Build methylation matrix¶

bsbit combine combines per-sample methylation calls into a site-by-sample matrix. It can report methylation levels, methylated and total counts, or both.

Inputs¶

Supply one coordinate-sorted CGmap or extended bedMethyl file per sample. All inputs must use the same reference genome and compatible site coordinates. Plain, gzip-compressed, and BGZF-compressed files are accepted.

Build the matrix¶

bsbit combine \
  -i sample1.CGmap,sample2.CGmap \
  --sample-name sample1,sample2 \
  -o cohort.bed \
  -t 8

Common options¶

Option	Argument	Default	Description
`-i`, `--input`	Comma-separated file paths	Required	Methylation call files, one per sample
`-o`, `--output`	Output path	Required	Destination; with `both`, a template for the level and count paths
`-c`, `--compress`	`true` or `false`	`false`	Write BGZF-compressed output when `true`
`-t`, `--threads`	Positive integer	`1`	Number of input-merge workers
`--matrix`	`level`, `count`, or `both`	`level`	Matrix values to write
`--sample-name`	Comma-separated sample names	Input paths	Sample names used as matrix column labels

Advanced options¶

Option	Argument	Default	Description
`--min-count`	Positive integer	`1`	Minimum total coverage required to retain a sample value
`--min-prop`	Decimal from `0` to `1`	`0`	Minimum fraction of samples that must pass `--min-count` at a site
`--cg-only`	—	Off	Retain only CpG sites

Inputs and sample names

Separate input paths with commas. Their order determines the sample-column order in the matrix. CGmap and extended bedMethyl files may be mixed:

-i sample1.CGmap.gz,sample2.CGmap.gz,sample3.CGmap.gz

--sample-name accepts a matching comma-separated list of unique names. If it is omitted, the exact input path text is used as the column label. Commas delimit values and therefore cannot occur inside a path or label.

Matrix types

--matrix level writes one methylated fraction from 0 to 1 per sample. --matrix count writes methylated and total coverage for each sample. --matrix both produces both matrices from the same merge.

Filtering behavior

Add --cg-only to exclude CHG and CHH sites.

--min-count is applied to each sample first. --min-prop then sets the fraction of samples that must pass at each site; for example, 0.8 requires at least 80%. Every retained site must have at least one valid sample, even when --min-prop is 0.

See the CLI reference for accepted input, and complete option details.

Output¶

The output is a coordinate-sorted BED6-plus-sample table: six genomic-site columns followed by one methylation level per sample with --matrix level, or methylated and total counts with --matrix count. A . represents a missing value or one that does not pass --min-count, instead of zero.

For one matrix type, --output is the exact destination. With --output cohort.bed --matrix both, bsbit creates cohort.level.bed and cohort.count.bed;

See Methylation matrices for the complete schemas, coordinates, and metadata fields. With -c true, use a .gz filename; BGZF-compressed output can then be indexed and queried as BED:

tabix -p bed cohort.level.bed.gz

Index each generated file separately. The matrices can be loaded into R or Python for sample-level quality control, clustering, differential methylation analysis, epigenome-wide association studies (EWAS), or methylation quantitative trait locus (mQTL) mapping.