Documentation created

ci.yml → .github/workflows/ci.yml

@@ -21,10 +21,10 @@ jobs:
         python-version: ['3.9', '3.14']
 
     steps:
-    - uses: actions/checkout@v4
-    
+    - uses: actions/checkout@v6
+
     - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v5
+      uses: actions/setup-python@v6
       with:
         python-version: ${{ matrix.python-version }}
 
@@ -38,7 +38,7 @@ jobs:
         python -m pip install --upgrade pip setuptools packaging
 
     - name: Cache src directory
-      uses: actions/cache@v4
+      uses: actions/cache@v5
       with:
         path: ${{ github.workspace }}/src/
         key: ${{ runner.os }}-src-grch37

.github/workflows/docs.yml

@@ -0,0 +1,53 @@
+name: Docs
+
+on:
+  push:
+    branches:
+      - master
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: github-pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.x"
+
+      - name: Configure Pages
+        uses: actions/configure-pages@v6
+
+      - name: Install docs dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install mkdocs mkdocs-material pymdown-extensions
+
+      - name: Build site
+        run: |
+          mkdocs build --clean
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v5
+        with:
+          path: site
+
+  deploy:
+    runs-on: ubuntu-latest
+    needs: build
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v5

.github/workflows/release.yml

@@ -17,10 +17,12 @@ jobs:
 
     steps:
       - name: Checkout repo
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
 
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: "3.14"
 
@@ -64,22 +66,29 @@ jobs:
               raise SystemExit(f"Error: New version ({new_version}) is not higher than latest release ({latest_version})")
           EOF
 
-      - name: Generate CHANGELOG.md with git-cliff
+      - name: Generate release notes and update CHANGELOG.md
         run: |
-          git-cliff --unreleased --strip all --tag "v${{ steps.get_version.outputs.VERSION }}" > CHANGELOG.md
+          git-cliff --unreleased --strip all --tag "v${{ steps.get_version.outputs.VERSION }}" > RELEASE_NOTES.md
+          git-cliff --unreleased --tag "v${{ steps.get_version.outputs.VERSION }}" --prepend CHANGELOG.md
 
-      - name: Create Git tag
+      - name: Commit and push CHANGELOG.md
         run: |
           git config user.name "github-actions"
           git config user.email "github-actions@github.com"
+          git add CHANGELOG.md
+          git commit -m "chore: update CHANGELOG.md for v${{ steps.get_version.outputs.VERSION }}"
+          git push origin HEAD:master
+
+      - name: Create Git tag
+        run: |
           git tag v${{ steps.get_version.outputs.VERSION }}
           git push origin v${{ steps.get_version.outputs.VERSION }}
 
       - name: Create GitHub Release
         uses: softprops/action-gh-release@v2
         with:
           tag_name: v${{ steps.get_version.outputs.VERSION }}
-          body_path: CHANGELOG.md
+          body_path: RELEASE_NOTES.md
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 

README.md

@@ -132,7 +132,9 @@ Two examples are provided under examples/. These directories include all expecte
 
 CITATIONS
 
-Erik N Bergstrom, Mousumy Kundu, Noura Tbeileh, Ludmil B Alexandrov. bioRxiv 2022.02.11.480117; doi: https://doi.org/10.1101/2022.02.11.480117
+Erik N Bergstrom, Mousumy Kundu, Noura Tbeileh, Ludmil B Alexandrov. Examining clustered somatic mutations with SigProfilerClusters. Bioinformatics. 2022;38(13):3470–3473. https://doi.org/10.1093/bioinformatics/btac335
+
+Bergstrom EN, Luebeck J, Petljak M, et al. Mapping clustered mutations in cancer reveals APOBEC3 mutagenesis of ecDNA. Nature. 2022;602:510–517. https://doi.org/10.1038/s41586-022-04398-6
 
 COPYRIGHT
 

docs/1_installation.md

