Oncodrive3D 1.0.4__tar.gz

oncodrive3d-1.0.4/.gitignore

@@ -0,0 +1,197 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+#build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+bdist.linux-x86_64
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Oncodrive3D
+dataset*
+!scripts/datasets 
+backups
+results
+output
+tests/results/*
+tests/output/*
+tests/normal_tests
+scripts/test.qmap
+scripts/run_*
+scripts/submit*
+guidelines.txt
+
+# Nextflow
+work
+report*
+timeline*
+trace*
+*.log
+.nextflow*
+run_*
+!run_input_output.md
+
+# Containers
+*.def
+*.simg
+*.sif
+.gitignore
+
+# VSC
+launch.json
+.vscode
+
+test/outputs*

oncodrive3d-1.0.4/.python-version

@@ -0,0 +1 @@
+3.10

oncodrive3d-1.0.4/Dockerfile

@@ -0,0 +1,67 @@
+FROM ghcr.io/astral-sh/uv:0.5-python3.10-bookworm AS build-stage
+
+# Set environment variables
+ENV UV_COMPILE_BYTECODE=1 \
+    BBGLAB_HOME="/home/user/.config/bbglab/"
+
+# Set the working directory to /oncodrive3d
+WORKDIR /oncodrive3d
+
+# Stage necessary files into the container
+COPY uv.lock uv.lock
+COPY pyproject.toml pyproject.toml
+COPY scripts scripts
+COPY README.md README.md
+
+# Install dependencies and build the project
+RUN mkdir -p /root/.cache/uv \
+    && uv sync --frozen --no-dev \
+    && uv build
+
+# Second stage: Runtime image
+FROM python:3.10-buster AS runtime-stage
+
+# Set environment variables
+ENV BGDATA_LOCAL="/bgdatacache" \
+    BBGLAB_HOME="/home/user/.config/bbglab/"
+
+# Copy oncodrive3d from the build stage
+COPY --from=build-stage /oncodrive3d/dist /oncodrive3d/dist
+WORKDIR /oncodrive3d
+
+# Install oncodrive3d
+RUN pip install dist/*.tar.gz
+
+# Create required directories
+RUN install -d -m 0755 "$BGDATA_LOCAL" "$BBGLAB_HOME"
+
+# Write bgdata configuration
+RUN echo "# Version of the bgdata config file\n\
+version = 2\n\
+\n\
+# The default local folder to store the data packages\n\
+local_repository = \"$BGDATA_LOCAL\"\n\
+\n\
+# The remote URL to download the data packages\n\
+remote_repository = \"https://bbglab.irbbarcelona.org/bgdata\"\n\
+\n\
+# If you want to force bgdata to work only locally\n\
+# offline = True\n\
+\n\
+# Cache repositories\n\
+[cache_repositories]" > "$BBGLAB_HOME/bgdatav2.conf"
+
+# Pre-fetch and prepare genome data
+RUN apt-get update && apt-get install -y curl \
+    && pip install bgdata bgreference \
+    && bgdata get datasets/genomereference/hg38 \
+    && bgdata get datasets/genomereference/mm39 \
+    && python3 -c "from bgreference import hg38; hg38(1, 1300000, 3000)" \
+    && python3 -c "from bgreference import mm39; mm39(1, 1300000, 3000)" \
+    && rm -rf /var/lib/apt/lists/*
+
+# Set permissions for cache directory
+RUN chmod -R 0755 "$BGDATA_LOCAL"
+
+# Set entrypoint (optional)
+CMD ["python3"]

oncodrive3d-1.0.4/LICENSE

@@ -0,0 +1,15 @@
+Oncodrive3D is the property of the Institute for Research in Biomedicine (IRB Barcelona), which hold the copyright thereto.
+Copyright (C) 2024 Institute for Research in Biomedicine (IRB Barcelona)
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU Affero General Public License as
+published by the Free Software Foundation, either version 3 of the
+License, or (at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU Affero General Public License for more details.
+
+You should have received a copy of the GNU Affero General Public License
+along with this program.  If not, see <http://www.gnu.org/licenses/>

oncodrive3d-1.0.4/PKG-INFO

@@ -0,0 +1,333 @@
+Metadata-Version: 2.4
+Name: Oncodrive3D
+Version: 1.0.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.
+Project-URL: Homepage, https://github.com/bbglab/clustering_3d
+Project-URL: Repository, https://github.com/bbglab/clustering_3d
+Project-URL: Issues, https://github.com/bbglab/clustering_3d/issues
+Author-email: "BBGLab (Barcelona Biomedical Genomics Lab)" <bbglab@irbbarcelona.org>, Stefano Pellegrini <stefano.pellegrini@irbbarcelona.org>
+License: GNU Affero General Public License v3 or later (AGPLv3+)
+License-File: LICENSE
+Keywords: bbglab,bioinformatics,driversprediction,positiveselection
+Requires-Python: >=3.10
+Requires-Dist: adjusttext==1.1.1
+Requires-Dist: aiohttp>=3.11.10
+Requires-Dist: bgreference==0.7
+Requires-Dist: bio==1.7.1
+Requires-Dist: colorcet==3.0.1
+Requires-Dist: daiquiri>=3.3.0
+Requires-Dist: matplotlib>=3.6.2
+Requires-Dist: networkx==2.7.1
+Requires-Dist: numpy==1.26.4
+Requires-Dist: pandas==1.4.2
+Requires-Dist: progressbar2==4.0.0
+Requires-Dist: pypdl==1.4.5
+Requires-Dist: pytabix==0.0.2
+Requires-Dist: scikit-learn>=1.3.0
+Requires-Dist: scipy>=1.7.3
+Requires-Dist: seaborn>=0.12.2
+Requires-Dist: setuptools==61.2.0
+Requires-Dist: statsmodels>=0.13.2
+Requires-Dist: tqdm>=4.67.1
+Provides-Extra: linting
+Requires-Dist: ruff>=0.8.3; extra == 'linting'
+Description-Content-Type: text/markdown
+
+# Oncodrive3D
+
+**Oncodrive3D** is a fast and accurate computational method designed to analyze patterns of somatic mutation across tumors, with the goal of identifying **three-dimensional (3D) clusters** of missense mutations and detecting genes under **positive selection**. 
+
+The method leverages **AlphaFold 2-predicted protein structures** and Predicted Aligned Error (PAE) to define residue contacts within the protein's 3D space. When available, it integrates **mutational profiles** to build an accurate background model of neutral mutagenesis. By applying a novel **rank-based statistical approach**, Oncodrive3D scores potential 3D clusters and computes empirical p-values."
+
+[![License: AGPL v3](https://img.shields.io/badge/License-AGPL_v3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)
+[![docker](https://img.shields.io/docker/v/bbglab/oncodrive3d?logo=docker)](https://hub.docker.com/r/bbglab/oncodrive3d)
+[![PyPI - Version](https://img.shields.io/pypi/v/oncodrive3d?logo=pypi)](https://pypi.org/project/Oncodrive3D/)
+
+---
+
+## License
+
+Oncodrive3D is available to the general public subject to certain conditions described in its [LICENSE](LICENSE).
+
+## Requirements
+
+Before you begin, ensure **Python 3.10 or later** is installed on your system.  
+Additionally, you may need to install additional development tools. Depending on your environment, you can choose one of the following methods:
+
+- If you have sudo privileges:
+
+   ```bash
+   sudo apt install built-essential
+   ```
+
+- 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/)):
+
+   ```bash
+   conda create -n o3d python=3.10.0
+   conda activate o3d
+   conda install -c conda-forge gxx gcc libxcrypt clang zlib
+   ```
+
+
+## Installation
+
+- Install via PyPI:
+
+   ```bash
+   pip install oncodrive3d
+   ```
+
+- Alternatively, you can obtain the latest code from the repository and install it for development with pip:
+
+   ```bash
+   git clone https://github.com/bbglab/oncodrive3d.git
+   cd oncodrive3d
+   pip install -e .
+   oncodrive3d --help
+   ```
+
+- Or you can use a modern build tool like [uv](https://github.com/astral-sh/uv):
+
+   ```bash
+   git clone https://github.com/bbglab/oncodrive3d.git
+   cd oncodrive3d
+   uv run oncodrive3d --help
+   ```
+
+## Building Datasets
+
+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.
+
+> [!WARNING]
+> This step is highly time- and resource-intensive, requiring a significant amount of free disk space. It will download a large amount of data, including AlphaFold-predicted structures and reference genomes (if not already cached). Ensure sufficient resources are available before proceeding, as insufficient capacity may result in extended runtimes or processing failures.
+
+> [!NOTE]
+> 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.
+
+```
+Usage: oncodrive3d build-datasets [OPTIONS]
+
+Examples:
+  Basic build:
+    oncodrive3d build-datasets -o <build_folder>
+  
+  Build with MANE Select transcripts:
+    oncodrive3d build-datasets -o <build_folder> --mane
+
+Options:
+  -o, --output_dir PATH           Path to the directory where the output files will be saved. 
+                                  Default: ./datasets/
+  -s, --organism PATH             Specifies the organism (`human` or `mouse`). 
+                                  Default: human
+  -m, --mane                      Use structures predicted from MANE Select transcripts 
+                                  (applicable to Homo sapiens only).
+  -d, --distance_threshold INT    Distance threshold (Å) for defining residues contacts. 
+                                  Default: 10
+  -c, --cores INT                 Number of CPU cores for computation. 
+                                  Default: All available CPU cores
+  -v, --verbose                   Enables verbose output.
+  -h, --help                      Show this message and exit.  
+```
+
+For more information on the output of this step, please refer to the [Building Datasets Output Documentation](https://github.com/bbglab/oncodrive3d/tree/master/docs/build_output.md).
+
+
+## Running 3D clustering Analysis
+
+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.  
+
+### Input
+
+- **Mutations file** (`required`): It can be either:
+   - **<input_maf>**: A Mutation Annotation Format (MAF) file annotated with consequences (e.g., by using [Ensembl Variant Effect Predictor (VEP)](https://www.ensembl.org/info/docs/tools/vep/index.html)).
+   - **<input_vep>**: The unfiltered output of VEP including annotations for all possible transcripts.
+
+- **<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.
+
+---
+
+> [!NOTE] 
+> Examples of the input files are available in the [Test Input Folder](https://github.com/bbglab/oncodrive3d/tree/master/test/input).  
+Please refer to these examples to understand the expected format and structure of the input files.
+
+---
+
+---
+
+> [!NOTE]
+> 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.
+
+---
+
+### Main Output
+
+- **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.
+  
+- **Residue-level output**: CSV file (`<cohort>.3d_clustering_pos.csv`) containing the results of the analysis at the level of mutated residues. Each row corresponds to a mutated position within a gene and includes detailed information for each potential mutational cluster.
+
+
+### Usage
+
+```
+Usage: oncodrive3d run [OPTIONS]
+
+Examples:
+  Basic run:
+    oncodrive3d run -i <input_maf> -p <mut_profile> -d <build_folder> -C <cohort_name>
+  
+  Example of run using VEP output as input and MANE Select transcripts:
+    oncodrive3d run -i <input_vep> -p <mut_profile> -d <build_folder> -C <cohort_name> \
+                    --o3d_transcripts --use_input_symbols --mane
+
+Options:
+  -i, --input_path PATH            Path to the input file (MAF or VEP output) containing the 
+                                   annotated mutations for the cohort. [required]
+  -p, --mut_profile_path PATH      Path to the JSON file specifying the cohort's mutational 
+                                   profile (192 key-value pairs).
+  -o, --output_dir PATH            Path to the output directory for results. 
+                                   Default: ./output/
+  -d, --data_dir PATH              Path to the directory containing the datasets built in the 
+                                   building datasets step. 
+                                   Default: ./datasets/
+  -c, --cores INT                  Number of CPU cores to use. 
+                                   Default: All available CPU cores
+  -s, --seed INT                   Random seed for reproducibility.
+  -v, --verbose                    Enables verbose output.
+  -t, --cancer_type STR            Cancer type to include as metadata in the output file.
+  -C, --cohort STR                 Cohort name for metadata and output file naming. 
+  -P, --cmap_prob_thr FLOAT        Threshold for defining residues contacts based on distance 
+                                   on predicted structure and predicted aligned error (PAE). 
+                                   Default: 0.5
+  --mane                           Prioritizes MANE Select transcripts when multiple 
+                                   structures map to the same gene symbol.
+  --o3d_transcripts                Filters mutations including only transcripts in Oncodrive3D 
+                                   built datasets (requires VEP output as input file).
+  --use_input_symbols              Update HUGO symbols in Oncodrive3D built datasets using the 
+                                   input file's entries (requires VEP output as input file).
+  -h, --help                       Show this message and exit.  
+```
+
+
+---
+
+> [!NOTE]
+> 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.
+
+---
+
+### Running With Singularity
+
+```
+singularity pull oncodrive3d.sif docker://bbglab/oncodrive3d:latest
+singularity exec oncodrive3d.sif oncodrive3d run -i <input_maf> -p <mut_profile> \ 
+                                                 -d <build_folder> -C <cohort_name>
+```
+
+
+### Testing
+
+To verify that Oncodrive3D is installed and configured correctly, you can perform a test run using the provided test input files: 
+
+```
+oncodrive3d run -d <build_folder> \
+                -i ./test/input/maf/TCGA_WXS_ACC.in.maf \ 
+                -p ./test/input/mut_profile/TCGA_WXS_ACC.sig.json \
+                -o ./test/output/ -C TCGA_WXS_ACC
+```
+
+Check the output in the `test/output/` directory to ensure the analysis completes successfully.
+
+
+## Parallel Processing on Multiple Cohorts
+
+Oncodrive3D can be run in parallel on multiple cohorts using [Nextflow](https://www.nextflow.io/). This approach enables efficient, reproducible and scalable analysis across datasets.
+
+### Requirements
+
+1. Install [Nextflow](https://www.nextflow.io/docs/latest/getstarted.html) (version `23.04.3` was used for testing).
+2. Install and set up either or both:
+   - [Singularity](https://sylabs.io/guides/latest/user-guide/installation.html)  
+      Pull the Oncodrive3D Singularity image from Docker Hub:
+
+      ```
+      singularity pull oncodrive3d.sif docker://bbglab/oncodrive3d:latest
+      ```
+
+   - [Conda](https://docs.conda.io/projects/conda/en/latest/user-guide/install/index.html)  
+      Ensure Oncodrive3D is installed in your Conda environment and update the `params` section of the `nextflow.config` file to point to your Conda installation:
+
+         ```groovy
+         params {
+            ...
+            conda_env = '/path/to/conda/environment/with/oncodrive3d' 
+            ...
+         }
+         ```
+
+      Replace `/path/to/conda/environment/with/oncodrive3d` with the path to your Conda environment. Alternatively, you can provide it as a command-line argument.
+
+
+### Test Run
+
+Run a test to ensure that everything is set up correctly and functioning as expected:
+
+```
+cd oncodrive3d_pipeline
+nextflow run main.nf -profile test,container --data_dir <build_folder>
+```
+
+Replace `<build_folder>` with the path to the Oncodrive3D datasets built in the [building datasets](#building-datasets) step.
+If you prefer to use Conda, replace `container` in the `-profile` argument with `conda`.
+
+### Usage
+
+---
+
+> [!WARNING]
+> When using the Nextflow script, ensure that your input files are organized in the following directory structure:
+> 
+> ```plaintext
+> input/
+>   ├── maf/
+>   │   └── <cohort>.in.maf
+>   ├── vep/
+>   │   └── <cohort>.vep.tsv.gz
+>   └── mut_profile/
+>       └── <cohort>.sig.json
+> ```
+> 
+> - `maf/`: Contains mutation files with the `.in.maf` extension.
+> - `vep/`: Contains VEP annotation files with the `.vep.tsv.gz` extension, which include annotated mutations with all possible transcripts.
+> - `mut_profile/`: Contains mutational profile files with the `.sig.json` extension.
+
+---
+
+```
+Usage: nextflow run main.nf [OPTIONS]
+
+Example of run using VEP output as input and MANE Select transcripts:
+  nextflow run main.nf -profile container --data_dir <build_folder> --indir <input> \
+                       --vep_input true --mane true
+  
+Options:
+  --indir PATH                    Path to the input directory including the subdirectories 
+                                  `maf` or `vep` and `mut_profile`. 
+  --outdir PATH                   Path to the output directory. 
+                                  Default: run_<timestamp>/
+  --cohort_pattern STR            Pattern expression to filter specific files within the 
+                                  input directory (e.g., 'TCGA*' select only TCGA cohorts). 
+                                  Default: *
+  --data_dir PATH                 Path to the Oncodrive3D datasets directory, which includes 
+                                  the files compiled during the building datasets step.
+                                  Default: ${baseDir}/datasets/
+  --container PATH                Path to the Singularity image with Oncodrive3D installation. 
+                                  Default: ${baseDir}/../oncodrive3d.sif
+  --max_running INT               Maximum number of cohorts to process in parallel.
+                                  Default: 5
+  --cores INT                     Number of CPU cores used to process each cohort. 
+                                  Default: 10
+  --memory STR                    Amount of memory allocated for processing each cohort. 
+                                  Default: 70GB
+  --seed INT:                     Seed value for reproducibility.
+                                  Default: 128
+```