Compatibility and other I/O¶
Print CNVkit’s version as a string on standard output:
If you submit a bug report or feature request for CNVkit, please include the CNVkit version in your message so we can help you more efficiently.
Convert Picard CollectHsMetrics (formerly CalculateHsMetrics) per-target coverage files (.tsv) to the CNVkit .cnn format:
cnvkit.py import-picard *.hsmetrics.targetcoverages.tsv *.hsmetrics.antitargetcoverages.csv cnvkit.py import-picard picard-hsmetrics/ -d cnvkit-from-picard/
You can use Picard tools to perform the bin read depth and GC calculations that CNVkit normally performs with the coverage and reference commands, if need be.
- Use the target and antitarget commands to generate the “targets.bed” and “antitargets.bed” files.
- Convert those BED files to Picard’s “interval list” format by adding the BAM header to the top of the BED file and rearranging the columns – see the Picard command BedToIntervalList.
- Run Picard CollectHsMetrics on each of your normal/control BAM files with the “targets” and “antitargets” interval lists (separately), your reference genome, and the “PER_TARGET_COVERAGE” option.
- Use import-picard to convert all of the PER_TARGET_COVERAGE files to CNVkit’s .cnn format.
- Use reference to build a CNVkit reference from those .cnn files. It will retain the GC values Picard calculated; you don’t need to provide the reference genome sequence again to get GC (but you if you do, it will also calculate the RepeatMaster fraction values)
- Use batch with the
--referenceoption to process the rest of your test samples.
Convert a file in the SEG format (e.g. the output of standard CBS or the GenePattern server) into one or more CNVkit .cns files.
The chromosomes in a SEG file may have been converted from chromosome names to
integer IDs. Options in
import-seg can help recover the original names.
- To add a “chr” prefix, use “-p chr”.
- To convert chromosome indices 23, 24 and 25 to the names “X”, “Y” and “M” (a common convention), use “-c human”.
- To use an arbitrary mapping of indices to chromosome names, use a comma-separated “key:value” string. For example, the human convention would be: “-c 23:X,24:Y,25:M”.
Convert the “.results” output of THetA2 to one or more CNVkit .cns files representing subclones with integer absolute copy number in each segment.
cnvkit.py import-theta Sample.cns Sample.BEST.results
See the page on tumor Tumor heterogeneity for more guidance on performing this analysis.
Convert copy number ratio tables (.cnr files) or segments (.cns) to another format.
Segments can be exported to BED format to support a variety of other uses, such
as viewing in a genome browser.
By default only regions with copy number different from the given ploidy
(default 2) are output. (Notice what this means for allosomes.)
To output all segments, use the
--show all option.
The BED format represents integer copy numbers in absolute scale, not log2 ratios. If the input .cns file contains a “cn” column with integer copy number values, as generated by the call command, export bed will use those values. Otherwise the log2 ratio value of each input segment is converted and rounded to an integer value, similar to the call -m clonal method.
# Estimate integer copy number of each segment cnvkit.py call Sample.cns -y -o Sample.call.cns # Show estimated integer copy number of all regions cnvkit.py export bed Sample.call.cns --show all -y -o Sample.bed
The same BED format can also specify CNV regions to the FreeBayes variant caller
# Show only CNV regions cnvkit.py export bed Sample.call.cns -o all-samples.cnv-map.bed
Convert segments, ideally already adjusted by the call command, to a VCF file. Copy ratios are converted to absolute integers, as with BED export, and VCF records are created for the segments where the copy number is different from the expected ploidy (e.g. 2 on autosomes, 1 on haploid sex chromosomes, depending on sample sex).
A sample’s chromosomal sex can be specified with the
--sample-sex option, or will be guessed automatically.
If the option
--haploid-x-reference was used
to construct the reference, use it here, too.
cnvkit.py export vcf Sample.cns -y -x female -i "SampleID" -o Sample.cnv.vcf
A collection of probe-level copy ratio files (
*.cnr) can be exported to Java
TreeView via the standard CDT format or a plain text table:
cnvkit.py export jtv *.cnr -o Samples-JTV.txt cnvkit.py export cdt *.cnr -o Samples.cdt
Similarly, the segmentation files for multiple samples (
*.cns) can be
exported to the standard SEG format to be loaded in the Integrative Genomic
cnvkit.py export seg *.cns -o Samples.seg
nexus-basic can be loaded directly by the commercial program
Biodiscovery Nexus Copy Number, specifying the “basic” input format in that
program. This allows viewing CNVkit data as if it were from array CGH.
This is a tabular format very similar to .cnr files, with the columns:
nexus-ogt can be loaded directly by the commercial program
Biodiscovery Nexus Copy Number, specifying the “Custom-OGT” input format in that
program. This allows viewing CNVkit data as if it were from a SNP array.
This is a tabular format similar to .cnr files, but with B-allele frequencies (BAFs) extracted from a corresponding VCF file. The format’s columns are (with .cnr equivalents):
- “Chromosome” (chromosome)
- “Position” (start)
- “Position” (end)
- “Log R Ratio” (log2)
- “B-Allele Frequency” (from VCF)
The positions of each heterozygous variant record in the given VCF are matched to bins in the given .cnr file, and the variant allele frequencies are extracted and assigned to the matching bins.
- If a bin contains no variants, the BAF field is left blank
- If a bin contains multiple variants, the BAFs of those variants are “mirrored” to be all above .5 (e.g. BAF of .3 becomes .7), then the median is taken as the bin-wide BAF.
THetA2 is a program for estimating normal-cell contamination and tumor subclone population fractions based on a tumor sample’s copy number profile and, optionally, SNP allele frequencies. (See the page on tumor Tumor heterogeneity for more guidance.)
THetA2’s input file is a BED-like file, typically with the extension
.interval_count, listing the read counts within each copy-number segment in
a pair of tumor and normal samples.
CNVkit can generate this file given the CNVkit-inferred tumor segmentation
(.cns), bypassing the initial step of THetA2, CreateExomeInput, which counts the
reads in each sample’s BAM file.
The normal-sample read counts in this file are used for weighting each segment
in THetA2’s calculations. We recommend providing these to
export theta via
the CNVkit pooled or paired reference file (.cnn) you created for your panel:
# From an existing CNVkit reference cnvkit.py export theta Sample_Tumor.cns reference.cnn -o Sample.theta2.interval_count
The THetA2 normal read counts can also be derived from the normal sample’s bin log2 ratios, if for some reason this is all you have:
# From a paired normal sample cnvkit.py export theta Sample_Tumor.cns Sample_Normal.cnr -o Sample.theta2.interval_count
If neither file is given, the THetA2 normal read counts will be calculated from the segment weight values in the given .cns file, or the number of probes if the “weight” column is missing, or as a last resort, the segment sizes if the “probes” column is also missing:
# From segment weights and/or probe counts cnvkit.py export theta Sample_Tumor.cns -o Sample.theta2.interval_count
THetA2 also can take the tumor and normal samples’ SNP allele frequencies as
input to improve its estimates. THetA2 uses another custom format for these
values, and provides another script for creating these files from VCF that we’d
again prefer to bypass. CNVkit’s
export theta command produces these two
additional files when given a VCF file of paired tumor-normal SNV calls with the
cnvkit.py export theta Sample_Tumor.cns reference.cnn -v Sample_Paired.vcf
This produces three output files;
-o will be used for the read count file,
while the SNV allele count files will be named according to the .cns file, e.g.