@@ -0,0 +1,82 @@
+# Installation
+
+
+----------
+
+
+This section will help you set up the necessary software and packages required to run SigProfilerClusters.
+
+----------
+
+
+## Prerequisites ##
+
+- [Python][1] version >= 3.9
+- [SigProfilerMatrixGenerator][2] with a downloaded reference genome (required to generate mutational matrices and simulations)
+- [SigProfilerSimulator][3] (required to generate the background model used for IMD threshold calculation)
+- Other dependencies are installed automatically during package installation
+
+## Installation ##
+
+SigProfilerClusters can be executed on any Windows/macOS/Unix system. First follow the [SigProfilerMatrixGenerator][2] guide for installing `Python` and `pip`. Next, follow the instructions below for the latest stable release or the current GitHub version.
+
+### Installation with `pip` ###
+
+Install the latest `SigProfilerClusters` PyPI version using `pip`:
+```
+$ pip install SigProfilerClusters
+```
+
+To upgrade an existing installation to the most recent version:
+```
+$ pip install SigProfilerClusters --upgrade
+```
+
+### Install specific GitHub Release ###
+
+First, download the [zip file][4] or clone the GitHub repository:
+```
+$ git clone https://github.com/SigProfilerSuite/SigProfilerClusters.git
+```
+
+Next, enter the downloaded directory and install the package:
+```
+$ cd SigProfilerClusters
+$ pip install .
+```
+
+## Download Reference Genome ##
+
+SigProfilerClusters requires a reference genome to generate simulations and mutational matrices. Current reference genomes supported include GRCh37, GRCh38, mm9, and mm10. To install the reference genome/s, you need to use [SigProfilerMatrixGenerator][2].
+
+The last PyPI [SigProfilerMatrixGenerator][2] version is installed with SigProfilerClusters by default. You can also install a specific version following the instructions in the [SigProfilerMatrixGenerator Wiki][2].
+
+Once [SigProfilerMatrixGenerator][2] is installed, install your desired reference genome from the command line/terminal as follows.
+
+### Installation from command line ###
+
+```
+$ SigProfilerMatrixGenerator install GRCh37
+```
+
+### Installation from Python terminal ###
+
+``` python
+$ python
+>>> from SigProfilerMatrixGenerator import install as genInstall
+>>> genInstall.install('GRCh37', rsync=False, bash=True)
+```
+
+If you have a firewall on your server, you may need to install `rsync` and use the `rsync=True` parameter. Similarly, if you do not have bash available, use `bash=False`.
+
+In case you prefer to install a reference genome from a local copy:
+``` python
+$ python
+>>> from SigProfilerMatrixGenerator import install as genInstall
+>>> genInstall.install('GRCh37', offline_files_path='path/to/directory/containing/GRCh37.tar.gz')
+```
+
+  [1]: https://www.python.org/downloads
+  [2]: https://sigprofilersuite.github.io/SigProfilerMatrixGenerator/
+  [3]: https://osf.io/usxjz/wiki/home/
+  [4]: https://github.com/SigProfilerSuite/SigProfilerClusters/releases

docs/2_quick_start_example.md

