Oncodrive3D 1.0.7__tar.gz → 1.0.8__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (71) hide show
  1. oncodrive3d-1.0.8/.github/workflows/release-publish.yml +225 -0
  2. {oncodrive3d-1.0.7 → oncodrive3d-1.0.8}/Dockerfile +20 -14
  3. {oncodrive3d-1.0.7 → oncodrive3d-1.0.8}/PKG-INFO +60 -36
  4. {oncodrive3d-1.0.7 → oncodrive3d-1.0.8}/README.md +59 -35
  5. oncodrive3d-1.0.8/docs/annotations_plotting.md +170 -0
  6. oncodrive3d-1.0.8/docs/mutability.md +110 -0
  7. {oncodrive3d-1.0.7 → oncodrive3d-1.0.8}/oncodrive3d_pipeline/README.md +37 -5
  8. {oncodrive3d-1.0.7 → oncodrive3d-1.0.8}/oncodrive3d_pipeline/conf/test.config +18 -3
  9. {oncodrive3d-1.0.7 → oncodrive3d-1.0.8}/oncodrive3d_pipeline/modules/o3d_chimerax_plot.nf +0 -3
  10. {oncodrive3d-1.0.7 → oncodrive3d-1.0.8}/oncodrive3d_pipeline/modules/o3d_plot.nf +0 -3
  11. {oncodrive3d-1.0.7 → oncodrive3d-1.0.8}/oncodrive3d_pipeline/modules/o3d_run.nf +1 -5
  12. oncodrive3d-1.0.8/oncodrive3d_pipeline/nextflow.config +164 -0
  13. {oncodrive3d-1.0.7 → oncodrive3d-1.0.8}/scripts/__init__.py +1 -1
  14. {oncodrive3d-1.0.7 → oncodrive3d-1.0.8}/scripts/datasets/af_merge.py +20 -3
  15. {oncodrive3d-1.0.7 → oncodrive3d-1.0.8}/scripts/datasets/build_datasets.py +51 -23
  16. {oncodrive3d-1.0.7 → oncodrive3d-1.0.8}/scripts/datasets/custom_pdb.py +34 -4
  17. {oncodrive3d-1.0.7 → oncodrive3d-1.0.8}/scripts/datasets/get_pae.py +47 -7
  18. oncodrive3d-1.0.8/scripts/datasets/seq_for_mut_prob.py +1695 -0
  19. {oncodrive3d-1.0.7 → oncodrive3d-1.0.8}/scripts/datasets/utils.py +4 -4
  20. {oncodrive3d-1.0.7 → oncodrive3d-1.0.8}/scripts/main.py +10 -10
  21. {oncodrive3d-1.0.7 → oncodrive3d-1.0.8}/scripts/run/clustering.py +2 -2
  22. oncodrive3d-1.0.8/tools/preprocessing/README.md +200 -0
  23. oncodrive3d-1.0.8/tools/preprocessing/config.yaml +7 -0
  24. oncodrive3d-1.0.8/tools/preprocessing/parse_alphafold_predictions.py +102 -0
  25. {oncodrive3d-1.0.7 → oncodrive3d-1.0.8}/tools/preprocessing/prepare_samplesheet.py +19 -23
  26. oncodrive3d-1.0.8/tools/preprocessing/pyproject.toml +16 -0
  27. oncodrive3d-1.0.8/tools/preprocessing/sitecustomize.py +5 -0
  28. oncodrive3d-1.0.8/tools/preprocessing/update_samplesheet_and_structures.py +960 -0
  29. {oncodrive3d-1.0.7 → oncodrive3d-1.0.8}/uv.lock +887 -888
  30. oncodrive3d-1.0.7/oncodrive3d_pipeline/conf/base.config +0 -39
  31. oncodrive3d-1.0.7/oncodrive3d_pipeline/nextflow.config +0 -145
  32. oncodrive3d-1.0.7/scripts/datasets/seq_for_mut_prob.py +0 -1031
  33. {oncodrive3d-1.0.7 → oncodrive3d-1.0.8}/.gitignore +0 -0
  34. {oncodrive3d-1.0.7 → oncodrive3d-1.0.8}/.python-version +0 -0
  35. {oncodrive3d-1.0.7 → oncodrive3d-1.0.8}/LICENSE +0 -0
  36. {oncodrive3d-1.0.7 → oncodrive3d-1.0.8}/docs/build_output.md +0 -0
  37. {oncodrive3d-1.0.7 → oncodrive3d-1.0.8}/docs/images/graphical_abstract.png +0 -0
  38. {oncodrive3d-1.0.7 → oncodrive3d-1.0.8}/docs/run_input_output.md +0 -0
  39. {oncodrive3d-1.0.7 → oncodrive3d-1.0.8}/oncodrive3d_pipeline/main.nf +0 -0
  40. {oncodrive3d-1.0.7 → oncodrive3d-1.0.8}/oncodrive3d_pipeline/validation.nf +0 -0
  41. {oncodrive3d-1.0.7 → oncodrive3d-1.0.8}/oncodrive3d_pipeline/workflows/oncodrive3d.nf +0 -0
  42. {oncodrive3d-1.0.7 → oncodrive3d-1.0.8}/pyproject.toml +0 -0
  43. {oncodrive3d-1.0.7 → oncodrive3d-1.0.8}/scripts/clustering_3d.code-workspace +0 -0
  44. {oncodrive3d-1.0.7 → oncodrive3d-1.0.8}/scripts/datasets/__init__.py +0 -0
  45. {oncodrive3d-1.0.7 → oncodrive3d-1.0.8}/scripts/datasets/get_structures.py +0 -0
  46. {oncodrive3d-1.0.7 → oncodrive3d-1.0.8}/scripts/datasets/model_confidence.py +0 -0
  47. {oncodrive3d-1.0.7 → oncodrive3d-1.0.8}/scripts/datasets/parse_pae.py +0 -0
  48. {oncodrive3d-1.0.7 → oncodrive3d-1.0.8}/scripts/datasets/prob_contact_maps.py +0 -0
  49. {oncodrive3d-1.0.7 → oncodrive3d-1.0.8}/scripts/globals.py +0 -0
  50. {oncodrive3d-1.0.7 → oncodrive3d-1.0.8}/scripts/plotting/__init__.py +0 -0
  51. {oncodrive3d-1.0.7 → oncodrive3d-1.0.8}/scripts/plotting/build_annotations.py +0 -0
  52. {oncodrive3d-1.0.7 → oncodrive3d-1.0.8}/scripts/plotting/chimerax_plot.py +0 -0
  53. {oncodrive3d-1.0.7 → oncodrive3d-1.0.8}/scripts/plotting/pdb_tool.py +0 -0
  54. {oncodrive3d-1.0.7 → oncodrive3d-1.0.8}/scripts/plotting/pfam.py +0 -0
  55. {oncodrive3d-1.0.7 → oncodrive3d-1.0.8}/scripts/plotting/plot.py +0 -0
  56. {oncodrive3d-1.0.7 → oncodrive3d-1.0.8}/scripts/plotting/stability_change.py +0 -0
  57. {oncodrive3d-1.0.7 → oncodrive3d-1.0.8}/scripts/plotting/uniprot_feat.py +0 -0
  58. {oncodrive3d-1.0.7 → oncodrive3d-1.0.8}/scripts/plotting/utils.py +0 -0
  59. {oncodrive3d-1.0.7 → oncodrive3d-1.0.8}/scripts/run/__init__.py +0 -0
  60. {oncodrive3d-1.0.7 → oncodrive3d-1.0.8}/scripts/run/communities.py +0 -0
  61. {oncodrive3d-1.0.7 → oncodrive3d-1.0.8}/scripts/run/miss_mut_prob.py +0 -0
  62. {oncodrive3d-1.0.7 → oncodrive3d-1.0.8}/scripts/run/mutability.py +0 -0
  63. {oncodrive3d-1.0.7 → oncodrive3d-1.0.8}/scripts/run/pvalues.py +0 -0
  64. {oncodrive3d-1.0.7 → oncodrive3d-1.0.8}/scripts/run/score_and_simulations.py +0 -0
  65. {oncodrive3d-1.0.7 → oncodrive3d-1.0.8}/scripts/run/utils.py +0 -0
  66. {oncodrive3d-1.0.7 → oncodrive3d-1.0.8}/test/input/maf/TCGA_WXS_ACC.in.maf +0 -0
  67. {oncodrive3d-1.0.7 → oncodrive3d-1.0.8}/test/input/maf/TCGA_WXS_PAAD.in.maf +0 -0
  68. {oncodrive3d-1.0.7 → oncodrive3d-1.0.8}/test/input/mut_profile/TCGA_WXS_ACC.sig.json +0 -0
  69. {oncodrive3d-1.0.7 → oncodrive3d-1.0.8}/test/input/mut_profile/TCGA_WXS_PAAD.sig.json +0 -0
  70. {oncodrive3d-1.0.7 → oncodrive3d-1.0.8}/test/input/vep/TCGA_WXS_ACC.vep.tsv.gz +0 -0
  71. {oncodrive3d-1.0.7 → oncodrive3d-1.0.8}/test/input/vep/TCGA_WXS_PAAD.vep.tsv.gz +0 -0
