Add mutations endpoint

.gitignore

@@ -22,3 +22,6 @@ dist/
 
 # Coverage
 .coverage
+
+# project
+output.log

README.md

@@ -134,14 +134,15 @@ scop3p --accession O95755 --no-cache
 # Set custom cache TTL (in seconds)
 scop3p --accession O95755 --cache-ttl 600
 
-# Include structures and peptides in stdout JSON (no saved files)
-scop3p --accession O95755 --include-structures --include-peptides
+# Include structures, peptides, and mutations in stdout JSON (no saved files)
+scop3p --accession O95755 --include-structures --include-peptides --include-mutations
 
 # Save multiple outputs in one invocation (TARGET:FORMAT:PATH)
 scop3p --accession O95755 \
   --save modifications:tsv:modifications.tsv \
   --save structures:tsv:structures.tsv \
-  --save peptides:json:peptides.json
+  --save peptides:json:peptides.json \
+  --save mutations:tsv:mutations.tsv
 
 # Save one output file (same --save syntax)
 scop3p --accession O95755 --save modifications:json:results.json
@@ -156,8 +157,9 @@ PYTHONPATH=./src python -m scop3p_api_client phospho --accession O95755
 **Important Notes:**
 
 - **Structures TSV Format**: The structures data is nested in the JSON response (each structure contains a `structureModificationsList`). When exporting to TSV, the data is automatically flattened - one row per modification with structure-level fields (pdbId, resolution, etc.) repeated for each modification.
-- **Automatic endpoint selection**: requesting `structures` or `peptides` via `--save` automatically fetches those datasets.
-- **Stdout enrichment**: use `--include-structures` and/or `--include-peptides` to include them in stdout JSON when not saving files.
+- **Mutations columns and sort**: mutations tabular output uses `position`, `pdbIds`, `referenceAA`, `altAA`, `type`, `disease` and sorts rows by `position`, then `referenceAA`, then `altAA`, then `type`.
+- **Automatic endpoint selection**: requesting `structures`, `peptides`, or `mutations` via `--save` automatically fetches those datasets.
+- **Stdout enrichment**: use `--include-structures`, `--include-peptides`, and/or `--include-mutations` to include them in stdout JSON when not saving files.
 - **Dataset JSON saves**: `--save TARGET:json:PATH` writes the normalized dataset payload for that target only (not the full `apiResult + metadata` envelope).
 
 **CLI Arguments:**
@@ -166,8 +168,9 @@ PYTHONPATH=./src python -m scop3p_api_client phospho --accession O95755
 - `--api-version` / `-v`: Optional API version query parameter
 - `--include-structures`: Include structures in stdout JSON output
 - `--include-peptides`: Include peptides in stdout JSON output
+- `--include-mutations`: Include mutations in stdout JSON output
 - `--save`: Repeatable output specification `TARGET:FORMAT:PATH`
-  - `TARGET`: `modifications`, `structures`, `peptides`
+  - `TARGET`: `modifications`, `structures`, `peptides`, `mutations`
   - `FORMAT`: `json`, `tsv`
 - `--raw`: Output compact JSON (used for stdout and `json` saves)
 - `--indent`: JSON indentation size (default: 2, ignored when `--raw` is set)
@@ -254,11 +257,12 @@ result = Scop3pResult.from_api(
     accession="O95755"
 )
 
-# Include structures and peptides
+# Include structures, peptides, and mutations
 result = Scop3pResult.from_api(
     accession="O95755",
     include_structures=True,
-    include_peptides=True
+    include_peptides=True,
+    include_mutations=True
 )
 
 # With API version and custom cache TTL
