Merge branch 'master' into feat/json-schema

Author: ivan-aksamentov

docs/user/assets/web_aaMotifs.png

@@ -63,7 +63,6 @@ Example configuration for SARS-CoV-2:
 ```json
 {
   "qc": {
-    "schemaVersion": "1.2.0",
     "privateMutations": {
       "enabled": true,
       "typical": 8,
@@ -131,8 +130,10 @@ Example:
 
 ```json
 {
-  "cli": "3.0.0",
-  "web": "3.0.0"
+  "compatibility": {
+    "cli": "3.0.0",
+    "web": "3.0.0"
+  }
 }
 ```
 
@@ -142,7 +143,7 @@ Optional `str`. The default gene/CDS to be shown in Nextclade web. If not provid
 
 #### `cdsOrderPreference`
 
-Optional `array[str]`. Order in which genes are shown in Nextclade web dropdown. Example value ["S", "ORF1a", "N", "E"]
+Optional `array[str]`. Order in which genes are shown in Nextclade web dropdown. Example value `["S", "ORF1a", "N", "E"]`
 
 #### `generalParams`
 
@@ -158,25 +159,114 @@ Optional `dict`. Parameters for the alignment algorithm. These are identical to
 
 #### `treeBuilderParams`
 
-Optional `dict`. Parameters for the tree building algorithm. These are identical to the corresponding CLI arguments (though here _camelCase_ needs to be used. If not provided, default values are used.
+Optional `dict`. Parameters for the tree building algorithm. These are identical to the corresponding CLI arguments (though here _camelCase_ needs to be used). If not provided, default values are used.
 
 - `withoutGreedyTreeBuilder`: If you don't want to use the greedy tree builder, set this to `true`. Default: `false`.
 - `maskedMutsWeight`: Parsimony weight for masked mutations. Default: `0.05`.
 
-#### `primers`
 
-TODO
+#### Calculate phenotypic scores from mutations (`phenotypeData`)
 
-#### `phenotypeData`
+Nextclade can calculate numerical scores derived from mutations in a query sequence relative to the reference sequence.
+Such scores could for example be used to calculate predicted ACE2 binding for SARS-CoV-2, immune escape estimates, or potential drug resistance. To specify such numerical scores, the field `phenotypeData` needs to be added to the `pathogen.json`.
 
-TODO
+Each such score is based on exactly one CDS and each amino acid mutation can be assigned a specific contribution to the score.
+In addition, a "default" value can be specified for amino acid mutations that are not explicitly listed.
+```json
+{
+  "phenotypeData": [
+    {
+      "aaRange": {
+        "begin": 330,
+        "end": 531
+      },
+      "description": "Estimated ACE2 binding",
+      "cds": "S",
+      "ignore": {
+        "clades": ["outgroup"]
+      },
+      "name": "ace2_binding",
+      "nameFriendly": "ACE2 binding",
+      "data": [
+        {
+          "name": "binding",
+          "weight": 1.0,
+          "locations": {
+            "330": {
+              "default": 0.1,
+              "A": -0.08339,
+              "C": -0.61624,
+              "D": -0.1467,
+              "E": -0.14146,
+              ...
+            },
+            "331": {}
+            ...
+          }
+        }
+      ]
+    }
+  ]
+}
+```
+If the score is only relevant for specific clades, you can specify which clades are to be ignored.
+
+#### Amino acid motif detection (`aaMotifs`)
+
+Nextclade can detect and report specific motifs in translated amino acid sequences. This feature is currently being used to highlight changes in glycosylation or cleavage sites, but the feature itself is generic.
+To use this feature, you need to add a `aaMotifs` field to the `pathogen.json`.
 
-#### `aaMotifs`
+Amino acid motifs can be specified using regular expressions and the parts of the genome in which Nextclade searches for the motifs is specified by listing the CDS and (optional) ranges within these CDSs (e.g.~to restrict to the exposed part of a protein).
+An example of a full configuration (for glycosylation in influenza HA) is shown below.
+```json
+  "aaMotifs": [
+    {
+      "name": "glycosylation",
+      "nameShort": "Glyc.",
+      "nameFriendly": "Glycosylation",
+      "description": "N-linked glycosylation motifs (N-X-S/T with X any amino acid other than P)",
+      "includeCdses": [
+        {
+          "cds":"HA1",
+          "ranges":[]
+        },
+        {
+          "cds":"HA2",
+          "ranges":[{"begin":0, "end":186}]
+        }
+      ],
+      "motifs": [
+        "N[^P][ST]"
+      ]
+    }
+  ]
+```
+In the web interface, motifs are reported as shown in the screenshot below:
+![aaMotifs](../assets/web_aaMotifs.png)
+
+#### Labelling mutations of interest (`mutLabels`)
+
+Nextclade can highlight specific mutations to the user, for example mutations that are indicative of contamination, drug resistance, or otherwise of particular interest.
+To do so, you can specify mutations as "labeled" using the `mutLabels` field in the `pathogenJson`.
+Labeled mutations are only searched among the "private" mutations, i.e. mutations in query sequences that are not found in the part of the reference tree the query sequence attaches to.
+
+The json specification looks as follows
+```json
+{
+  "mutLabels": {
+    "nucMutLabelMap": {
+      "174T": ["20H", ...],
+      "204T": ["20E"],
+      ...
+    }
+  }
+}
+```
+Labeled "private" mutations are shown in the tool-tip of the mutation column when mutations "relative to parent" are shown (private mutations) and exported into the tabular output.
 
-TODO
+TODO: add amino acid mutations once released.
 
-#### `mutLabels`
+> ⚠️ Note that the specification of these mutations breaks with the convention of zero-indexing. Instead, these labeled mutations are one-indexed and directly correspond to the mutations displayed in the UI or in the tables.
 
-TODO
 
 > 💡 Nextclade CLI supports file compression and reading from standard input. See section [Compression, stdin](./compression.md) for more details.