@@ -0,0 +1,225 @@
1
+ name: release-publish
2
+
3
+ on:
4
+ release:
5
+ types:
6
+ - published
7
+
8
+ permissions:
9
+ contents: read
10
+
11
+
12
+ jobs:
13
+ validate-and-build:
14
+ name: Validate Version And Build Dist
15
+ runs-on: ubuntu-latest
16
+ outputs:
17
+ version: ${{ steps.version_check.outputs.version }}
18
+ tag_name: ${{ steps.version_check.outputs.tag_name }}
19
+ steps:
20
+ - name: Checkout
21
+ uses: actions/checkout@v4
22
+ with:
23
+ fetch-depth: 0
24
+
25
+ - name: Set Up Python
26
+ uses: actions/setup-python@v5
27
+ with:
28
+ python-version: '3.10'
29
+
30
+ - name: Set Up uv
31
+ uses: astral-sh/setup-uv@v5
32
+
33
+ - name: Validate Tag Version And Bump
34
+ id: version_check
35
+ env:
36
+ TAG_NAME: ${{ github.event.release.tag_name }}
37
+ run: |
38
+ set -euo pipefail
39
+
40
+ if [[ -z "${TAG_NAME}" ]]; then
41
+ echo "Could not determine release tag."
42
+ exit 1
43
+ fi
44
+
45
+ TAG_VERSION="${TAG_NAME#v}"
46
+ if [[ "${TAG_VERSION}" == "${TAG_NAME}" ]]; then
47
+ echo "Release tag must start with 'v' (for example: v1.0.9)."
48
+ exit 1
49
+ fi
50
+
51
+ CURRENT_VERSION=$(python - <<'PY'
52
+ import pathlib
53
+ import re
54
+
55
+ init_file = pathlib.Path('scripts/__init__.py').read_text(encoding='utf-8')
56
+ match = re.search(r'__version__\s*=\s*["\']([^"\']+)["\']', init_file)
57
+ if not match:
58
+ raise SystemExit('Could not find __version__ in scripts/__init__.py')
59
+ print(match.group(1))
60
+ PY
61
+ )
62
+
63
+ if [[ "${CURRENT_VERSION}" != "${TAG_VERSION}" ]]; then
64
+ echo "Version mismatch: scripts/__init__.py has ${CURRENT_VERSION}, tag is ${TAG_VERSION}."
65
+ exit 1
66
+ fi
67
+
68
+ PREVIOUS_TAG=$(git tag --sort=-v:refname | grep -E '^v[0-9]+' | grep -vx "${TAG_NAME}" | head -n 1 || true)
69
+ if [[ -n "${PREVIOUS_TAG}" ]]; then
70
+ PREVIOUS_FILE=$(git show "${PREVIOUS_TAG}:scripts/__init__.py" 2>/dev/null || true)
71
+ PREVIOUS_VERSION=$(printf '%s\n' "${PREVIOUS_FILE}" | sed -nE "s/^__version__[[:space:]]*=[[:space:]]*['\"]([^'\"]+)['\"].*/\1/p" | head -n 1)
72
+
73
+ if [[ -n "${PREVIOUS_VERSION}" ]]; then
74
+ python - "${PREVIOUS_VERSION}" "${CURRENT_VERSION}" <<'PY'
75
+ import re
76
+ import sys
77
+
78
+ previous = sys.argv[1]
79
+ current = sys.argv[2]
80
+
81
+ semver_pattern = re.compile(r'^\d+\.\d+\.\d+$')
82
+ if not semver_pattern.match(previous) or not semver_pattern.match(current):
83
+ raise SystemExit(
84
+ f'Both versions must use MAJOR.MINOR.PATCH numeric format for bump check. '
85
+ f'Previous={previous}, Current={current}'
86
+ )
87
+
88
+ p = tuple(int(x) for x in previous.split('.'))
89
+ c = tuple(int(x) for x in current.split('.'))
90
+
91
+ if c <= p:
92
+ raise SystemExit(
93
+ f'Version not bumped. Current release version {current} must be greater than previous release {previous}.'
94
+ )
95
+
96
+ print(f'Version bump check passed: {previous} -> {current}')
97
+ PY
98
+ else
99
+ echo "Could not parse version from ${PREVIOUS_TAG}. Skipping bump comparison."
100
+ fi
101
+ else
102
+ echo "No previous v* tag found. Skipping bump comparison."
103
+ fi
104
+
105
+ echo "version=${CURRENT_VERSION}" >> "${GITHUB_OUTPUT}"
106
+ echo "tag_name=${TAG_NAME}" >> "${GITHUB_OUTPUT}"
107
+
108
+ - name: Build Distribution Packages
109
+ run: |
110
+ uv build
111
+
112
+ - name: Upload Distribution Artifacts
113
+ uses: actions/upload-artifact@v4
114
+ with:
115
+ name: python-dist
116
+ path: dist/*
117
+ if-no-files-found: error
118
+
119
+ publish-testpypi:
120
+ name: Publish To TestPyPI
121
+ runs-on: ubuntu-latest
122
+ needs: validate-and-build
123
+ steps:
124
+ - name: Download Distribution Artifacts
125
+ uses: actions/download-artifact@v4
126
+ with:
127
+ name: python-dist
128
+ path: dist
129
+
130
+ - name: Publish To TestPyPI
131
+ uses: pypa/gh-action-pypi-publish@release/v1
132
+ with:
133
+ repository-url: https://test.pypi.org/legacy/
134
+ user: __token__
135
+ password: ${{ secrets.TEST_PYPI_API_TOKEN }}
136
+ packages-dir: dist
137
+ skip-existing: true
138
+
139
+ smoke-test-testpypi:
140
+ name: Install And Smoke Test From TestPyPI
141
+ runs-on: ubuntu-latest
142
+ needs:
143
+ - validate-and-build
144
+ - publish-testpypi
145
+ steps:
146
+ - name: Set Up Python
147
+ uses: actions/setup-python@v5
148
+ with:
149
+ python-version: '3.10'
150
+
151
+ - name: Set Up uv
152
+ uses: astral-sh/setup-uv@v5
153
+
154
+ - name: Install Package From TestPyPI And Run Smoke Test
155
+ env:
156
+ VERSION: ${{ needs.validate-and-build.outputs.version }}
157
+ run: |
158
+ set -euo pipefail
159
+
160
+ uv venv .venv --python 3.10
161
+
162
+ for attempt in 1 2 3 4 5 6; do
163
+ if uv pip install --python .venv/bin/python --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple "oncodrive3d==${VERSION}"; then
164
+ break
165
+ fi
166
+
167
+ if [[ "${attempt}" == "6" ]]; then
168
+ echo "Failed to install oncodrive3d==${VERSION} from TestPyPI after retries."
169
+ exit 1
170
+ fi
171
+
172
+ echo "Package not available yet on TestPyPI (attempt ${attempt}/6). Retrying in 30s..."
173
+ sleep 30
174
+ done
175
+
176
+ .venv/bin/oncodrive3d --help >/dev/null
177
+
178
+ publish-pypi:
179
+ name: Publish To PyPI
180
+ runs-on: ubuntu-latest
181
+ needs:
182
+ - validate-and-build
183
+ - smoke-test-testpypi
184
+ steps:
185
+ - name: Download Distribution Artifacts
186
+ uses: actions/download-artifact@v4
187
+ with:
188
+ name: python-dist
189
+ path: dist
190
+
191
+ - name: Publish To PyPI
192
+ uses: pypa/gh-action-pypi-publish@release/v1
193
+ with:
194
+ user: __token__
195
+ password: ${{ secrets.PYPI_API_TOKEN }}
196
+ packages-dir: dist
197
+ skip-existing: true
198
+
199
+ publish-docker:
200
+ name: Build And Push Docker Image
201
+ runs-on: ubuntu-latest
202
+ needs:
203
+ - validate-and-build
204
+ - publish-pypi
205
+ steps:
206
+ - name: Checkout
207
+ uses: actions/checkout@v4
208
+
209
+ - name: Set Up Docker Buildx
210
+ uses: docker/setup-buildx-action@v3
211
+
212
+ - name: Log In To Docker Hub
213
+ uses: docker/login-action@v3
214
+ with:
215
+ registry: docker.io
216
+ username: ${{ secrets.DOCKERHUB_USERNAME }}
217
+ password: ${{ secrets.DOCKERHUB_TOKEN }}
218
+
219
+ - name: Build And Push Docker Image
220
+ uses: docker/build-push-action@v6
221
+ with:
222
+ context: .
223
+ file: ./Dockerfile
224
+ push: true
225
+ tags: docker.io/bbglab/oncodrive3d:${{ needs.validate-and-build.outputs.version }}
@@ -1,4 +1,5 @@
1
- FROM ghcr.io/astral-sh/uv:0.5-python3.10-bookworm AS build-stage
1
+ # syntax=docker/dockerfile:1.7
2
+ FROM ghcr.io/astral-sh/uv:0.9-python3.10-bookworm AS build-stage
2
3
 
3
4
  # Set environment variables
4
5
  ENV UV_COMPILE_BYTECODE=1 \
@@ -14,8 +15,8 @@ COPY scripts scripts
14
15
  COPY README.md README.md
15
16
 
16
17
  # Install dependencies and build the project
17
- RUN mkdir -p /root/.cache/uv \
18
- && uv sync --frozen --no-dev \
18
+ RUN --mount=type=cache,target=/root/.cache/uv \
19
+ uv sync --frozen --no-dev \
19
20
  && uv build
20
21
 
21
22
  # Second stage: Runtime image
@@ -25,13 +26,8 @@ FROM python:3.10.18-bookworm AS runtime-stage
25
26
  ENV BGDATA_LOCAL="/bgdatacache" \
26
27
  BBGLAB_HOME="/home/user/.config/bbglab/"
27
28
 
28
- # Copy oncodrive3d from the build stage
29
- COPY --from=build-stage /oncodrive3d/dist /oncodrive3d/dist
30
29
  WORKDIR /oncodrive3d
31
30
 
32
- # Install oncodrive3d
33
- RUN pip install dist/*.tar.gz
34
-
35
31
  # Create required directories
36
32
  RUN install -d -m 0755 "$BGDATA_LOCAL" "$BBGLAB_HOME"
37
33
 
@@ -52,16 +48,26 @@ remote_repository = \"https://bbglab.irbbarcelona.org/bgdata\"\n\
52
48
  [cache_repositories]" > "$BBGLAB_HOME/bgdatav2.conf"
53
49
 
54
50
  # Pre-fetch and prepare genome data
55
- RUN apt-get update && apt-get install -y curl \
56
- && pip install bgdata bgreference \
57
- && bgdata get datasets/genomereference/hg38 \
58
- && bgdata get datasets/genomereference/mm39 \
59
- && python3 -c "from bgreference import hg38; hg38(1, 1300000, 3000)" \
60
- && python3 -c "from bgreference import mm39; mm39(1, 1300000, 3000)" \
51
+ RUN apt-get update && apt-get install -y --no-install-recommends curl \
61
52
  && rm -rf /var/lib/apt/lists/*
62
53
 
54
+ RUN --mount=type=cache,target=/root/.cache/pip \
55
+ pip install bgdata bgreference
56
+
57
+ RUN bgdata get datasets/genomereference/hg38
58
+ RUN bgdata get datasets/genomereference/mm39
59
+
60
+ RUN python3 -c "from bgreference import hg38; hg38(1, 1300000, 3000)"
61
+ RUN python3 -c "from bgreference import mm39; mm39(1, 1300000, 3000)"
62
+
63
63
  # Set permissions for cache directory
64
64
  RUN chmod -R 0755 "$BGDATA_LOCAL"
65
65
 
66
+ # Copy and install oncodrive3d after data prefetch so package updates do not
67
+ # invalidate the expensive genome-data cache layers.
68
+ COPY --from=build-stage /oncodrive3d/dist /oncodrive3d/dist
69
+ RUN --mount=type=cache,target=/root/.cache/pip \
70
+ pip install dist/*.tar.gz
71
+
66
72
  # Set entrypoint (optional)
67
73
  CMD ["python3"]
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: Oncodrive3D
3
- Version: 1.0.7
3
+ Version: 1.0.8
4
4
  Summary: Oncodrive3D is a method designed to analyse patterns of somatic mutations across tumors to identify three-dimensional (3D) clusters of missense mutations and detect genes that are under positive selection.
5
5
  Project-URL: Homepage, https://github.com/bbglab/clustering_3d
6
6
  Project-URL: Repository, https://github.com/bbglab/clustering_3d
@@ -45,8 +45,6 @@ The method leverages **AlphaFold 2-predicted protein structures** and Predicted
45
45
 
46
46
  ![Graphical abstract of Oncodrive3D](docs/images/graphical_abstract.png "Oncodrive3D")
47
47
 
48
- ---
49
-
50
48
  ## Requirements
51
49
 
52
50
  Before you begin, ensure **Python 3.10 or later** is installed on your system.
@@ -55,7 +53,7 @@ Additionally, you may need to install additional development tools. Depending on
55
53
  - If you have sudo privileges:
56
54
 
57
55
  ```bash
58
- sudo apt install built-essential
56
+ sudo apt install build-essential
59
57
  ```
60
58
 
61
59
  - For HPC cluster environment, it is recommended to use [Conda](https://docs.conda.io/projects/conda/en/latest/user-guide/install/index.html) (or [Mamba](https://mamba.readthedocs.io/en/latest/)):
@@ -94,13 +92,22 @@ Additionally, you may need to install additional development tools. Depending on
94
92
 
95
93
  ## Building Datasets
96
94
 
97
- This step build the datasets necessary for Oncodrive3D to run the 3D clustering analysis. It is required once after installation or whenever you need to generate datasets for a different organism or apply a specific threshold to define amino acid contacts.
95
+ This step builds the datasets necessary for Oncodrive3D to run the 3D clustering analysis. It is required once after installation or whenever you need to generate datasets for a different organism or apply a specific threshold to define amino acid contacts.
98
96
 
99
97
  > [!WARNING]
100
98
  > This step is highly time- and resource-intensive, requiring a significant amount of free disk space and computational power. It will download and process a large amount of data. Ensure sufficient resources are available before proceeding, as insufficient capacity may result in extended runtimes or processing failures.
99
+ >
100
+ > Reliable internet access is required because AlphaFold structures, Ensembl annotations, Pfam files, and other resources are downloaded on demand during the build.
101
+
102
+ > [!WARNING]
103
+ > Human datasets built with the default settings pull canonical transcript metadata from the January 2024 Ensembl archive (release 111 / GENCODE v45). For maximum compatibility, annotate your input variants with the same Ensembl/Gencode release or supply the unfiltered VEP output together with `--o3d_transcripts --use_input_symbols`.
104
+
105
+ > [!NOTE]
106
+ > Predicted Aligned Error (PAE) files for older AlphaFold DB versions (e.g., v4) are no longer hosted after 2025. If you need PAE for an older AF version, download and supply them locally via `--custom_pae_dir`.
107
+ > MANE structures are available only in AlphaFold DB v4, while non-MANE builds default to v6. Since MANE mode forces v4 structures, you should also supply the corresponding PAE files through `--custom_pae_dir`.
101
108
 
102
109
  > [!NOTE]
103
- > The first time that you run Oncodrive3D building dataset step with a given reference genome, it will download it from our servers. By default the downloaded datasets go to`~/.bgdata`. If you want to move these datasets to another folder you have to define the system environment variable `BGDATA_LOCAL` with an export command.
110
+ > The first time that you run Oncodrive3D building dataset step with a given reference genome, it will download it from our servers. By default the downloaded datasets go to `~/.bgdata`. If you want to move these datasets to another folder you have to define the system environment variable `BGDATA_LOCAL` with an export command.
104
111
 
105
112
  ```
106
113
  Usage: oncodrive3d build-datasets [OPTIONS]
@@ -115,13 +122,16 @@ Examples:
115
122
  Options:
116
123
  -o, --output_dir PATH Path to the directory where the output files will be saved.
117
124
  Default: ./datasets/
118
- -s, --organism PATH Specifies the organism (`human` or `mouse`).
119
- Default: human
125
+ -s, --organism TEXT Specifies the organism (`human` or `mouse`; also accepts `Homo sapiens` / `Mus musculus`).
126
+ Default: Homo sapiens
120
127
  -m, --mane Use structures predicted from MANE Select transcripts
121
128
  (applicable to Homo sapiens only).
122
129
  -M, --mane_only Use only structures predicted from MANE Select transcripts
123
130
  (applicable to Homo sapiens only).
124
- -C, --custom_mane_pdb_dir Path to directory containing custom MANE PDB structures.
131
+ -C, --custom_mane_pdb_dir PATH Path to directory containing custom MANE PDB structures (requires --mane_only).
132
+ Default: None
133
+ --custom_pae_dir PATH Path to directory containing pre-downloaded PAE JSON files.
134
+ The directory will be copied into the build as `pae/`.
125
135
  Default: None
126
136
  -f, --custom_mane_metadata_path Path to a dataframe (typically a samplesheet.csv) including
127
137
  Ensembl IDs and sequences of the custom pdbs.
@@ -130,6 +140,9 @@ Options:
130
140
  Default: 10
131
141
  -c, --cores INT Number of CPU cores for computation.
132
142
  Default: All available CPU cores
143
+ --af_version INT AlphaFold DB version for non-MANE builds (MANE uses v4).
144
+ Default: 6
145
+ -y, --yes Run without interactive prompts.
133
146
  -v, --verbose Enables verbose output.
134
147
  -h, --help Show this message and exit.
135
148
  ```
@@ -138,27 +151,31 @@ For more information on the output of this step, please refer to the [Building D
138
151
 
139
152
  > [!TIP]
140
153
  > ### Increasing MANE Structural Coverage
141
- > To maximize structural coverage of **MANE Select transcripts**, you can predict missing structures locally and integrate them into Oncodrive3D using:
154
+ > To maximize structural coverage of **MANE Select transcripts**, you can [predict missing structures locally and integrate them into Oncodrive3D](tools/preprocessing/README.md) using:
142
155
  >
143
156
  > - `tools/preprocessing/prepare_samplesheet.py`: a standalone utility that:
144
- > - Retrieve the full MANE entries from NCBI.
157
+ > - Retrieves the full MANE entries from NCBI.
145
158
  > - Identifies proteins missing from the AlphaFold MANE dataset.
146
159
  > - Generates:
147
160
  > - A `samplesheet.csv` with Ensembl protein IDs, FASTA paths, and optional sequences.
148
161
  > - Individual FASTA files for each missing protein.
149
162
  >
150
- > - `--custom_mane_pdb_dir`: use this to provide your own predicted PDB structures (e.g., from [nf-core/proteinfold](https://nf-co.re/proteinfold/1.1.1/)).
163
+ > - `tools/preprocessing/update_samplesheet_and_structures.py`: takes the samplesheet folder produced above and:
164
+ > - Reuses canonical AlphaFold structures when possible to shrink the nf-core input.
165
+ > - Ingests nf-core/proteinfold predictions and keeps the `missing/` set up to date.
166
+ > - Generates a `final_bundle/samplesheet.csv` plus `final_bundle/pdbs/`, ready to be passed to `oncodrive3d build-datasets --mane_only` via `--custom_mane_metadata_path` and `--custom_mane_pdb_dir`.
151
167
  >
152
- > - `--custom_mane_metadata_path`: path to the corresponding `samplesheet.csv`, which must include:
153
- > - `sequence`: Ensembl protein ID (required)
154
- > - `refseq`: amino acid sequence (used to inject sequence into PDB if missing)
168
+ > - When invoking `oncodrive3d build-datasets`, supply:
169
+ > - `--custom_mane_pdb_dir`: use this to provide your own predicted PDB structures (e.g., from [nf-core/proteinfold](https://nf-co.re/proteinfold/1.1.1/) or `final_bundle/pdbs/` produced by `update_samplesheet_and_structures.py`).
170
+ > - `--custom_mane_metadata_path`: path to the corresponding `samplesheet.csv` (e.g., `final_bundle/samplesheet.csv`).
155
171
  >
172
+ > See the documentation of [MANE Preprocessing Toolkit](tools/preprocessing/README.md) for the full workflow to expand coverage of the MANE associated structures.
156
173
 
157
174
 
158
175
 
159
176
  ## Running 3D clustering Analysis
160
177
 
161
- For in depth information on how to obtain the required input data and for comprehensive information about the output, please refer to the [Input and Output Documentation](https://github.com/bbglab/oncodrive3d/tree/master/docs/run_input_output.md) of the 3D clustering analysis.
178
+ For in-depth information on how to obtain the required input data and for comprehensive information about the output, please refer to the [Input and Output Documentation](https://github.com/bbglab/oncodrive3d/tree/master/docs/run_input_output.md) of the 3D clustering analysis.
162
179
 
163
180
  ### Input
164
181
 
@@ -168,21 +185,13 @@ For in depth information on how to obtain the required input data and for compre
168
185
 
169
186
  - **<mut_profile>** (`optional`): Dictionary including the normalized frequencies of mutations (*values*) in every possible trinucleotide context (*keys*), such as 'ACA>A', 'ACC>A', and so on.
170
187
 
171
- ---
172
-
173
188
  > [!NOTE]
174
189
  > Examples of the input files are available in the [Test Input Folder](https://github.com/bbglab/oncodrive3d/tree/master/test/input).
175
190
  Please refer to these examples to understand the expected format and structure of the input files.
176
191
 
177
- ---
178
-
179
- ---
180
-
181
192
  > [!NOTE]
182
193
  > Oncodrive3D uses the mutational profile of the cohort to build an accurate background model. However, it’s not strictly required. If the mutational profile is not provided, the tool will use a simple uniform distribution as the background model for simulating mutations and scoring potential 3D clusters.
183
194
 
184
- ---
185
-
186
195
  ### Main Output
187
196
 
188
197
  - **Gene-level output**: CSV file (`\<cohort>.3d_clustering_genes.csv`) containing the results of the analysis at the gene level. Each row represents a gene, sorted from the most significant to the least significant based on the 3D clustering analysis. The table also includes genes that were not analyzed, with the reason for exclusion provided in the `status` column.
@@ -208,17 +217,31 @@ Options:
208
217
  annotated mutations for the cohort. [required]
209
218
  -p, --mut_profile_path PATH Path to the JSON file specifying the cohort's mutational
210
219
  profile (192 key-value pairs).
220
+ -m, --mutability_config_path PATH
221
+ Path to the JSON file with information on mutability, used when
222
+ mutation calls originate from cohorts with highly heterogeneous
223
+ sequencing depth across sites.
211
224
  -o, --output_dir PATH Path to the output directory for results.
212
225
  Default: ./output/
213
226
  -d, --data_dir PATH Path to the directory containing the datasets built in the
214
227
  building datasets step.
215
228
  Default: ./datasets/
229
+ -n, --n_iterations INT Number of densities to be simulated.
230
+ Default: 10000
231
+ -a, --alpha FLOAT Significance threshold for residue and gene p-values.
232
+ Default: 0.01
216
233
  -c, --cores INT Number of CPU cores to use.
217
234
  Default: All available CPU cores
218
235
  -s, --seed INT Random seed for reproducibility.
219
236
  -v, --verbose Enables verbose output.
220
237
  -t, --cancer_type STR Cancer type to include as metadata in the output file.
221
238
  -C, --cohort STR Cohort name for metadata and output file naming.
239
+ --no_fragments Disable processing of fragmented (AF-F) proteins.
240
+ --only_processed Include only processed genes in the output.
241
+ --thr_mapping_issue FLOAT Threshold for the ratio of mutations with mapping issues
242
+ (out of structure, WT mismatch, zero mutability). A value
243
+ of 1 disables filtering mismatching mutations.
244
+ Default: 0.1
222
245
  -P, --cmap_prob_thr FLOAT Threshold for defining residues contacts based on distance
223
246
  on predicted structure and predicted aligned error (PAE).
224
247
  Default: 0.5
@@ -231,13 +254,14 @@ Options:
231
254
  -h, --help Show this message and exit.
232
255
  ```
233
256
 
257
+ > [!TIP]
258
+ > To maximize the number of matching transcripts between the input mutations and the AlphaFold predicted structures used by Oncodrive3D, it is recommended to use the unfiltered output of VEP (including all possible transcripts) as input, along with the flags `--o3d_transcripts` `--use_input_symbols` in the `oncodrive3d run` command.
234
259
 
235
- ---
260
+ ### Handling Heterogeneous Sequencing Depth
236
261
 
237
- > [!NOTE]
238
- > To maximize the number of matching transcripts between the input mutations and the AlphaFold predicted structures used by Oncodrive3D, it is recommended to use the unfiltered output of VEP (including all possible transcripts) as input, along with the flags `--o3d_transcripts` `--use_input_symbols` in the `oncodrive3d run` command.
262
+ Oncodrive3D can ingest **site-specific mutability tables** when a single mutational profile is not representative of the cohort (e.g., mutation calling performed on highly heterogeneous-depth datasets such as ultra depth **Duplex sequencing** panels commonly used in normal tissue analysis). Provide an indexed TSV describing per-site mutability together with a JSON config via `--mutability_config_path`. The run automatically switches from trinucleotide rates to per-position probabilities and tracks additional diagnostics (`Mut_zero_mut_prob`, `Pos_zero_mut_prob`, status `Mut_with_zero_prob/No_mutability`).
239
263
 
240
- ---
264
+ Please see the [Mutability-aware runs guide](docs/mutability.md) for the expected file formats, config schema, and troubleshooting tips.
241
265
 
242
266
  ### Running With Singularity
243
267
 
@@ -247,7 +271,6 @@ singularity exec oncodrive3d.sif oncodrive3d run -i <input_maf> -p <mut_profile>
247
271
  -d <build_folder> -C <cohort_name>
248
272
  ```
249
273
 
250
-
251
274
  ### Testing
252
275
 
253
276
  To verify that Oncodrive3D is installed and configured correctly, you can perform a test run using the provided test input files:
@@ -261,6 +284,11 @@ oncodrive3d run -d <build_folder> \
261
284
 
262
285
  Check the output in the `test/output/` directory to ensure the analysis completes successfully.
263
286
 
287
+ ## Building Annotations & Plotting
288
+
289
+ Oncodrive3D ships with an optional plotting pipeline: run `oncodrive3d build-annotations` once to cache structural/functional tracks, then use `oncodrive3d plot` and/or `chimerax-plot` to generate plots and tables that help interpret the clustering signal and distinguish real biology from artifacts.
290
+
291
+ Please refer to [Annotation & plotting workflow](docs/annotations_plotting.md) for prerequisites, command examples, and output descriptions.
264
292
 
265
293
  ## Parallel Processing on Multiple Cohorts
266
294
 
@@ -270,9 +298,7 @@ For more information, refer to the [Oncodrive3D Pipeline](https://github.com/bbg
270
298
 
271
299
  ### Usage
272
300
 
273
- ---
274
-
275
- > [!WARNING]
301
+ > [!NOTE]
276
302
  > When using the Nextflow script, ensure that your input files are organized in the following directory structure (you only need either the `maf/` or `vep/` directory):
277
303
  >
278
304
  > ```plaintext
@@ -289,8 +315,6 @@ For more information, refer to the [Oncodrive3D Pipeline](https://github.com/bbg
289
315
  > - `vep/`: Contains VEP annotation files with the `.vep.tsv.gz` extension, which include annotated mutations with all possible transcripts.
290
316
  > - `mut_profile/`: Contains mutational profile files with the `.sig.json` extension.
291
317
 
292
- ---
293
-
294
318
  ```
295
319
  Usage: nextflow run main.nf [OPTIONS]
296
320
 
@@ -318,10 +342,10 @@ Options:
318
342
  --vep_input BOOL Use `vep/` subdir as input and select transcripts matching
319
343
  the Ensembl transcript IDs in Oncodrive3D built datasets.
320
344
  Default: false
321
- --mane BOOL Prioritize structures corresponding to MANE transcrips if
345
+ --mane BOOL Prioritize structures corresponding to MANE transcripts if
322
346
  multiple structures are associated to the same gene.
323
347
  Default: false
324
- --seed INT: Seed value for reproducibility.
348
+ --seed INT Seed value for reproducibility.
325
349
  Default: 128
326
350
  ```
327
351