@@ -278,6 +282,7 @@ result = Scop3pResult.from_api(
 print(result.modifications)
 print(result.structures)  # None if not requested
 print(result.peptides)    # None if not requested
+print(result.mutations)   # None if not requested
 print(result.metadata)
 
 # Convert to dictionary
@@ -301,6 +306,7 @@ from scop3p_api_client.result import Scop3pResult
 from scop3p_api_client.output import (
     Scop3pResultJSONOutput,
     Scop3pResultModificationsTabularOutput,
+    Scop3pResultMutationsTabularOutput,
     Scop3pResultStructuresTabularOutput,
     Scop3pResultPeptidesTabularOutput,
 )
@@ -309,7 +315,8 @@ from scop3p_api_client.output import (
 result = Scop3pResult.from_api(
     accession="O95755",
     include_structures=True,
-    include_peptides=True
+    include_peptides=True,
+    include_mutations=True
 )
 
 # JSON output
@@ -341,6 +348,14 @@ pep_formatter = Scop3pResultPeptidesTabularOutput(
     include_header=False
 )
 pep_formatter.print_to_console()
+
+# Mutations as TSV
+mut_formatter = Scop3pResultMutationsTabularOutput(
+    result,
+    separator="\t",
+    include_header=True
+)
+mut_formatter.write_to_file("mutations.tsv")
 ```
 
 **Low-level API usage:**
@@ -351,16 +366,19 @@ The procedural helpers now wrap an underlying `Scop3pRestApi` instance. You can
 from scop3p_api_client.api import (
     Scop3pRestApi,
     fetch_modifications,
+    fetch_mutations,
     fetch_structures,
     fetch_peptides,
 )
 
 api = Scop3pRestApi()
 data = api.fetch_modifications("O95755")
 peptides, peptides_meta = api.fetch_peptides("O95755", return_metadata=True)
+mutations, mutations_meta = api.fetch_mutations("O95755", return_metadata=True)
 
 # Or keep using the functional wrappers
 structures = fetch_structures("O95755")
+mutations = fetch_mutations("O95755")
 ```
 
 ---

docs/examples.md

@@ -75,6 +75,14 @@ ABCDEFG	1	7	None	5	None	D	None	None	None	None
 HIJKLMN	10	16	None	12	None	L	None	None	None	None
 ```
 
+## Mutations TSV Example
+
+```tsv
+position	pdbIds	referenceAA	altAA	type	disease
+326	{}	R	A	Disease	Other disease
+326	['1ABC', '2XYZ']	R	H	Disease	Mental retardation
+```
+
 ## FAIR Provenance Log Example
 
 Example from `output.log`:
@@ -110,7 +118,8 @@ Example from `output.log`:
       "api_endpoints": [
         "https://iomics.ugent.be/scop3p/api/modifications",
         "https://iomics.ugent.be/scop3p/api/get-structures-modifications",
-        "https://iomics.ugent.be/scop3p/api/get-peptides-modifications"
+        "https://iomics.ugent.be/scop3p/api/get-peptides-modifications",
+        "https://iomics.ugent.be/scop3p/api/get-mutations"
       ]
     },
     "interoperable": {
@@ -127,8 +136,9 @@ Example from `output.log`:
 ## Reproduce Locally
 
 ```bash
-scop3p --accession O95755 --include-structures --include-peptides
+scop3p --accession O95755 --include-structures --include-peptides --include-mutations
 scop3p --accession O95755 --save modifications:tsv:modifications.tsv
 scop3p --accession O95755 --save structures:tsv:structures.tsv
 scop3p --accession O95755 --save peptides:tsv:peptides.tsv
+scop3p --accession O95755 --save mutations:tsv:mutations.tsv
 ```

docs/getting-started.md

@@ -39,10 +39,10 @@ Use a specific API version for modifications:
 scop3p --accession O95755 --api-version 1
 ```
 
-Include structures and peptides in standard output JSON:
+Include structures, peptides, and mutations in standard output JSON:
 
 ```bash
-scop3p --accession O95755 --include-structures --include-peptides
+scop3p --accession O95755 --include-structures --include-peptides --include-mutations
 ```
 
 Save additional files in one run:
@@ -51,7 +51,8 @@ Save additional files in one run:
 scop3p --accession O95755 \
   --save modifications:tsv:modifications.tsv \
   --save structures:tsv:structures.tsv \
-  --save peptides:json:peptides.json
+  --save peptides:json:peptides.json \
+  --save mutations:tsv:mutations.tsv
 ```
 
 ## Cache Controls
@@ -87,8 +88,9 @@ scop3p --accession O95755 --log-file run-fair.log --raw
 
 ## What `--save` Supports
 
-- Targets: `modifications`, `structures`, `peptides`
+- Targets: `modifications`, `structures`, `peptides`, `mutations`
 - Formats: `json`, `tsv`
+- Mutations TSV columns: `position`, `pdbIds`, `referenceAA`, `altAA`, `type`, `disease`
 
 Examples:
 

docs/index.md

@@ -37,3 +37,4 @@ This documentation covers:
 - `https://iomics.ugent.be/scop3p/api/modifications`
 - `https://iomics.ugent.be/scop3p/api/get-structures-modifications`
 - `https://iomics.ugent.be/scop3p/api/get-peptides-modifications`
+- `https://iomics.ugent.be/scop3p/api/get-mutations`

docs/methodology.md

@@ -27,11 +27,12 @@ flowchart LR
 - Modifications: `https://iomics.ugent.be/scop3p/api/modifications`
 - Structures: `https://iomics.ugent.be/scop3p/api/get-structures-modifications`
 - Peptides: `https://iomics.ugent.be/scop3p/api/get-peptides-modifications`
+- Mutations: `https://iomics.ugent.be/scop3p/api/get-mutations`
 
 URL behavior:
 
 - Modifications URL is built as `?accession=<id>` and optionally `&version=<api_version>`.
-- Structures and peptides use `?accession=<id>`.
+- Structures, peptides, and mutations use `?accession=<id>`.
 
 ## `requests` Behavior
 
@@ -47,7 +48,7 @@ Cache key material:
 
 - `accession`
 - `api_version` (modifications only)
-- dataset suffix (`modifications`, `structures`, `peptides`)
+- dataset suffix (`modifications`, `structures`, `peptides`, `mutations`)
 
 Cache file name:
 
@@ -91,6 +92,7 @@ Before serialization, payloads are normalized for stable order:
 
 - predictable column/key ordering for known datasets
 - deterministic row sorting by dataset primary keys
+- mutations sorted by `position`, then `referenceAA`, then `altAA`, then `type`
 
 Structures TSV behavior:
 

docs/python-api.md

@@ -19,6 +19,7 @@ result = Scop3pResult.from_api(
     ttl=600,                  # cache TTL in seconds
     include_structures=True,  # optional
     include_peptides=True,    # optional
+    include_mutations=True,   # optional
 )
 ```
 
@@ -36,7 +37,8 @@ Envelope shape:
   "apiResult": {
     "modifications": {},
     "structures": [],
-    "peptides": []
+    "peptides": [],
+    "mutations": []
   },
   "metadata": {}
 }
@@ -66,6 +68,11 @@ peptides, peptides_meta = api.fetch_peptides(
     accession="O95755",
     return_metadata=True,
 )
+
+mutations, mutations_meta = api.fetch_mutations(
+    accession="O95755",
+    return_metadata=True,
+)
 ```
 
 `return_metadata=True` includes source and cache metadata for each fetch.
@@ -77,6 +84,7 @@ The module also exports backward-compatible wrappers:
 - `fetch_modifications(...)`
 - `fetch_structures(...)`
 - `fetch_peptides(...)`
+- `fetch_mutations(...)`
 
 These forward arguments to a shared default `Scop3pRestApi` instance.
 

examples/output_formats_demo.py

@@ -5,6 +5,7 @@
 from scop3p_api_client.output import (
     Scop3pResultJSONOutput,
     Scop3pResultModificationsTabularOutput,
+    Scop3pResultMutationsTabularOutput,
     Scop3pResultStructuresTabularOutput,
     Scop3pResultPeptidesTabularOutput,
 )
@@ -19,6 +20,7 @@ def main():
         accession="O95755",
         include_structures=True,
         include_peptides=True,
+        include_mutations=True,
         ttl=300
     )
 
@@ -67,6 +69,19 @@ def main():
         pep_lines = pep_output.split("\n")[:10]
         print("\n".join(pep_lines))
 
+    if result.mutations:
+        print("\n" + "="*80)
+        print("Mutations TSV (first 10 lines):")
+        print("="*80)
+        mut_formatter = Scop3pResultMutationsTabularOutput(
+            result,
+            separator="\t",
+            include_header=True
+        )
+        mut_output = mut_formatter.format()
+        mut_lines = mut_output.split("\n")[:10]
+        print("\n".join(mut_lines))
+
     print("\n" + "="*80)
     print("Example: Saving to files")
     print("="*80)
@@ -76,6 +91,7 @@ def main():
     # mods_formatter.write_to_file("modifications.tsv")
     # struct_formatter.write_to_file("structures.tsv")
     # pep_formatter.write_to_file("peptides.tsv")
+    # mut_formatter.write_to_file("mutations.tsv")
 
     print("To save outputs, uncomment the write_to_file() calls in the script.")
     print("\nDone!")

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "scop3p"
-version = "1.0.1"
+version = "1.1.0"
 description = "The official Scop3P REST API Python client"
 readme = "README.md"
 requires-python = ">=3.6,<4"