DOCSEARCHbyAlgolia
Submit Docs

infercnvpy

repository·main·Indexed 41 days ago

https://github.com/icbi-lab/infercnvpy

A scalable Scanpy plugin for inferring copy number variation (CNV) events from single-cell transcriptomics data. It provides a Python implementation of the InferCNV algorithm and integrates with the Scanpy ecosystem, operating on AnnData objects. The library includes modules for I/O, preprocessing, plotting, and computational tools such as copyKAT, CNV scoring, and genomic smoothing.

Tokens
9.4K
Snippets
33
Records
45
Agent score
51%

What's inside infercnvpy

  1. Understand the inferCNV computation steps

    main

    The infercnvpy.tl.infercnv function implements a computationally efficient version of the inferCNV algorithm using numpy, scipy, and sparse matrices. The pipeline follows these steps:

    1. Log Fold Change Calculation: Subtracts reference gene expression from all cells. If multiple reference categories are provided via reference_cat, the log fold change is 'bounded' to prevent false positives caused by cell-type specific expression (e.g., HLA or Immunoglobulin genes).
    2. Clipping: Clips fold changes at -lfc_cap and +lfc_cap.
    3. Genomic Smoothing: Smooths expression by genomic position using a running window of length window_size and a stride of step.
    4. Centering: Centers smoothed expression by subtracting the median of each cell.
    5. Noise Filtering: Sets values to 0 if they are less than dynamic_threshold * STDDEV (where STDDEV is the standard deviation of the smoothed expression).
    6. Median Filtering: Applies a final median filter to the result.

  2. Understand the infercnvpy API structure

    main

    The infercnvpy library is organized into modules that mirror the scanpy ecosystem, allowing users to perform different stages of CNV analysis on AnnData objects:

    • io (Input/Output): Functions for reading data and mapping genomic positions (e.g., genomic_position_from_biomart, genomic_position_from_gtf, read_scevan).
    • pp (Preprocessing): Preprocessing steps (e.g., neighbors).
    • tl (Tools): Computational tools that add interpretable annotations to the AnnData object. Note that while these mirror scanpy tools, they operate on CNV data rather than transcriptomics data. Tools include:
      • InferCNV: infercnv, copykat
      • CNV scores: cnv_score, ithcna, ithgex
      • Embeddings: pca, umap, tsne
      • Clustering: leiden
    • pl (Plotting): Visualization functions for results (e.g., chromosome_heatmap, umap, tsne).
    • datasets: Built-in datasets for testing or reference (e.g., maynard2020_3k, oligodendroglioma).

  3. Enforce code-style with prek

    main

    The project uses pre-commit hooks for code-style enforcement. It is recommended to use prek (a fast replacement for pre-commit) to run these checks locally.

    To set up:

    1. Install prek (e.g., uv tool install prek).
    2. Run prek install in the repository root.

    If you push changes and pre-commit.ci (the GitHub service) automatically commits fixes to your branch, integrate them using git pull --rebase.

    uv tool install prek
prek install
git pull --rebase

  4. Build documentation locally

    main

    You can build the project documentation locally using Hatch, uv, or Pip. The documentation is built using Sphinx and supports Markdown via the MyST extension.

    Using Hatch

    hatch run docs:build
hatch run docs:open

    Using uv

    cd docs
uv run sphinx-build -M html . _build -W
(xdg-)open _build/html/index.html

    Using Pip

    source .venv/bin/activate
cd docs
sphinx-build -M html . _build -W
(xdg-)open _build/html/index.html

  6. Run automated tests with pytest

    main

    Tests are written using pytest. Depending on your environment manager, use the following commands to run them from the repository root:

    Hatch:

    • hatch test (highest supported version)
    • hatch test --all (all supported versions)

    uv:

    • uv run pytest

    Pip:

    • source .venv/bin/activate && pytest
    hatch test
uv run pytest
source .venv/bin/activate
pytest

  7. Configure VS Code for development with Hatch

    main

    To use Hatch environments in VS Code:

    1. Install the hatch-code extension.
    2. Ensure vscode-python-environments is installed.
    3. In settings.json, set "python.useEnvironmentsExtension": true.
    4. Open the "Python Environment Managers" sidebar via the command palette (Ctrl+Shift+P -> Python: Focus on Environment Managers View).
    5. Expand "Hatch" and click the checkmark next to the desired environment. It is recommended to use hatch-test with the latest supported Python version.

  8. Prepare input data for inferCNV

    main

    To use infercnvpy, your anndata.AnnData object must meet the following requirements:

    1. Quality Control: The object should be pre-filtered for low-quality cells.
    2. Normalization: adata.X must be normalized and log-transformed (e.g., using scanpy.pp.normalize_total).
    3. Reference Data: The method requires a reference to compare genomic region expression against. You can provide a reference in three ways:
      • Default (Global Average): If no reference is specified, the average of all cells in the dataset is used.
      • Cell-type Annotations: If you have known 'normal' cells, provide the name of the column in adata.obs to reference_key and specify the normal cell categories in reference_cat.
      • External Array: You can provide a numpy array of average gene expression values to the reference parameter. This array must align with the var axis of your AnnData object.

  9. Configure R environment for copyKAT algorithm

    main

    To use the copyKAT algorithm, you must have a working R installation and the copykat R package installed. infercnvpy uses rpy2 to interface with R, which typically detects R automatically if it is in your PATH.

    If you encounter errors during import, manually set the R_HOME environment variable before importing infercnvpy in your Python script.

    import os

os.environ["R_HOME"] = "/usr/lib/R"
import infercnvpy

  10. Writing documentation for infercnvpy

    main

    The project uses Sphinx for documentation with several key extensions:

    • MyST: Allows writing documentation in Markdown/Markedly Structured Text.
    • Numpy-style docstrings: Handled via the napoleon extension.
    • myst-nb: Renders Jupyter notebooks located in docs/notebooks as tutorials. Only .ipynb files are currently supported, and they must include both input and output cells. You are responsible for re-running notebooks to ensure outputs are up to date.
    • sphinx-autodoc-typehints: Automatically references annotated input and output types.
    • sphinxcontrib-bibtex: Used for including citations (e.g., {cite:p}Virshup_2023`).

    Configuration Hints

    • External Links: To link to objects in other packages, add an entry to intersphinx_mapping in docs/conf.py.
    • Ignoring Broken Links: If a build fails due to an external link you cannot control, add the link to the nitpick_ignore list in docs/conf.py.

  12. Install development dependencies using Hatch

    main

    The project uses hatch as its primary project manager to handle virtual environments for testing and documentation. To run tests or build documentation, use the following commands which automatically resolve the necessary environments:

    • Run tests: hatch test (uses the highest supported Python version).
    • Run tests for all supported versions: hatch test --all.
    • Build documentation: hatch run docs:build.
    hatch test
hatch run docs:build