Skip to main content

pycopykat

A Python implementation of CopyKAT (Gao et al., Nat Biotechnol 2021): copy-number profiles of single cells in 220 kb bins and the call of each cell as aneuploid (tumour) or diploid (normal) from scRNA-seq UMI counts.

Status: v0.2.0 — reproduces R copykat 1.2.5. With the same seed pycopykat gives R's breakpoints, R's baseline cells and R's call for every cell; the copy-number matrices agree to about 1e-10. On six breast tumours of the CopyKAT paper it ran 4.7 to 17 times faster than R on one thread. See Reproducing R below and report/.

Installation

pip install pycopykat

Python 3.10–3.12. The wheel bundles R copykat's reference tables (hg20 and mm10 gene positions, the 220 kb bins, the cell-cycle genes), identical to the package's sysdata.rda.

Usage

import pandas as pd
from pycopykat import CopykatConfig, copykat

counts = pd.read_csv("counts.tsv", sep="\t", index_col=0)     # genes x cells, raw UMI counts
res = copykat(counts, CopykatConfig(id_type="Symbol", genome="hg20", n_jobs=8))

res.prediction        # cell.names, copykat.pred  (as R's res$prediction)
res.cna_mat           # bins x cells, index (chrom, chrompos, abspos)  (R's res$CNAmat)
res.hclustering       # R hclust of the cells (merge, height, order)
res.to_txt("out/", "sample")

copykat also takes an AnnData (cells x genes, counts in X). The arguments of CopykatConfig are those of R copykat() with the same defaults: id_type ("Symbol"/"Ensembl"), genome ("hg20"/"mm10"), cell_line, ngene_chr, min_gene_per_cell, low_dr, up_dr, win_size, ks_cut, distance ("euclidean", "pearson", "spearman") and norm_cell_names (known normal cells); seed is the value R copykat passes to set.seed (1234), and n_jobs sets the threads of the steps without random numbers (results do not depend on it).

Per patient on an AnnData:

from pycopykat import copykat_by_batch
adata = copykat_by_batch(adata, batch_key="patient", config=CopykatConfig(n_jobs=8))
# adata.obs["copykat_pred"], adata.obsm["copykat_cna"], adata.uns["copykat_bins"]

Command line: pycopykat run --input counts.tsv --output-dir out/ --sam-name sample, or pycopykat run-h5ad --adata data.h5ad --batch-key patient --output out.h5ad.

In OmicVerse: ov.single.CNV(adata, method="copykat").run().

Reproducing R

pycopykat follows R copykat 1.2.5 (copykat() and its helpers) step by step, in R's order of genes and cells:

  • Filters and annotation — the cell and gene filters, the annotation (first entry per symbol, data order, then stably by abspos), the removal of HLA and cell-cycle genes and the per-cell chromosome-coverage test (runs of chromosomes over the expressed genes) are R's.
  • Smoothing — log(sqrt(x) + sqrt(x + 1)), centring, and the local-level Kalman smoother of dlm (dlmModPoly(1, dV = 0.16, dW = 0.001)); dlm computes on SVD factors, which shifts the first genes of each cell by about 1e-10.
  • Baseline — hclust(ward.D2) and cutree are ported from R's Fortran and C (nearest-neighbour list, tie order, cluster numbering); mixtools' normalmixEM (three components, common sigma) is ported with its normpost routine, so the EM takes the same iterations; the silhouette, the F test and the GMM fallback (baseline.GMM) follow R. Known normal cells and the cell-line mode (baseline.synthetic, set.seed(123) and rnorm per cluster) are supported.
  • Segmentation — CNA.MCMC draws MCpoissongamma, i.e. rgamma(1000, shape, rate), for every window of the cluster medians and for every segment of every cell. R's Mersenne-Twister, norm_rand (inversion) and rgamma (Ahrens–Dieter GD and GS, exp_rand) are ported (pycopykat._rcompat); the draws are produced in vectorised form and are identical to R's, so the KS breakpoints and the posterior means are R's. ks.test uses R's cumulative sum, and the KS cut-off is lowered as in R when fewer than 25 breakpoints are found.
  • Bins and calls — convert.all.bins.hg20 (gene centres in [start, end] with the start taken from the previous bin, empty bins filled from the nearest bin), the v1.2 classification (ward.D trees cut at k = 4, 3 or 2, the clusters holding the pre-defined diploid cells, the baseline re-adjustment, the correlation rule and the Wasserstein assignment) and the low-confidence labels are R's.

R copykat with n.cores > 1 does not repeat its own results (mclapply children start from unseeded generators); pycopykat always follows the n.cores = 1 stream.

Comparison with R copykat 1.2.5 (same seed, n.cores = 1):

sample (GSE148673) cells breakpoints calls identical max |ΔCNA| pycopykat, 1 thread (s) R (s)
DCIS1 1,480 231 = 231 yes 4.3e-11 80 730
TNBC1 1,097 291 = 291 yes 5.2e-11 72 496
TNBC2 1,034 267 = 267 yes 5.5e-11 62 437
TNBC3 532 326 = 326 yes 5.3e-11 46 220
TNBC4 3,056 252 = 252 yes 6.2e-11 177 2,478
TNBC5 3,225 219 = 219 yes 1.3e-11 165 2,759

Times are the faster of two runs, each on one idle core (report/). Most of the time goes to the segmentation's gamma draws, which come from one sequential random stream; more threads (n_jobs) speed up only the other steps.

The known-normal, cell-line and Pearson-distance modes were checked the same way on TNBC3. tests/test_parity.py checks copykat's example data (exp.rawdata) against stored R results, and tests/test_rcompat.py the R pieces against stored R values; tests/r_reference.R and tests/r_components.R regenerate them.

Testing

pip install -e '.[dev]'
pytest

Citation

Gao R, Bai S, Henderson YC, et al. Delineating copy number and clonal substructure in human tumors from single-cell transcriptomes. Nat Biotechnol 39, 599–608 (2021).

License

GPL-2.0-or-later, as R copykat (GPL-2).

Metadata

Release files for pycopykat 0.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pycopykat 0.2.0
File Size Uploaded Provenance Actions
pycopykat-0.2.0.tar.gz 8.3 MB Without provenance Details for pycopykat-0.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for pycopykat 0.2.0
File Interpreter ABI Platform Actions
pycopykat-0.2.0-py3-none-any.whl Python 3 none any Details for pycopykat-0.2.0-py3-none-any.whl

Total release size: 12.6 MB

Release files / pycopykat-0.2.0.tar.gz

Download URL pycopykat-0.2.0.tar.gz
Size 8.3 MB
Tags Source
SHA-256 checksum
How to use checksums
da1916127b5d70040a8566ca6da79d86b7bd04e73df640b454c5d17ba93dd6c5
BLAKE2b-256 checksum
How to use checksums
36b83ab2abe9bcf3228800033c1804a5188d2695db7a0e6c60b38928cbca16c6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.10.22

Release files / pycopykat-0.2.0-py3-none-any.whl

Download URL pycopykat-0.2.0-py3-none-any.whl
Size 4.2 MB
Tags Python 3
SHA-256 checksum
How to use checksums
3f8ace5c3265c0a56aa0d8f53e5c0b2fb6791a95400fd2039e2092baa99586d8
BLAKE2b-256 checksum
How to use checksums
38755facb6f1b61fbb732b620b87ac99f511f6338056bf8475fa898adff8f605
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.10.22

Security for pycopykat 0.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.2.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page