Metadata-Version: 2.4
Name: pytmb-curie
Version: 1.6.0
Summary: Calculate a Tumour Mutational Burden (TMB) score from a VCF file.
Author-email: Tom Gutman <tom.gutman@curie.fr>, Nicolas Servant <nicolas.servant@curie.fr>
License: CeCILL FREE SOFTWARE LICENSE AGREEMENT
        Copyright (c) Institut Curie
        
        Version 2.1 dated 2013-06-21
        
            Notice
        
        This Agreement is a Free Software license agreement that is the result
        of discussions between its authors in order to ensure compliance with
        the two main principles guiding its drafting:
        
          * firstly, compliance with the principles governing the distribution
            of Free Software: access to source code, broad rights granted to users,
          * secondly, the election of a governing law, French law, with which it
            is conformant, both as regards the law of torts and intellectual
            property law, and the protection that it offers to both authors and
            holders of the economic rights over software.
        
        The authors of the CeCILL (for Ce[a] C[nrs] I[nria] L[ogiciel] L[ibre]) 
        license are: 
        
        Commissariat a  l'energie atomique et aux energies alternatives - CEA, a
        public scientific, technical and industrial research establishment,
        having its principal place of business at 25 rue Leblanc, immeuble Le
        Ponant D, 75015 Paris, France.
        
        Centre National de la Recherche Scientifique - CNRS, a public scientific
        and technological establishment, having its principal place of business
        at 3 rue Michel-Ange, 75794 Paris cedex 16, France.
        
        Institut National de Recherche en Informatique et en Automatique -
        Inria, a public scientific and technological establishment, having its
        principal place of business at Domaine de Voluceau, Rocquencourt, BP
        105, 78153 Le Chesnay cedex, France.
        
        
            Preamble
        
        The purpose of this Free Software license agreement is to grant users
        the right to modify and redistribute the software governed by this
        license within the framework of an open source distribution model.
        
        The exercising of this right is conditional upon certain obligations for
        users so as to preserve this status for all subsequent redistributions.
        
        In consideration of access to the source code and the rights to copy,
        modify and redistribute granted by the license, users are provided only
        with a limited warranty and the software's author, the holder of the
        economic rights, and the successive licensors only have limited liability.
        
        In this respect, the risks associated with loading, using, modifying
        and/or developing or reproducing the software by the user are brought to
        the user's attention, given its Free Software status, which may make it
        complicated to use, with the result that its use is reserved for
        developers and experienced professionals having in-depth computer
        knowledge. Users are therefore encouraged to load and test the
        suitability of the software as regards their requirements in conditions
        enabling the security of their systems and/or data to be ensured and,
        more generally, to use and operate it in the same conditions of
        security. This Agreement may be freely reproduced and published,
        provided it is not altered, and that no provisions are either added or
        removed herefrom.
        
        This Agreement may apply to any or all software for which the holder of
        the economic rights decides to submit the use thereof to its provisions.
        
        Frequently asked questions can be found on the official website of the
        CeCILL licenses family (http://www.cecill.info/index.en.html) for any 
        necessary clarification.
        
        
            Article 1 - DEFINITIONS
        
        For the purpose of this Agreement, when the following expressions
        commence with a capital letter, they shall have the following meaning:
        
        Agreement: means this license agreement, and its possible subsequent
        versions and annexes.
        
        Software: means the software in its Object Code and/or Source Code form
        and, where applicable, its documentation, "as is" when the Licensee
        accepts the Agreement.
        
        Initial Software: means the Software in its Source Code and possibly its
        Object Code form and, where applicable, its documentation, "as is" when
        it is first distributed under the terms and conditions of the Agreement.
        
        Modified Software: means the Software modified by at least one
        Contribution.
        
        Source Code: means all the Software's instructions and program lines to
        which access is required so as to modify the Software.
        
        Object Code: means the binary files originating from the compilation of
        the Source Code.
        
        Holder: means the holder(s) of the economic rights over the Initial
        Software.
        
        Licensee: means the Software user(s) having accepted the Agreement.
        
        Contributor: means a Licensee having made at least one Contribution.
        
        Licensor: means the Holder, or any other individual or legal entity, who
        distributes the Software under the Agreement.
        
        Contribution: means any or all modifications, corrections, translations,
        adaptations and/or new functions integrated into the Software by any or
        all Contributors, as well as any or all Internal Modules.
        
        Module: means a set of sources files including their documentation that
        enables supplementary functions or services in addition to those offered
        by the Software.
        
        External Module: means any or all Modules, not derived from the
        Software, so that this Module and the Software run in separate address
        spaces, with one calling the other when they are run.
        
        Internal Module: means any or all Module, connected to the Software so
        that they both execute in the same address space.
        
        GNU GPL: means the GNU General Public License version 2 or any
        subsequent version, as published by the Free Software Foundation Inc.
        
        GNU Affero GPL: means the GNU Affero General Public License version 3 or
        any subsequent version, as published by the Free Software Foundation Inc.
        
        EUPL: means the European Union Public License version 1.1 or any
        subsequent version, as published by the European Commission.
        
        Parties: mean both the Licensee and the Licensor.
        
        These expressions may be used both in singular and plural form.
        
        
            Article 2 - PURPOSE
        
        The purpose of the Agreement is the grant by the Licensor to the
        Licensee of a non-exclusive, transferable and worldwide license for the
        Software as set forth in Article 5 <#scope> hereinafter for the whole
        term of the protection granted by the rights over said Software.
        
        
            Article 3 - ACCEPTANCE
        
        3.1 The Licensee shall be deemed as having accepted the terms and
        conditions of this Agreement upon the occurrence of the first of the
        following events:
        
          * (i) loading the Software by any or all means, notably, by
            downloading from a remote server, or by loading from a physical medium;
          * (ii) the first time the Licensee exercises any of the rights granted
            hereunder.
        
        3.2 One copy of the Agreement, containing a notice relating to the
        characteristics of the Software, to the limited warranty, and to the
        fact that its use is restricted to experienced users has been provided
        to the Licensee prior to its acceptance as set forth in Article 3.1
        <#accepting> hereinabove, and the Licensee hereby acknowledges that it
        has read and understood it.
        
        
            Article 4 - EFFECTIVE DATE AND TERM
        
        
              4.1 EFFECTIVE DATE
        
        The Agreement shall become effective on the date when it is accepted by
        the Licensee as set forth in Article 3.1 <#accepting>.
        
        
              4.2 TERM
        
        The Agreement shall remain in force for the entire legal term of
        protection of the economic rights over the Software.
        
        
            Article 5 - SCOPE OF RIGHTS GRANTED
        
        The Licensor hereby grants to the Licensee, who accepts, the following
        rights over the Software for any or all use, and for the term of the
        Agreement, on the basis of the terms and conditions set forth hereinafter.
        
        Besides, if the Licensor owns or comes to own one or more patents
        protecting all or part of the functions of the Software or of its
        components, the Licensor undertakes not to enforce the rights granted by
        these patents against successive Licensees using, exploiting or
        modifying the Software. If these patents are transferred, the Licensor
        undertakes to have the transferees subscribe to the obligations set
        forth in this paragraph.
        
        
              5.1 RIGHT OF USE
        
        The Licensee is authorized to use the Software, without any limitation
        as to its fields of application, with it being hereinafter specified
        that this comprises:
        
         1. permanent or temporary reproduction of all or part of the Software
            by any or all means and in any or all form.
        
         2. loading, displaying, running, or storing the Software on any or all
            medium.
        
         3. entitlement to observe, study or test its operation so as to
            determine the ideas and principles behind any or all constituent
            elements of said Software. This shall apply when the Licensee
            carries out any or all loading, displaying, running, transmission or
            storage operation as regards the Software, that it is entitled to
            carry out hereunder.
        
        
              5.2 ENTITLEMENT TO MAKE CONTRIBUTIONS
        
        The right to make Contributions includes the right to translate, adapt,
        arrange, or make any or all modifications to the Software, and the right
        to reproduce the resulting software.
        
        The Licensee is authorized to make any or all Contributions to the
        Software provided that it includes an explicit notice that it is the
        author of said Contribution and indicates the date of the creation thereof.
        
        
              5.3 RIGHT OF DISTRIBUTION
        
        In particular, the right of distribution includes the right to publish,
        transmit and communicate the Software to the general public on any or
        all medium, and by any or all means, and the right to market, either in
        consideration of a fee, or free of charge, one or more copies of the
        Software by any means.
        
        The Licensee is further authorized to distribute copies of the modified
        or unmodified Software to third parties according to the terms and
        conditions set forth hereinafter.
        
        
                5.3.1 DISTRIBUTION OF SOFTWARE WITHOUT MODIFICATION
        
        The Licensee is authorized to distribute true copies of the Software in
        Source Code or Object Code form, provided that said distribution
        complies with all the provisions of the Agreement and is accompanied by:
        
         1. a copy of the Agreement,
        
         2. a notice relating to the limitation of both the Licensor's warranty
            and liability as set forth in Articles 8 and 9,
        
        and that, in the event that only the Object Code of the Software is
        redistributed, the Licensee allows effective access to the full Source
        Code of the Software for a period of at least three years from the
        distribution of the Software, it being understood that the additional
        acquisition cost of the Source Code shall not exceed the cost of the
        data transfer.
        
        
                5.3.2 DISTRIBUTION OF MODIFIED SOFTWARE
        
        When the Licensee makes a Contribution to the Software, the terms and
        conditions for the distribution of the resulting Modified Software
        become subject to all the provisions of this Agreement.
        
        The Licensee is authorized to distribute the Modified Software, in
        source code or object code form, provided that said distribution
        complies with all the provisions of the Agreement and is accompanied by:
        
         1. a copy of the Agreement,
        
         2. a notice relating to the limitation of both the Licensor's warranty
            and liability as set forth in Articles 8 and 9,
        
        and, in the event that only the object code of the Modified Software is
        redistributed,
        
         3. a note stating the conditions of effective access to the full source
            code of the Modified Software for a period of at least three years
            from the distribution of the Modified Software, it being understood
            that the additional acquisition cost of the source code shall not
            exceed the cost of the data transfer.
        
        
                5.3.3 DISTRIBUTION OF EXTERNAL MODULES
        
        When the Licensee has developed an External Module, the terms and
        conditions of this Agreement do not apply to said External Module, that
        may be distributed under a separate license agreement.
        
        
                5.3.4 COMPATIBILITY WITH OTHER LICENSES
        
        The Licensee can include a code that is subject to the provisions of one
        of the versions of the GNU GPL, GNU Affero GPL and/or EUPL in the
        Modified or unmodified Software, and distribute that entire code under
        the terms of the same version of the GNU GPL, GNU Affero GPL and/or EUPL.
        
        The Licensee can include the Modified or unmodified Software in a code
        that is subject to the provisions of one of the versions of the GNU GPL,
        GNU Affero GPL and/or EUPL and distribute that entire code under the
        terms of the same version of the GNU GPL, GNU Affero GPL and/or EUPL.
        
        
            Article 6 - INTELLECTUAL PROPERTY
        
        
              6.1 OVER THE INITIAL SOFTWARE
        
        The Holder owns the economic rights over the Initial Software. Any or
        all use of the Initial Software is subject to compliance with the terms
        and conditions under which the Holder has elected to distribute its work
        and no one shall be entitled to modify the terms and conditions for the
        distribution of said Initial Software.
        
        The Holder undertakes that the Initial Software will remain ruled at
        least by this Agreement, for the duration set forth in Article 4.2 <#term>.
        
        
              6.2 OVER THE CONTRIBUTIONS
        
        The Licensee who develops a Contribution is the owner of the
        intellectual property rights over this Contribution as defined by
        applicable law.
        
        
              6.3 OVER THE EXTERNAL MODULES
        
        The Licensee who develops an External Module is the owner of the
        intellectual property rights over this External Module as defined by
        applicable law and is free to choose the type of agreement that shall
        govern its distribution.
        
        
              6.4 JOINT PROVISIONS
        
        The Licensee expressly undertakes:
        
         1. not to remove, or modify, in any manner, the intellectual property
            notices attached to the Software;
        
         2. to reproduce said notices, in an identical manner, in the copies of
            the Software modified or not.
        
        The Licensee undertakes not to directly or indirectly infringe the
        intellectual property rights on the Software of the Holder and/or
        Contributors, and to take, where applicable, vis-Ã -vis its staff, any
        and all measures required to ensure respect of said intellectual
        property rights of the Holder and/or Contributors.
        
        
            Article 7 - RELATED SERVICES
        
        7.1 Under no circumstances shall the Agreement oblige the Licensor to
        provide technical assistance or maintenance services for the Software.
        
        However, the Licensor is entitled to offer this type of services. The
        terms and conditions of such technical assistance, and/or such
        maintenance, shall be set forth in a separate instrument. Only the
        Licensor offering said maintenance and/or technical assistance services
        shall incur liability therefor.
        
        7.2 Similarly, any Licensor is entitled to offer to its licensees, under
        its sole responsibility, a warranty, that shall only be binding upon
        itself, for the redistribution of the Software and/or the Modified
        Software, under terms and conditions that it is free to decide. Said
        warranty, and the financial terms and conditions of its application,
        shall be subject of a separate instrument executed between the Licensor
        and the Licensee.
        
        
            Article 8 - LIABILITY
        
        8.1 Subject to the provisions of Article 8.2, the Licensee shall be
        entitled to claim compensation for any direct loss it may have suffered
        from the Software as a result of a fault on the part of the relevant
        Licensor, subject to providing evidence thereof.
        
        8.2 The Licensor's liability is limited to the commitments made under
        this Agreement and shall not be incurred as a result of in particular:
        (i) loss due the Licensee's total or partial failure to fulfill its
        obligations, (ii) direct or consequential loss that is suffered by the
        Licensee due to the use or performance of the Software, and (iii) more
        generally, any consequential loss. In particular the Parties expressly
        agree that any or all pecuniary or business loss (i.e. loss of data,
        loss of profits, operating loss, loss of customers or orders,
        opportunity cost, any disturbance to business activities) or any or all
        legal proceedings instituted against the Licensee by a third party,
        shall constitute consequential loss and shall not provide entitlement to
        any or all compensation from the Licensor.
        
        
            Article 9 - WARRANTY
        
        9.1 The Licensee acknowledges that the scientific and technical
        state-of-the-art when the Software was distributed did not enable all
        possible uses to be tested and verified, nor for the presence of
        possible defects to be detected. In this respect, the Licensee's
        attention has been drawn to the risks associated with loading, using,
        modifying and/or developing and reproducing the Software which are
        reserved for experienced users.
        
        The Licensee shall be responsible for verifying, by any or all means,
        the suitability of the product for its requirements, its good working
        order, and for ensuring that it shall not cause damage to either persons
        or properties.
        
        9.2 The Licensor hereby represents, in good faith, that it is entitled
        to grant all the rights over the Software (including in particular the
        rights set forth in Article 5 <#scope>).
        
        9.3 The Licensee acknowledges that the Software is supplied "as is" by
        the Licensor without any other express or tacit warranty, other than
        that provided for in Article 9.2 <#good-faith> and, in particular,
        without any warranty as to its commercial value, its secured, safe,
        innovative or relevant nature.
        
        Specifically, the Licensor does not warrant that the Software is free
        from any error, that it will operate without interruption, that it will
        be compatible with the Licensee's own equipment and software
        configuration, nor that it will meet the Licensee's requirements.
        
        9.4 The Licensor does not either expressly or tacitly warrant that the
        Software does not infringe any third party intellectual property right
        relating to a patent, software or any other property right. Therefore,
        the Licensor disclaims any and all liability towards the Licensee
        arising out of any or all proceedings for infringement that may be
        instituted in respect of the use, modification and redistribution of the
        Software. Nevertheless, should such proceedings be instituted against
        the Licensee, the Licensor shall provide it with technical and legal
        expertise for its defense. Such technical and legal expertise shall be
        decided on a case-by-case basis between the relevant Licensor and the
        Licensee pursuant to a memorandum of understanding. The Licensor
        disclaims any and all liability as regards the Licensee's use of the
        name of the Software. No warranty is given as regards the existence of
        prior rights over the name of the Software or as regards the existence
        of a trademark.
        
        
            Article 10 - TERMINATION
        
        10.1 In the event of a breach by the Licensee of its obligations
        hereunder, the Licensor may automatically terminate this Agreement
        thirty (30) days after notice has been sent to the Licensee and has
        remained ineffective.
        
        10.2 A Licensee whose Agreement is terminated shall no longer be
        authorized to use, modify or distribute the Software. However, any
        licenses that it may have granted prior to termination of the Agreement
        shall remain valid subject to their having been granted in compliance
        with the terms and conditions hereof.
        
        
            Article 11 - MISCELLANEOUS
        
        
              11.1 EXCUSABLE EVENTS
        
        Neither Party shall be liable for any or all delay, or failure to
        perform the Agreement, that may be attributable to an event of force
        majeure, an act of God or an outside cause, such as defective
        functioning or interruptions of the electricity or telecommunications
        networks, network paralysis following a virus attack, intervention by
        government authorities, natural disasters, water damage, earthquakes,
        fire, explosions, strikes and labor unrest, war, etc.
        
        11.2 Any failure by either Party, on one or more occasions, to invoke
        one or more of the provisions hereof, shall under no circumstances be
        interpreted as being a waiver by the interested Party of its right to
        invoke said provision(s) subsequently.
        
        11.3 The Agreement cancels and replaces any or all previous agreements,
        whether written or oral, between the Parties and having the same
        purpose, and constitutes the entirety of the agreement between said
        Parties concerning said purpose. No supplement or modification to the
        terms and conditions hereof shall be effective as between the Parties
        unless it is made in writing and signed by their duly authorized
        representatives.
        
        11.4 In the event that one or more of the provisions hereof were to
        conflict with a current or future applicable act or legislative text,
        said act or legislative text shall prevail, and the Parties shall make
        the necessary amendments so as to comply with said act or legislative
        text. All other provisions shall remain effective. Similarly, invalidity
        of a provision of the Agreement, for any reason whatsoever, shall not
        cause the Agreement as a whole to be invalid.
        
        
              11.5 LANGUAGE
        
        The Agreement is drafted in both French and English and both versions
        are deemed authentic.
        
        
            Article 12 - NEW VERSIONS OF THE AGREEMENT
        
        12.1 Any person is authorized to duplicate and distribute copies of this
        Agreement.
        
        12.2 So as to ensure coherence, the wording of this Agreement is
        protected and may only be modified by the authors of the License, who
        reserve the right to periodically publish updates or new versions of the
        Agreement, each with a separate number. These subsequent versions may
        address new issues encountered by Free Software.
        
        12.3 Any Software distributed under a given version of the Agreement may
        only be subsequently distributed under the same version of the Agreement
        or a subsequent version, subject to the provisions of Article 5.3.4
        <#compatibility>.
        
        
            Article 13 - GOVERNING LAW AND JURISDICTION
        
        13.1 The Agreement is governed by French law. The Parties agree to
        endeavor to seek an amicable solution to any disagreements or disputes
        that may arise during the performance of the Agreement.
        
        13.2 Failing an amicable solution within two (2) months as from their
        occurrence, and unless emergency proceedings are necessary, the
        disagreements or disputes shall be referred to the Paris Courts having
        jurisdiction, by the more diligent Party.
        
Keywords: bioinformatics,TMB,tumour mutational burden,VCF,cancer genomics
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: POSIX :: Linux
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: cyvcf2>=0.30
Requires-Dist: pyyaml>=6.0
Requires-Dist: numpy>=1.21
Requires-Dist: scipy>=1.9
Provides-Extra: effgenomesize
Requires-Dist: pybedtools>=0.9; extra == "effgenomesize"
Requires-Dist: pandas>=1.3; extra == "effgenomesize"
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Dynamic: license-file

# Tumor Mutational Burden

**Institut Curie - TMB analysis**

[![run with conda](http://img.shields.io/badge/run%20with-conda-3EB049?labelColor=000000&logo=anaconda)](https://docs.conda.io/en/latest/)
[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
[![Version](https://img.shields.io/badge/version-1.6.0-green.svg)](CHANGELOG)

This tool was designed to calculate a **Tumor Mutational Burden (TMB)** score from a VCF file.

The TMB is usually defined as the total number of non-synonymous mutations per coding area of a tumor genome. This metric is mainly used as a biomarker in clinical practice to determine whether to use or not immunomodulatory anticancer drugs (immune checkpoint inhibitors such as Nivolumab). Whole Exome Sequencing (WES) allows comprehensive measurement of TMB and is considered the gold standard. In practice, as TMB is mainly used in the routine of the clinic, and due to the high cost of WES, TMB calculation based on gene panels is preferred.

Currently, the main limitation of TMB calculation is the lack of standard for its calculation. Therefore, we decided to propose a very **versatile** tool allowing the user to define exactly which type of variants to use or filter.

---

## Tool summary

### Installation

#### Option 1 — conda environment + pip (recommended)

```bash
# 1. Create and activate the conda environment
conda env create -f environment.yml
conda activate pyTMB_new

# 2. Install the package (regular)
pip install .

# 3. Or install in editable / development mode
pip install -e .

# 4. To also enable pyEffGenomeSize (requires pybedtools + pandas)
pip install -e ".[effgenomesize]"
```

After installation two CLI commands are available directly in your `$PATH`:

```
pyTMB
pyEffGenomeSize
```

#### Option 2 — conda only (pre-built bioconda package)

```bash
conda env create -n pytmb
conda activate pytmb
conda install -c bioconda -c conda-forge tmb=1.6.0
```

#### Option 3 — run scripts directly (backward-compatible shims)

The `bin/` directory still contains thin wrapper scripts that delegate to the
installed package.  After installing with `pip install .` you can still call:

```bash
python bin/pyTMB.py [options]
python bin/pyEffGenomeSize.py [options]
```

### Recommendations

In order to have homogenous VCF entry files and to avoid VCF ambiguities, we recommend to normalize the VCF files before calculating the TMB. This is especially useful if the VCF file contains Multi Nucleotide Variants (MNVs) or multiallelic variants.

```bash
bcftools norm -f FASTA -m -o file_norm.vcf file
```

### Implementation

The idea behind this tool is quite simple. All variants are scanned and filtered according to the criteria provided by the user. If a variant passes all the filters, it is therefore used for the TMB calculation. In other words, if no filters are provided, the tool will simply count the number of variants.

The TMB is defined as the number of variants over the size of the genomic region (in Mb).  
To calculate the effective genome size, the user can provide a BED file (`--bed`) with the design of the assay.  
This BED file should be ordered, 0-based and with no header.  
Another alternative is to specify the size directly using `--effGenomeSize`.  
Importantly, **it is the user's responsibility to provide the BED corresponding to the VCF input file.**

We also provide the `pyEffGenomeSize` command to calculate the effective size from a BAM file using annotations, coverage and mapping quality thresholds defined by the user.

---

## Package structure

Since version 1.6.0, the code is organized as an installable Python package:

```
pytmb/
├── __init__.py           # version + public API
├── config.py             # loadConfig()
├── vcf_utils.py          # getTag(), getMultiAlleleHeader()
├── genome_size.py        # getEffGenomeSizeFromBed(), getEffGenomeSizeFromMosdepth()
├── filters.py            # isAnnotatedAs(), isPolym(), isCancerHotspot(), …
├── tmb.py                # calculate_tmb() — importable library function
└── cli/
    ├── run_tmb.py        # pyTMB entry point
    └── run_effgenomesize.py  # pyEffGenomeSize entry point
```

The core `calculate_tmb()` function can also be used programmatically:

```python
from pytmb import calculate_tmb, loadConfig

db_flags     = loadConfig("config/snpeff.yml")
caller_flags = loadConfig("config/mutect2.yml")

results = calculate_tmb(
    vcf_path="sample.vcf.gz",
    db_flags=db_flags,
    caller_flags=caller_flags,
    eff_genome_size=33_280_000,
    vaf=0.05,
    maf=0.001,
    min_depth=20,
    min_alt_depth=2,
    filter_low_qual=True,
    filter_non_coding=True,
    filter_syn=True,
    filter_polym=True,
    polym_db="1k,gnomad",
)
print("TMB =", results["tmb"])
```

---

## Quick help

```bash
pyTMB -h

usage: pyTMB [-h] -i VCF --dbConfig DBCONFIG --varConfig VARCONFIG
             [--sample SAMPLE] [--effGenomeSize EFFGENOMESIZE] [--bed BED]
             [--vaf VAF] [--maf MAF] [--minDepth MINDEPTH]
             [--minAltDepth MINALTDEPTH] [--filterLowQual] [--filterIndels]
             [--filterCoding] [--filterSplice] [--filterNonCoding]
             [--filterSyn] [--filterNonSyn] [--filterCancerHotspot]
             [--filterPolym] [--filterRecurrence] [--polymDb POLYMDB]
             [--cancerDb CANCERDB] [--verbose] [--debug] [--export EXPORT]
             [--version]

Calculate a Tumour Mutational Burden (TMB) score from a VCF file.

options:
  -h, --help            show this help message and exit
  -i VCF, --vcf VCF     Input file (.vcf, .vcf.gz, .bcf, .bcf.gz) (default: None)
  --dbConfig DBCONFIG   Databases config file (YAML) (default: None)
  --varConfig VARCONFIG Variant calling config file (YAML) (default: None)
  --sample SAMPLE       Specify the sample ID to focus on (default: None)
  --effGenomeSize EFFGENOMESIZE
                        Effective genome size (bp) (default: None)
  --bed BED             Capture design BED file (default: None)
  --vaf VAF             Filter variants with Allelic Ratio < vaf (default: 0)
  --maf MAF             Filter variants with MAF > maf (default: 1)
  --minDepth MINDEPTH   Filter variants with depth < minDepth (default: 1)
  --minAltDepth MINALTDEPTH
                        Filter variants with alt-allele depth < minAltDepth (default: 1)
  --filterLowQual       Filter low quality (not PASS) variants (default: False)
  --filterIndels        Filter insertions/deletions (default: False)
  --filterCoding        Filter coding variants (default: False)
  --filterSplice        Filter splice variants (default: False)
  --filterNonCoding     Filter non-coding variants (default: False)
  --filterSyn           Filter synonymous variants (default: False)
  --filterNonSyn        Filter non-synonymous variants (default: False)
  --filterCancerHotspot Filter variants annotated as cancer hotspots (default: False)
  --filterPolym         Filter polymorphism variants (see --maf) (default: False)
  --filterRecurrence    Filter on run-level recurrence values (default: False)
  --polymDb POLYMDB     Databases for polymorphism detection, comma-separated (default: gnomad)
  --cancerDb CANCERDB   Databases for cancer hotspot annotation, comma-separated (default: cosmic)
  --verbose             Activate verbose mode (default: False)
  --debug               Export original VCF with TMB_FILTER tag (default: False)
  --export EXPORT       Export a VCF with passing variants to this path (default: None)
  --version             Version number
```

---

## Configs

Working with VCF files is usually not straightforward, and mainly depends on the variant caller and annotation tools/databases used.
In order to make this tool as flexible as possible, we set up **two configuration files** to define which fields have to be checked and in which case.

The `--dbConfig` file describes all details about annotation. We provide configurations for:
- **Annovar** — `config/annovar.yml`
- **snpEff** — `config/snpeff.yml`
- **VEP** — `config/vep.yml`

These files can be customized by the user.

The `--varConfig` file contains all variant-caller-specific parameters. Config files for:
- **Varscan2** — `config/varscan2.yml`
- **Mutect2** — `config/mutect2.yml`
- **Strelka** — `config/strelka.yml`

are provided as examples.

The `yaml` config files list the different **key:values** for each function.
For example, to assess whether a variant is coding (for Annovar):

```yaml
isCoding:
  Func.refGene:
    - exonic
```

Regarding databases, the polymorphism fields for Annovar are:

```yaml
polymDb:
  1k:
    - 1000g2015aug_all
  gnomad:
    - gnomAD_exome_ALL
  esp:
    - esp6500siv2_all
  exac:
    - ExAC_ALL
```

The user can then choose databases with `--polymDb 1k,gnomad,esp,exac`.  
The same logic applies for `--cancerDb`.

---

## Usage

### `pyTMB`

#### General parameters

##### `-i`
Input file (`.vcf`, `.vcf.gz`, `.bcf`, `.bcf.gz`)

##### `--sample`
Specify the sample ID to focus on. Required when dealing with multi-sample VCFs.

##### `--bed` and `--effGenomeSize`
Specify either a sorted BED file with no header, or the size of the effective genome directly.

### Filters

#### `--vaf MINVAF`
Filter variants with Allelic Ratio < minVAF. The field name is defined in `config/caller.yml`.
The tool first checks the **FORMAT** field and then falls back to the **INFO** field.

#### `--maf MAXMAF`
Filter variants with MAF > maxMAF. The databases to use are set with `--polymDb`
and the `config/databases.yml` file.

#### `--minDepth MINDEPTH`
Filter variants with depth < minDepth. The field name is defined in `config/caller.yml`.
The tool first checks the **FORMAT** field and then falls back to the **INFO** field.

#### `--minAltDepth MINALTDEPTH`
Filter variants with alternative allele depth < minAltDepth. Checked in the **FORMAT** field.

#### `--filterLowQual`
Filter variants for which the **FILTER** field is not **PASS** or for which the **QUAL** value is not null.

#### `--filterIndels`
Filter insertion/deletion variants.

#### `--filterCoding`
Filter coding variants as defined in the `config/databases.yml` file.

#### `--filterSplice`
Filter splice variants as defined in the `config/databases.yml` file.

#### `--filterNonCoding`
Filter non-coding variants as defined in the `config/databases.yml` file.

#### `--filterSyn`
Filter synonymous variants as defined in the `config/databases.yml` file.

#### `--filterNonSyn`
Filter non-synonymous variants as defined in the `config/databases.yml` file.

#### `--filterCancerHotspot`
Filter variants annotated as cancer hotspots as defined in the `config/databases.yml` file.
All variants with a cancer annotation (e.g. a COSMIC ID) will be removed.

#### `--filterPolym`
Filter polymorphism variants from genome databases. The databases can be listed with `--polymDb`.
The fields to scan for each database are defined in `config/databases.yml` and the population
frequency is compared against `--maf`.

#### `--filterRecurrence`
Filter on run-level recurrence values. The VCF must already contain recurrence information
as defined in the `config/databases.yml` file.

### Outputs

By default, the tool prints a summary with the calculated TMB value.

#### `--export PATH`
Export a VCF file containing only the variants used for TMB calculation.

#### `--debug`
Export a VCF file with the tag **TMB_FILTERS** in the **INFO** field. This tag contains the
reason why each variant would be filtered.

---

### `pyEffGenomeSize`

This tool calculates the effective genome size from a BAM file. This parameter has a strong
impact on the TMB result. For instance, if only coding variants are used it makes sense to
restrict the denominator to coding regions only.

```bash
pyEffGenomeSize -h

usage: pyEffGenomeSize [-h] --bed BED [--gtf GTF] [--bam BAM]
                       [--minCoverage MINCOVERAGE] [--minMapq MINMAPQ]
                       [--filterNonCoding] [--filterCoding]
                       [--featureTypes FEATURETYPES [FEATURETYPES ...]]
                       [--saveIntermediates] [-t THREAD]
                       [--oprefix OPREFIX] [--verbose] [--version]
```

#### General parameters

##### `--bed`
The input BED file to filter. Should be 0-based, sorted, and with no header. **Required.**

##### `--gtf`
A sorted GTF file for genome annotation (e.g. `gencode.v19.annotation.gtf` or `.gtf.gz`).

##### `--bam`
A BAM file from your experiment to extract mapping quality and coverage information.
When provided, mosdepth is automatically run to filter regions based on coverage and mapping quality.

#### Filters

##### `--minCoverage`
Minimum coverage per region of the BED file. Requires `--bam`.

##### `--minMapq`
Mapping quality threshold. Reads below this value are ignored. Requires `--bam`.

##### `--filterNonCoding`
Remove regions considered non-coding from the GTF/BED intersection to keep only exonic regions.
Requires `--gtf`.

##### `--filterCoding`
Remove regions considered coding based on the `transcript_type` field in the GTF.
Requires `--gtf` and `--featureTypes`.

##### `--featureTypes`
Choose one or more feature types from `exon`, `gene`, `transcript`, `UTR`, `CDS` to
retain in the final BED file. Default: `exon`. Required with `--filterCoding`.

#### Output / Misc

##### `--saveIntermediates`
Keep intermediate files (mosdepth output, filtered GTF, intersect BED) instead of deleting them.

##### `-t`, `--thread`
Number of threads for mosdepth. Default: 1.

##### `--oprefix`
Output file prefix. Default: `pyeffg`.

##### `--verbose`
Activate verbose mode.

##### `--version`
Show version number.

---

## Usage examples and recommendations

### Gene Panel

Calculate the TMB on a gene panel VCF (coding size = 1.59 Mb, caller = Varscan2, annotation = Annovar)
with the following criteria:
- minDepth at 100×
- non-synonymous, coding and splice variants only
- polymorphisms filtered using 1K, gnomAD databases at MAF 0.001 (0.1%)

```bash
pyTMB -i ${VCF} \
    --effGenomeSize 1590000 \
    --dbConfig config/annovar.yml \
    --varConfig config/varscan2.yml \
    --maf 0.001 --minDepth 100 --minAltDepth 2 \
    --filterLowQual \
    --filterNonCoding \
    --filterSplice \
    --filterSyn \
    --filterPolym --polymDb 1k,gnomad \
    --export panel_tmb_variants.vcf.gz \
    > TMB_results.log
```

### Whole Exome Sequencing

For WES, filter low-quality, non-coding, synonymous and polymorphic variants.
Indels and splicing variants are kept. An effective genome size of 33 Mb is used.

For Mutect2 + snpEff:

```bash
pyTMB -i ${VCF} \
    --effGenomeSize 33280000 \
    --dbConfig config/snpeff.yml \
    --varConfig config/mutect2.yml \
    --vaf 0.05 --maf 0.001 --minDepth 20 --minAltDepth 2 \
    --filterLowQual \
    --filterNonCoding \
    --filterSyn \
    --filterPolym --polymDb 1k,gnomad \
    > TMB_results.log
```

---

## Credits

This pipeline has been written by the bioinformatics core facility in close collaboration with the Clinical Bioinformatics and the Genetics Service of the Institut Curie. Many thanks to the seqOIA-IT team for their help in the development and for the extensive testing of the tool!

If you are using this tool for your own research, please cite:  
Dupain, C., Gutman, T., Girard, E. et al. *Tumor mutational burden assessment and standardized bioinformatics approach using custom NGS panels in clinical routine.* BMC Biol 22, 43 (2024). https://doi.org/10.1186/s12915-024-01839-8

## AI Disclosure: Augmented

This project is **AI-augmented** and utilized AI (e.g., Claude) to:
* **Generate** boilerplate code and specific utility functions.
* **Refactor** existing code for better performance and readability.
* **Draft** unit tests and technical documentation.

**Verification:** Every AI-generated contribution was manually reviewed, debugged, and integrated into the final codebase.

## Contacts

For any question, bug or suggestion, please use the issues system or contact the bioinformatics core facility.
