This section of the user guide contains information on using methbat deconvolve to estimate cell type proportions from methylation data using a reference atlas. This approach uses non-negative least squares (NNLS) regression to deconvolve bulk methylation data into constituent cell types based on a pre-defined atlas of cell type-specific methylation patterns.

Table of contents:

• Quickstart
• Atlas format
• Output files

Quickstart

The following command will perform cell type deconvolution on a single dataset:

methbat deconvolve \
    --input-pileup {PILEUP_BED_GZ} \
    --atlas-regions {ATLAS_FILE} \
    --output-estimate {OUT_JSON}

Parameters:

• --input-pileup {PILEUP_BED_GZ} - a single bgzipped unified pileup BED from methbat pileup (for example {OUT_PREFIX}.5mC.bed.gz). The shipped atlases under public/data/cell_atlas are 5mC-based; this sub-command has not been validated on 5hmC or 6mA pileups.
• --atlas-regions {ATLAS_FILE} - the cell type atlas file in MethBat format; the format is described below and example atlases are provided in the data folder
• --output-estimate {OUT_JSON} - the output JSON file containing deconvolution results
• --strand {combined|forward|reverse} - (optional) row-level strand filter on the input pileup; default combined aggregates across strands. See pileup output strand semantics for what each value selects.

Atlas format

The cell type atlas must be a tab-separated file with the following structure:

Required columns:

• chr - chromosome name; chrom or chromosome are also accepted as column headers
• start - 0-based start coordinate (inclusive)
• end - 0-based end coordinate (exclusive)
• Additional columns for each cell type with methylation values (0.0 to 1.0), where 0.0 is fully unmethylated and 1.0 is fully methylated

Example atlas format:

chr	start	end	adipocyte	endothelial_cell	colon_fibroblasts	heart_fibroblasts	...
chr1	1066168	1066385	0.71	0.81	0.78	0.80	...
chr1	1071849	1072048	0.86	0.86	0.79	0.86	...
chr1	1179392	1179548	0.88	0.91	0.76	0.83	...
...

Available atlases

Pre-formatted atlases are available in the data folder.

Output files

The deconvolution process generates a single JSON output file with the following structure:

{
  "version": "0.16.0-8dcb2bf",
  "atlas_md5sum": "6e30a2eafd8da7410d4e7766c7c71d94",
  "cli_settings": {
    "input_pileup_bed": "./pipeline/methbat_pileup/HG001.5mC.bed.gz",
    "atlas_regions": "./data/cell_atlas/nanomix/39Bisulfite.methbat.tsv",
    "output_estimate": "./HG001_cell_estimate.json",
    "min_active": 0.05
  },
  "metrics": {
    "normalized_fraction": {
      "B-cell": 0.8549362852865744,
      "NK-cell": 0.0,
      ...
    },
    "nnls_raw_fraction": {
      "B-cell": 0.7578555187460534,
      "NK-cell": 0.0,
      ...
    },
    "nnls_residual_error": 12.898144132607202,
    "residual": [
      -0.02371285749724783,
      ...
    ]
  }
}

Field descriptions:

• version - MethBat version used for deconvolution
• atlas_md5sum - MD5 checksum of the atlas file for verification of exact atlas file
• cli_settings - Copy of the command-line parameters used
• metrics - Deconvolution results and statistics:
  • normalized_fraction - Normalized cell type proportions (sum to 1.0)
  • nnls_raw_fraction - Raw cell type proportions from NNLS regression
  • nnls_residual_error - Residual error from the NNLS regression
  • residual - Array of residual values for each region used in deconvolution. This can be useful in identifying regions that are prone to high error rates across multiple datasets.