@@ -0,0 +1,75 @@
+# Quick Start Example
+
+
+----------
+
+
+This section provides a minimal example to get started with SigProfilerClusters. The following example uses a breast cancer sample (`BRCA`) or a melanoma sample (`MELA`) and demonstrates the complete workflow: generating simulations with [SigProfilerSimulator][2] and detecting clustered mutations with SigProfilerClusters.
+
+----------
+
+## Prerequisites ##
+
+This tutorial requires that you have completed all steps in the [installation guide][1], specifically:
+
+- Installed SigProfilerClusters
+- Installed [SigProfilerSimulator][2]
+- Downloaded the **GRCh37** reference genome using [SigProfilerMatrixGenerator][3]
+
+## Downloading input example data ##
+
+Download one of the example VCF files below and place it in a new project directory (e.g., `path/to/data/`):
+
+- [BRCA_example_subs.vcf][5] — breast cancer substitutions
+- [BRCA_example_indels.vcf][7] — breast cancer indels
+- [MELA_example.vcf][6] — melanoma substitutions
+
+These samples and their expected outputs are also available under the `examples/` directory within the [GitHub repository](https://github.com/SigProfilerSuite/SigProfilerClusters).
+
+!!! note
+    The `simulations/` folder is not included in the GitHub repository to reduce its memory footprint.
+
+## Running SigProfilerClusters ##
+
+First, start a Python interactive shell and import [SigProfilerMatrixGenerator][3], [SigProfilerSimulator][2], and SigProfilerClusters.
+
+``` python
+$ python
+>>> from SigProfilerMatrixGenerator import install as genInstall
+>>> from SigProfilerSimulator import SigProfilerSimulator as sigSim
+>>> from SigProfilerClusters import SigProfilerClusters as hp
+```
+
+### Step 1: Run SigProfilerSimulator ###
+
+Generate a background model by running at least 100 simulations of inter-mutational distances for your data. **Note**: Update `"path/to/data"` with the actual path to the directory containing the VCF file.
+
+``` python
+>>> sigSim.SigProfilerSimulator("BRCA", "path/to/data", "GRCh37", contexts=["288"], chrom_based=True, simulations=100)
+```
+
+### Step 2: Run SigProfilerClusters ###
+
+Cluster mutations based on the simulated background distribution. **Note**: Update `"path/to/data"` with the actual path to your project directory.
+
+``` python
+>>> hp.analysis("BRCA", "GRCh37", "96", ["288"], "path/to/data",
+                analysis="all", sortSims=True, subClassify=True,
+                correction=True, calculateIMD=True, max_cpu=4,
+                variant_caller="standard")
+```
+
+After SigProfilerClusters has finished running, the output will be organized under `path/to/data/output/`. Partitioned mutations are placed under `output/clustered/` and `output/nonClustered/`, and visualizations are found under `output/plots/`. To learn more about all output files, please refer to the [Using the Tool - Output][4] section.
+
+## Additional Information ##
+
+In the above example, unspecified parameters use their default values. All function arguments and their types are described in detail in the [Using the Tool - Input][8] section. To learn more about the generated output files, refer to [Using the Tool - Output][4].
+
+  [1]: https://sigprofilersuite.github.io/SigProfilerClusters/1_installation.html
+  [2]: https://osf.io/usxjz/wiki/home/
+  [3]: https://sigprofilersuite.github.io/SigProfilerMatrixGenerator/
+  [4]: https://sigprofilersuite.github.io/SigProfilerClusters/5_using_the_tool_output.html
+  [5]: https://osf.io/gy2bh/
+  [6]: https://osf.io/a8bq5/
+  [7]: https://osf.io/tyw3u/
+  [8]: https://sigprofilersuite.github.io/SigProfilerClusters/4_using_the_tool_input.html

docs/3_workflow.md

@@ -0,0 +1,49 @@
+# Workflow
+
+
+----------
+
+
+This section describes the methodology used by SigProfilerClusters to identify and classify clustered mutations. The tool follows a four-stage process that distinguishes genuinely clustered mutations from those distributed randomly across the genome.
+
+!!! note "Minimum mutational burden"
+    Reliable analysis requires a mutational burden greater than **0.005 mutations per megabase**. Samples below this threshold may not produce meaningful IMD-based clustering results.
+
+----------
+
+## Stage 1: Background Model Generation ##
+
+A per-sample background model is created using [SigProfilerSimulator][1]. This tool randomizes each mutation across the genome while preserving:
+
+- The desired trinucleotide sequence context
+- Transcriptional strand bias ratios
+- The mutational burden on each chromosome
+
+A minimum of **100 simulations** is recommended to ensure a robust background distribution.
+
+## Stage 2: IMD Threshold Calculation ##
+
+SigProfilerClusters compares the distribution of real inter-mutational distances (IMD) with the simulated background to compute a **sample-specific IMD threshold**. The threshold is set at the point where at least **90% of mutations falling within it are unlikely to have occurred by chance**, i.e., their spacing cannot be explained by the background model.
+
+This approach ensures that the clustering criterion adapts to the mutation burden and genomic context of each individual sample.
+
+## Stage 3: Regional Correction ##
+
+The global IMD threshold is further refined by applying a **localized correction across 1-megabase genomic windows**. This step accounts for the uneven distribution of mutations throughout the genome — regions with higher mutation density will have a proportionally adjusted threshold — preventing over- or under-calling of clustered events in heterogeneous mutational landscapes.
+
+## Stage 4: Mutation Classification ##
+
+After thresholding and correction, mutations are assigned to one of the following categories based on their inter-mutational spacing and, when available, variant allele frequencies (VAF):
+
+| Class | Category | Description |
+|-------|----------|-------------|
+| Non-clustered | — | Mutations whose spacing is consistent with random expectation |
+| Clustered | **DBS** (Doublet Base Substitution) | Exactly 2 adjacent SNVs on the same chromosomal position |
+| Clustered | **MBS** (Multi-Base Substitution) | 3 or more adjacent SNVs on consecutive chromosomal positions |
+| Clustered | **Omikli** | 2–3 clustered SNVs with IMD pattern consistent with a localized event |
+| Clustered | **Kataegis** | 4 or more clustered SNVs with IMD pattern consistent with a regional hypermutation event |
+| Clustered | **Other** | Clustered mutations with inconsistent allele frequencies; only identified when VAF/CCF data is available |
+
+Indels are classified as clustered or non-clustered but are not further subclassified into the categories above.
+
+  [1]: https://osf.io/usxjz/wiki/home/