Skip to contents

Gives each bin of each sample an expected read count from the median read rate of the sample's autosomal training bins in the same GC stratum, so that `ratio = reads / expected` is about 1 for two copies, 0.5 for one and 1.5 for three. The output feeds [rduckhts_depth_region_fraction()] and [rduckhts_depth_sex_fraction()]. Normalization uses eligible autosomal bins with positive reads; empty bins retain zero ratios when their bin and stratum rules pass.

Usage

rduckhts_depth_bins(
  con,
  bins_table,
  min_mappability = 0.9,
  gc_step = 0.01,
  min_stratum_bins = 10,
  outlier_quantile = 0.01,
  max_ratio = 4,
  table_name = NULL,
  overwrite = FALSE
)

Arguments

con

A DuckDB connection with DuckHTS loaded.

bins_table

Name of a table or view with `sample_id`, `chrom`, `start`, `end` (zero-based, half-open), `reads` and `gc` (the G+C share of the A, C, G and T reference bases, from 0 to 1), and optionally `mappability` (0 to 1).

min_mappability

Bins with a lower mappability are not kept.

gc_step

Width of a GC stratum, in \[1/2147483647, 1\], so the stratum number fits the integer output column.

min_stratum_bins

Training bins a stratum needs, a whole number.

outlier_quantile

Training bins outside this quantile of the read rate, and its complement, set no stratum median; in \[0, 0.5).

max_ratio

Bins with a higher ratio are not kept; above 1.

table_name

Optional table to create instead of returning a data frame.

overwrite

Whether `table_name` may replace an existing table.

Value

A data frame (or invisible `TRUE` when `table_name` is given) with one row per input row: `sample_id`, `chrom`, `start`, `end`, `reads`, `gc`, `mappability`, `gc_stratum`, `stratum_bins`, `expected`, `ratio`, `log2_ratio`, `reason`, `kept` and `method`.

Details

The GC stratum of a bin is `floor(gc / gc_step)`. Training bins are autosomal bins that pass the bin rules, hold at least one read and have a read rate inside the `outlier_quantile` and `1 - outlier_quantile` quantiles of the sample. A bin is kept unless it lacks a count or a GC value, has a mappability below `min_mappability` (when the relation has a `mappability` column), falls in a stratum with fewer than `min_stratum_bins` training bins, or has a ratio above `max_ratio`; `reason` names the rule. Only `max_ratio` looks at a bin's count, so a bin with no reads stays kept. Autosomal means a contig whose `duckhts_contig_key()` is not X, Y or MT. Restrict contigs and remove problem bins in SQL first.

See also

[rduckhts_bam_bin_counts()], [rduckhts_fasta_nuc()]

Examples

con <- rduckhts_connect()
DBI::dbExecute(con, paste(
  "CREATE TEMP TABLE bins AS SELECT 'S1' AS sample_id, CAST(c AS VARCHAR) AS chrom,",
  "b * 1000000 AS start, (b + 1) * 1000000 AS \"end\",",
  "0.35 + 0.25 * ((b * 37 + c * 11) % 100) / 100.0 AS gc,",
  "CAST(600 + 4 * ((b * 13 + c * 7) % 11) AS BIGINT) AS reads",
  "FROM range(1, 23) t(c), range(0, 100) r(b)"
))
#> [1] 2200
head(rduckhts_depth_bins(con, "bins")[, c("chrom", "start", "reads", "ratio", "kept")])
#>   chrom start reads     ratio kept
#> 1     1 0e+00   628 1.0129032 TRUE
#> 2     1 1e+06   636 1.0258065 TRUE
#> 3     1 2e+06   600 0.9677419 TRUE
#> 4     1 3e+06   608 0.9806452 TRUE
#> 5     1 4e+06   616 0.9935484 TRUE
#> 6     1 5e+06   624 1.0064516 TRUE
DBI::dbDisconnect(con, shutdown = TRUE)