PaNET Standard Operating Procedures

General procedure for handling issues in PaNET

Changes to PaNET ontology are triggered by resolving an issue in github. Other than in exceptional circumstances, it should be possible to trace any change in the PaNET ontology back to a corresponding issue that is being addressed.

The issue is created by someone who has found (or believes they have found) a problem with PaNET. The issue's description (provided by the person submitting the issue) indicates what problem they are trying to resolve. The description may propose a change to the ontology (e.g., add a new term, retire a term). Any such proposal change should be taken as a hint: the important part is to resolve the underlying problem, which may be best achieved by doing something other than what is proposed.

The issue is assigned to someone who is responsible for that issue: the issue resolver. That person is responsible for closing that ticket. Should the person be unable to do that (e.g., currently insufficient spare time, left the facility) then another person should be assigned.

The issue resolver should look at the description and try to understand the underlying problem. Often the description is incomplete and doesn't provide sufficient information to fully understand the underlying problem. If so, the issue resolver should pose questions (through the github issue) to better understand the problem.

Once the problem is understood, there should be a decision whether the underlying problem is something that fits within PaNET's remit. If this is unclear, the issuer resolver may seek a consensus opinion from the PaNET maintenance team (via email or at the next meeting).

If the underlying problem does not fit within PaNET's remit then the issue resolver will update the issue, writing a description of why the problem falls outside PaNET's remit, and close the issue.

If the underlying problem fits within PaNET's remit then the issue resolver should understand how best to resolve the problem. Any suggestion (in the issue description) may be considered, but other possibilities should also be considered. If this is unclear then the issue resolver may discuss this with other members of the PaNET maintenance team (either via mailing list or at a meeting).

Once the desired change is understood, the issue resolver will follow one or more of the procedures (described below) to update the ontology.

The issue will be closed automatically once the ontology is updated.

Naming convention

In PaNET we aim for consistent labels for terms. Therefore, when adding a new term or updating an existing term the labels should follow the naming convention described here.

The following rules were taken from Steve's comment:

Names are copied from existing sources wherever possible.
Adopted style is lower-case except for acronyms
We assume the names are not case-sensitive in order to avoid a proliferation of terms using different cases.
We assume that there is no significant preference for label over alt-label, i.e. all labels have the same importance.
Abbreviations and acronyms are treated as any other label/alt-label

Adding a new term/relationship

New terms or relationships are added to fix an inadequacy with the current ontology. Examples of such problems include the inability to make a distinction between two similar techniques when searching, or the inability to query a well-defined concept that encompasses multiple terms.

The motivation for adding a new term usually comes from following the "General procedure for handling issues in PaNET" (see above).

The issue resolver will need to understand the exact nature of the new term or the new relationship. For terms, this involves writing an appropriate description, identifying the relationships with existing PaNET terms, and potentially finding links to related terms in other corpora. This process may involve contacting experts in the field to try to ensure a consensus in how this term is being defined.

As a general guideline, a new term should be a subclass of the classes that are the conceptually closest broader techniques. If any of these closest broader techniques classes have existing subclasses then those relationships are reviewed to see whether the new term should be added as an intermediate term between one of the closest broader techniques and the existing subclass.

In case the closest broader technique has a relation to a technique where the new term is when added the closest broader technique, the relation between the existing classes should be removed and the new technique should be put in between. To give a more concrete example, if PaNET contains two techniques A and B with A being a generalisation of B (in this example, written as A ← B) and a new term N is introduced where A ← N and N ← B then the existing relationship (A ← B) is removed when the two new relationships (A ← N and N ← B) are added.

Once the new term or relationship is understood, the issue resolver will update PaNET ontology following the general procedure for updating git, as described below.

Removing a term

A problematic term may be removed ONLY if it has not been released. In other words, a term may be removed only if it was added more recently than the most recent release.

If the term is present in one or more releases then the problematic term must be retired instead. See below, in the "Retiring a term" section, for more details.

Removing a term follows the procedure described in "general procedure for updating git" with the slight modification that the patch may be generated automatically, using the git revert command, rather than manually editing the corresponding files.

Care must be exercised when using the git revert command as it undoes everything done by a specific commit. If that commit does more than adding a term we want to get rid of, then an alternative approach may be needed.

Also, be aware that changes in the ontology after the new term was added may complicate the process of removing a term. This is most obvious if the git revert command indicates a conflict that must be resolved, but this is a more general problem. For example, if a term (term #1) is added that is subsequently discovered to be problematic and a later commit adds a new term (term #2) that is a child of term #1 then the commit removing term #1 will also need to handle the parent-child relationship between term #1 and term #2. Simply reverting the earlier patch that introduced term #1 (i.e., git revert) will not do this.

Retiring a term

This process is based on Geneontology's Principles for term obsoletion.

A term is retired because its presence is causing a problem in the PaNET ontology. For example, the term may be badly defined, allowing multiple mutually incompatible interpretations on to what the term refers.

Released terms are never removed.

More specifically, the PaNET maintenance team guarantees that any IRI corresponding to a technique that is available in one release will exist in all subsequent releases (see below on releasing).

Retiring a term is the process of adhering to this promise while, at the same time, acknowledging that a specific term should not be used any more.

Retiring a term involves removing all its links within the ontology and adding an annotation to indicate the term is obsolete.

In some cases it is desirable to "simultaneously" retire a term while creating a new term. An example is when an existing term is badly defined: the existing term (with a bad definition) is retired while a new term (with a better definition) is added. Such a change in behaviour should be done as a single git commit, in order to indicate the close connection between these two activities.

Once the desired changes are understood, the issue resolver updates the git repo, as described in the "general procedure for updating git" section below.

Removing or modifying a relationship

Unlike terms, relationships are not guaranteed from release to release: they may be modified, as we correct problems and introduce new terms. Therefore, any problematic connections may be simply modified or removed, as appropriate.

Any changes to the relationship should be motivated by solving some concrete problem. That problem should be described in a GitHub issue. Ideally, the issue should describe some user-facing problem (e.g., when searching for X, I receive results like Y even those they are not appropriate). In practice, when the underlying problem is obvious, the issue may state simply that the relationship is wrong.

There are situations where multiple changes are necessary; for example, if a relationship is wrong then fixing the problem may involve removing the existing relationship and adding a new relationship. When multiple changes are motivated from solving the same underlying problem then those changes should be provided as a single git commit.

Once the problem is suitably investigated and the desired modification to the ontology is well understood, general procedure for updating git is followed.