API Reference¶

scParams.cellMetadata¶

This mapping specifies which cells belong to each sample and cell group.

Type: a dictionary specifying the file path and column names for a CSV, TSV, or AnnData .obs source.

The path can be one of

CSV/TSV file (optionally gzipped): contains cell metadata with columns for barcodes (barcodeColumn), sample IDs (sampleColumn), and group labels (groupColumn)
AnnData (.h5ad) file: contains cell metadata in the .obs table.

Field	Type	Use
`path`	`str`	Required. A `.csv`, `.tsv`, or `.h5ad` file. CSV/TSV may use `.gz`.
`barcodeColumn`	`str \| None`	Cell identifier column. Required for CSV/TSV. Omit this for AnnData/H5AD so that `.obs_names` is used
`sampleColumn`	`str \| None`	Column used to match metadata rows to an input sample, e.g. `library` below. Required when the metadata file covers multiple input samples.
`groupColumn`	`str \| None`	Cell-group column, such as `cellType`. Required for group selection.

Example.

cells.csv¶
barcode	library	cellType
AAACGAAAGTACGCCC-1	PBMC_01	CD4_T
AAACGAACAGCTACAT-1	PBMC_01	B_cell
AAACGAAGTCGTTGGC-1	PBMC_01	NK_cell
AAACGAAAGTACGCCC-1	PBMC_02	CD8_T
AAACGAATCTTACGGA-1	PBMC_02	B_cell
AAACGAAGTACAGCGA-1	PBMC_02	CD4_T

For the cells.csv table above, specify the column names under scParams.cellMetadata in the Consenrich YAML:

scParams:
  cellMetadata:
    path: cells.csv
    barcodeColumn: barcode
    sampleColumn: library
    groupColumn: cellType

With sampleColumn: library, an input named PBMC_01 is matched to the three rows labelled PBMC_01. If that input is named replicate1, you would set metadataSample: PBMC_01 on the input to keep the same match.

scParams.fits¶

Use this to specify multiple Consenrich jobs for different cell groups within the same dataset, in one YAML file. See, for example, the scATAC-seq example.

Type: list[dict[str, str | list[str]]] | None.

Default: None (one run without a fit list).

Each entry requires name and selectGroups:

name (str) names the output directory, e.g. TCells. Must be unique
selectGroups (list[str]) holds one or more unique labels from groupColumn, matched exactly

# ...other consenrich config...


scParams:
  fits:
    - {name: TCells, selectGroups: [CD4_T, CD8_T]} # Run a fit for T cells
    - {name: BCells, selectGroups: [B_cell]}       # and run a fit for B cells, too

inputParams.samples¶

Input files and source-specific settings.

Type: list[str | dict[str, Any]] | None. Default: None.

Supply a nonempty list. H5AD counts require a mapping with matrixRows.

Field	Type	Use / default
`path`	`str`	Required. E.g. `library1.fragments.tsv.gz` or `library1.h5ad`.
`name`	`str \| None`	Output label and default metadata sample identifier. Default: `None`.
`cellMetadata`	`dict[str, str \| None] \| None`	Replaces `scParams.cellMetadata` for that source. Default: `None` uses the shared setting.
`metadataSample`	`str \| None`	Value to select from `sampleColumn`, e.g. `library1`. Default: `None` uses `name`.
`matrixRows`	`str \| None`	Required for H5AD counts. `cells` sums selected rows. `pseudobulks` selects exactly one row per source and fit. Default: `None`.
`countMode`	`str \| None`	Fragment counting override. Default: `None` uses `scParams.defaultCountMode`. Rejected for H5AD counts.
`fragmentsUseReadSupport`	`bool`	`True` weights fragment rows by column five. Inherits `scParams.fragmentsUseReadSupport`, which defaults to `False`.

Fragment countMode choices: coverage, cutsite, fiveprime, center, midpoint, or conservedFractionalOverlap. Use center to count fragment centers.

H5AD count requirements¶

.X contains raw, nonnegative integer counts. Dense, CSR, and CSC storage are supported, including integer-valued floats.
.var contains chrom, start, and end for complete, regular chromosome grids in 0-based, half-open coordinates. Terminal bins may be shorter.
countingParams.intervalSizeBP is inferred when omitted. All H5AD inputs must share that width, and an explicit value must match. Fragment inputs in the same run use that width.

Normalization uses countingParams.normMethod. H5AD supports CPM, RPKM, SF, or supplied scale factors. EGS/RPGC require supplied factors. Fragment barcode-file options on H5AD inputs are ignored with a warning.

See the single-cell examples for complete configurations.