Skip to main content

R API

Generated from roxygen .Rd topics in r-cfdnalab/man. S3 method signatures are shown so mode-specific arguments are visible, but normal user code should call the exported generic.

Jump To​

Midpoint Profiles​

Load midpoint profile Zarr stores and extract count arrays or data frames by group, fragment length bin, and midpoint position.

TopicSummary
read_midpointsLoads a <prefix>.midpoint_profiles.zarr store created with the cfdna midpoints CLI tool from the main cfDNAlab rust package.
group_metadataReturn group metadata.
length_binsReturn length-bin metadata.
positionsReturn midpoint position-bin metadata.
group_idxLook up a group index.
length_bin_idxLook up the length-bin index containing a fragment length.
profile_arrayReturn one midpoint profile as an array vector.
midpoint_data_frameReturn midpoint profiles as a data frame.
midpoint_arrayReturn the full midpoint count array.
schema_versionReturn the cfDNAlab schema version.

read_midpoints​

read_midpoints

Loads a <prefix>.midpoint_profiles.zarr store created with the cfdna midpoints CLI tool from the main cfDNAlab rust package. It validates the schema, coordinate axes, labels, and count-array shape.

read_midpoints(path)

Arguments

  • path: Path to a cfDNAlab midpoint-profile .zarr directory.

Returns

A cfdnalab_midpoint_profiles object.

Examples

midpoints <- read_midpoints("sample.midpoint_profiles.zarr")
group_metadata(midpoints)
midpoint_data_frame(midpoints, groups = "LYL1", length_bin_idxs = 1)

group_metadata​

group_metadata

Return group metadata.

group_metadata.cfdnalab_grouped_end_motif_counts(x, ...)

group_metadata(x, ...)

group_metadata.cfdnalab_grouped_length_counts(x, ...)

group_metadata.cfdnalab_midpoint_profiles(x, ...)

group_metadata.cfdnalab_grouped_ref_kmer_frequencies(x, ...)

Arguments

  • x: A cfDNAlab object with a group axis.
  • ...: Reserved for future methods.

Returns

A data frame with one row per group.

length_bins​

length_bins

Return length-bin metadata.

length_bins(x, ...)

length_bins.cfdnalab_length_counts(x, ...)

length_bins.cfdnalab_midpoint_profiles(x, ...)

Arguments

  • x: A cfDNAlab object with length bins.
  • ...: Reserved for future methods.

Returns

A data frame with one row per length bin.

positions​

positions

Return midpoint position-bin metadata.

positions(x, ...)

positions.cfdnalab_midpoint_profiles(x, ...)

Arguments

  • x: A cfDNAlab midpoint-profile object.
  • ...: Reserved for future methods.

Returns

A data frame with one row per position bin.

group_idx​

group_idx

Look up a group index.

group_idx.cfdnalab_grouped_end_motif_counts(x, group_name, ...)

group_idx(x, ...)

group_idx.cfdnalab_grouped_length_counts(x, group_name, ...)

group_idx.cfdnalab_midpoint_profiles(x, group_name, ...)

group_idx.cfdnalab_grouped_ref_kmer_frequencies(x, group_name, ...)

Arguments

  • x: A cfDNAlab object with group labels.
  • group_name: Group name to look up.
  • ...: Method-specific lookup arguments.

Returns

A scalar one-based integer group index.

length_bin_idx​

length_bin_idx

Look up the length-bin index containing a fragment length.

length_bin_idx(x, ...)

length_bin_idx.cfdnalab_length_counts(x, length, ...)

length_bin_idx.cfdnalab_midpoint_profiles(x, length, ...)

Arguments

  • x: A cfDNAlab object with length bins.
  • ...: Method-specific lookup arguments.
  • length: Fragment length in base pairs.

Returns

A scalar one-based integer length-bin index.

Details

Errors if no length bin contains the requested fragment length.

profile_array​

profile_array

Return one midpoint profile as an array vector.

profile_array(x, ...)

profile_array.cfdnalab_midpoint_profiles(
  x,
  group_idx = NULL,
  length_bin_idx = NULL,
  group = NULL,
  length = NULL,
  ...
)

Arguments

  • x: A cfDNAlab midpoint-profile object.
  • ...: Method-specific profile selection arguments.
  • group_idx: One-based group index. Use either group_idx or group.
  • length_bin_idx: One-based length-bin index. Use either length_bin_idx or length.
  • group: Group name. Use either group_idx or group.
  • length: Fragment length in base pairs. Use either length_bin_idx or length.

Returns

A numeric vector with one value per position bin.

midpoint_data_frame​

midpoint_data_frame

Return midpoint profiles as a data frame.

midpoint_data_frame(x, ...)

midpoint_data_frame.cfdnalab_midpoint_profiles(
  x,
  groups = NULL,
  group_idxs = NULL,
  with_lengths = NULL,
  with_length_range = NULL,
  length_bin_idxs = NULL,
  ...
)

Arguments

  • x: A cfDNAlab midpoint-profile object.
  • ...: Method-specific profile selection arguments.
  • groups: Optional group name vector. Use either groups or group_idxs, not both.
  • group_idxs: Optional one-based group index vector.
  • with_lengths: Optional fragment length vector in base pairs. Returned rows use the length bins containing these lengths. Multiple lengths must select distinct length bins.
  • with_length_range: Optional two-value fragment length range in base pairs. Returned rows use whole length bins that overlap the half-open range [start, end).
  • length_bin_idxs: Optional one-based length-bin index vector. Use only one of with_lengths, with_length_range, or length_bin_idxs.

Returns

A data frame with one row per selected group, length bin, and position bin.

midpoint_array​

midpoint_array

Return the full midpoint count array.

midpoint_array(x, ...)

midpoint_array.cfdnalab_midpoint_profiles(x, ...)

Arguments

  • x: A cfDNAlab midpoint-profile object.
  • ...: Reserved for future methods.

Returns

A three-dimensional numeric array.

schema_version​

schema_version

Return the cfDNAlab schema version.

schema_version(x, ...)

schema_version.cfdnalab_zarr_store(x, ...)

Arguments

  • x: A cfDNAlab loader object.
  • ...: Reserved for future methods.

Returns

An integer schema version.

End-Motif Counts​

Load dense or sparse end-motif count Zarr stores and extract motif count tables, dense arrays, or sparse matrices.

TopicSummary
read_end_motifsLoads a <prefix>.end_motifs.zarr store created with the cfdna ends CLI tool from the main cfDNAlab rust package.
storage_modeReturn the output storage mode.
row_modeReturn the output row mode.
motifsFor ordinary end-motif stores, the motif column contains motif labels.
motif_idxLook up a motif index.
has_motifTest whether a motif label exists.
window_metadataReturn window metadata.
group_metadataReturn group metadata.
group_idxLook up a group index.
end_motif_data_frameSparse outputs return stored non-zero rows unless the method explicitly receives densify = TRUE.
dense_counts_matrixSparse output stores only non-zero values.
dense_counts_vectorSparse output stores only non-zero values.
dense_corrected_counts_matrixThese methods divide counts by reference-based correction factors.
sparse_counts_matrixSparse output is returned without building a zero-filled dense matrix.
sparse_corrected_counts_matrixThese methods divide counts by reference-based correction factors.
schema_versionReturn the cfDNAlab schema version.

read_end_motifs​

read_end_motifs

Loads a <prefix>.end_motifs.zarr store created with the cfdna ends CLI tool from the main cfDNAlab rust package. It validates the cfDNAlab schema, row metadata, motif metadata, and dense or sparse count layout.

read_end_motifs(path)

Arguments

  • path: Path to a cfDNAlab end-motif .zarr directory.

Returns

One of cfdnalab_global_end_motif_counts, cfdnalab_windowed_end_motif_counts, or cfdnalab_grouped_end_motif_counts, depending on the row mode.

Examples

ends <- read_end_motifs("sample.end_motifs.zarr")
motifs(ends)
sparse_counts_matrix(ends)

storage_mode​

storage_mode

Return the output storage mode.

storage_mode.cfdnalab_end_motif_counts(x, ...)

storage_mode(x, ...)

storage_mode.cfdnalab_ref_kmer_frequencies(x, ...)

Arguments

  • x: A cfDNAlab object with dense or sparse matrix output.
  • ...: Reserved for future methods.

Returns

A scalar character value, currently "dense" or "sparse_coo".

row_mode​

row_mode

Return the output row mode.

row_mode.cfdnalab_end_motif_counts(x, ...)

row_mode(x, ...)

row_mode.cfdnalab_ref_kmer_frequencies(x, ...)

Arguments

  • x: A cfDNAlab object with matrix rows.
  • ...: Reserved for future methods.

Returns

A scalar character value describing the row axis.

motifs​

motifs

For ordinary end-motif stores, the motif column contains motif labels. For grouped motifs-file output, the same column contains user-defined group names from the motif axis. Reference k-mer stores use the same column for k-mer labels or k-mer group names. For observed-only reference k-mer output, this is the combined set of motifs or motifs-file targets observed anywhere in the output.

motifs.cfdnalab_end_motif_counts(x, ...)

motifs(x, ...)

motifs.cfdnalab_ref_kmer_frequencies(x, ...)

Arguments

  • x: A cfDNAlab object with a motif axis.
  • ...: Reserved for future methods.

Returns

A data frame with one row per motif-axis label.

motif_idx​

motif_idx

Look up a motif index.

motif_idx.cfdnalab_end_motif_counts(x, motif, ...)

motif_idx(x, ...)

motif_idx.cfdnalab_ref_kmer_frequencies(x, motif, ...)

Arguments

  • x: A cfDNAlab object with motif labels.
  • motif: Motif label to look up.
  • ...: Method-specific lookup arguments.

Returns

A scalar one-based integer motif index.

has_motif​

has_motif

Test whether a motif label exists.

has_motif.cfdnalab_end_motif_counts(x, motif, ...)

has_motif(x, ...)

has_motif.cfdnalab_ref_kmer_frequencies(x, motif, ...)

Arguments

  • x: A cfDNAlab object with motif labels.
  • motif: Motif label to test.
  • ...: Method-specific lookup arguments.

Returns

A scalar logical.

window_metadata​

window_metadata

Return window metadata.

window_metadata.cfdnalab_windowed_end_motif_counts(x, ...)

window_metadata(x, ...)

window_metadata.cfdnalab_windowed_length_counts(x, ...)

window_metadata.cfdnalab_windowed_ref_kmer_frequencies(x, ...)

Arguments

  • x: A cfDNAlab object with window rows.
  • ...: Reserved for future methods.

Returns

A data frame with one row per window. Public genomic window metadata uses window_idx, chrom, start, and end columns.

group_metadata​

group_metadata

Return group metadata.

group_metadata.cfdnalab_grouped_end_motif_counts(x, ...)

group_metadata(x, ...)

group_metadata.cfdnalab_grouped_length_counts(x, ...)

group_metadata.cfdnalab_midpoint_profiles(x, ...)

group_metadata.cfdnalab_grouped_ref_kmer_frequencies(x, ...)

Arguments

  • x: A cfDNAlab object with a group axis.
  • ...: Reserved for future methods.

Returns

A data frame with one row per group.

group_idx​

group_idx

Look up a group index.

group_idx.cfdnalab_grouped_end_motif_counts(x, group_name, ...)

group_idx(x, ...)

group_idx.cfdnalab_grouped_length_counts(x, group_name, ...)

group_idx.cfdnalab_midpoint_profiles(x, group_name, ...)

group_idx.cfdnalab_grouped_ref_kmer_frequencies(x, group_name, ...)

Arguments

  • x: A cfDNAlab object with group labels.
  • group_name: Group name to look up.
  • ...: Method-specific lookup arguments.

Returns

A scalar one-based integer group index.

end_motif_data_frame​

end_motif_data_frame

Sparse outputs return stored non-zero rows unless the method explicitly receives densify = TRUE. Densifying adds explicit zero-count rows for selected observed motifs. Dense outputs always include zero counts.

end_motif_data_frame.cfdnalab_global_end_motif_counts(
  x,
  ref_kmers = NULL,
  densify = FALSE,
  motifs = NULL,
  motif_idxs = NULL,
  use_global_bias = FALSE,
  unsupported_motifs = "error",
  two_sided_correction = NULL,
  ...
)

end_motif_data_frame.cfdnalab_windowed_end_motif_counts(
  x,
  ref_kmers = NULL,
  window_idxs = NULL,
  densify = FALSE,
  motifs = NULL,
  motif_idxs = NULL,
  max_blacklisted_fraction = 1,
  use_global_bias = FALSE,
  unsupported_motifs = "error",
  two_sided_correction = NULL,
  ...
)

end_motif_data_frame.cfdnalab_grouped_end_motif_counts(
  x,
  ref_kmers = NULL,
  groups = NULL,
  group_idxs = NULL,
  densify = FALSE,
  motifs = NULL,
  motif_idxs = NULL,
  max_blacklisted_fraction = 1,
  use_global_bias = FALSE,
  unsupported_motifs = "error",
  two_sided_correction = NULL,
  ...
)

end_motif_data_frame(x, ...)

Arguments

  • x: A cfDNAlab end-motif object.
  • ref_kmers: Optional reference k-mer object used to add corrected counts.
  • densify: If TRUE, sparse outputs add explicit zero-count rows for selected observed motifs. Dense outputs ignore this option.
  • motifs: Optional motif label vector. Use either motifs or motif_idxs, not both.
  • motif_idxs: Optional one-based motif index vector.
  • use_global_bias: Whether a global reference k-mer output may be applied to every end-motif row.
  • unsupported_motifs: What to do when an observed sample motif has no positive correction factor under the selected mode. Use "error", "drop", or "keep_na".
  • two_sided_correction: Required when motif labels contain both outside and inside bases, such as "AC_GT", and ref_kmers is supplied. Use "joint", "split", "outside", or "inside". Leave as NULL for one-sided motifs or motif groups.
  • ...: Method-specific selection arguments.
  • window_idxs: Optional one-based window index vector for windowed output.
  • max_blacklisted_fraction: Maximum row blacklisted_fraction in 0..1 to retain before returning counts. The default 1.0 keeps all selected rows.
  • groups: Optional group name vector for grouped output. Use either groups or group_idxs, not both.
  • group_idxs: Optional one-based group index vector for grouped output.

Returns

A data frame containing row metadata, motif metadata, and counts.

Details

End-motif methods can receive ref_kmers to add reference-corrected counts without manually joining the sample and reference data frames. Corrected data frames add corrected_count and corrected_frequency.

Reference correction divides each observed end-motif count by a reference-based correction factor for the matched row. This factor is computed from the motif frequencies in the reference k-mer output and normalized so a uniform reference composition leaves counts unchanged. Motifs that are common in the reference row are scaled down. Motifs that are rare in the reference row are scaled up. Only motifs with a positive reference frequency contribute to the row's correction support.

Two-sided correction modes:

When motif labels contain both outside and inside bases, such as "AC_GT", two_sided_correction chooses both the motif labels in the result and the correction factor used for each returned count.

  • "joint" keeps full labels such as "AC_GT" and corrects each count using the exact reference k-mer "ACGT".
  • "split" keeps full labels such as "AC_GT", but calculates the correction factor from the two sides separately. For "AC_GT", separate correction factors are calculated for outside label "AC" and inside label "GT". Those two correction factors are multiplied and applied to the observed "AC_GT" count. Use this when you want full two-sided motif labels in the result, but the exact full reference k-mers are too sparse or you want the reference correction to treat outside and inside sequence composition separately.
  • "outside" returns outside labels such as "AC_". For each outside label, all full motif counts with that outside label are summed first. For example, "AC_AA" and "AC_GT" both contribute to the "AC_" count. That summed count is corrected using the outside label "AC".
  • "inside" returns inside labels such as "_GT". For each inside label, all full motif counts with that inside label are summed first. For example, "AA_GT" and "AC_GT" both contribute to the "_GT" count. That summed count is corrected using the inside label "GT".

For "split", "outside", and "inside", side-specific reference frequencies are calculated from the loaded full-length reference k-mers. For example, the outside frequency for "AC" is the sum of frequencies for loaded k-mers with prefix "AC", such as "ACTG" and "ACAA". The inside frequency for "TG" is the corresponding sum over loaded k-mers with suffix "TG". Separate shorter reference k-mer runs are not required.

A motifs file used for the reference output restricts these sums to the k-mers in that file. Without a motifs file, all k-mers in the reference output can contribute, including k-mers absent from the sample end-motif output.

corrected_frequency is corrected_count divided by the sum of corrected counts over the full correction-mode motif axis for the same output row. Motif selection filters these frequencies afterward and does not renormalize them, so a selected subset can sum to less than 1. If the corrected total is zero, finite frequencies are zero. With unsupported_motifs = "keep_na", one undefined positive corrected count makes all frequencies in that output row NA. Reference correction fails if division by a positive reference factor would produce a non-finite corrected count.

dense_counts_matrix​

dense_counts_matrix

Sparse output stores only non-zero values. These methods do not create a zero-filled dense matrix from sparse output unless they explicitly receive allow_densify = TRUE. For objects with a motif axis, densifying fills zeroes only across the labels returned by motifs(x).

dense_counts_matrix.cfdnalab_global_end_motif_counts(
  x,
  allow_densify = FALSE,
  motifs = NULL,
  motif_idxs = NULL,
  ...
)

dense_counts_matrix.cfdnalab_windowed_end_motif_counts(
  x,
  allow_densify = FALSE,
  window_idxs = NULL,
  motifs = NULL,
  motif_idxs = NULL,
  ...
)

dense_counts_matrix.cfdnalab_grouped_end_motif_counts(
  x,
  allow_densify = FALSE,
  groups = NULL,
  group_idxs = NULL,
  motifs = NULL,
  motif_idxs = NULL,
  ...
)

dense_counts_matrix(x, ...)

dense_counts_matrix.cfdnalab_global_ref_kmer_frequencies(
  x,
  allow_densify = FALSE,
  motifs = NULL,
  motif_idxs = NULL,
  ...
)

dense_counts_matrix.cfdnalab_windowed_ref_kmer_frequencies(
  x,
  allow_densify = FALSE,
  window_idxs = NULL,
  motifs = NULL,
  motif_idxs = NULL,
  ...
)

dense_counts_matrix.cfdnalab_grouped_ref_kmer_frequencies(
  x,
  allow_densify = FALSE,
  groups = NULL,
  group_idxs = NULL,
  motifs = NULL,
  motif_idxs = NULL,
  ...
)

Arguments

  • x: A cfDNAlab object with count values or reconstructable counts.
  • allow_densify: If TRUE, allow sparse stores to be converted to a dense in-memory matrix. Sparse stores error by default.
  • motifs: Optional motif label vector. Use either motifs or motif_idxs, not both.
  • motif_idxs: Optional one-based motif index vector.
  • ...: Method-specific arguments.
  • window_idxs: Optional one-based window index vector for windowed output.
  • groups: Optional group name vector for grouped output. Use either groups or group_idxs, not both.
  • group_idxs: Optional one-based group index vector for grouped output.

Returns

A dense numeric matrix.

dense_counts_vector​

dense_counts_vector

Sparse output stores only non-zero values. These methods do not create a zero-filled dense vector from sparse output unless they explicitly receive allow_densify = TRUE. For objects with a motif axis, densifying fills zeroes only across the labels returned by motifs(x).

dense_counts_vector.cfdnalab_global_end_motif_counts(x, allow_densify = FALSE, ...)

dense_counts_vector(x, ...)

dense_counts_vector.cfdnalab_global_ref_kmer_frequencies(x, allow_densify = FALSE, ...)

Arguments

  • x: A cfDNAlab global object with count values or reconstructable counts.
  • allow_densify: If TRUE, allow sparse stores to be converted to dense in memory before returning the vector.
  • ...: Method-specific arguments.

Returns

A named numeric vector with one value per motif.

dense_corrected_counts_matrix​

dense_corrected_counts_matrix

These methods divide counts by reference-based correction factors. For a one-sided motif, and for "joint" two-sided correction, the factor comes from the matching full reference motif. "split" keeps each full two-sided label but calculates outside and inside factors independently and multiplies them. "outside" first sums counts over inside bases, divides each sum by its outside factor, and returns labels such as "AC_". "inside" first sums over outside bases, divides by the inside factor, and returns labels such as "_GT".

dense_corrected_counts_matrix.cfdnalab_global_end_motif_counts(
  x,
  ref_kmers,
  allow_densify = FALSE,
  motifs = NULL,
  motif_idxs = NULL,
  use_global_bias = FALSE,
  unsupported_motifs = "error",
  two_sided_correction = NULL,
  ...
)

dense_corrected_counts_matrix.cfdnalab_windowed_end_motif_counts(
  x,
  ref_kmers,
  allow_densify = FALSE,
  window_idxs = NULL,
  motifs = NULL,
  motif_idxs = NULL,
  max_blacklisted_fraction = 1,
  use_global_bias = FALSE,
  unsupported_motifs = "error",
  two_sided_correction = NULL,
  ...
)

dense_corrected_counts_matrix.cfdnalab_grouped_end_motif_counts(
  x,
  ref_kmers,
  allow_densify = FALSE,
  groups = NULL,
  group_idxs = NULL,
  motifs = NULL,
  motif_idxs = NULL,
  max_blacklisted_fraction = 1,
  use_global_bias = FALSE,
  unsupported_motifs = "error",
  two_sided_correction = NULL,
  ...
)

dense_corrected_counts_matrix(x, ...)

Arguments

  • x: A cfDNAlab end-motif object.
  • ref_kmers: Reference k-mer object used for correction.
  • allow_densify: If TRUE, allow sparse stores to be converted to a dense in-memory matrix. Sparse stores error by default.
  • motifs: Optional motif label vector. Use either motifs or motif_idxs, not both.
  • motif_idxs: Optional one-based motif index vector.
  • use_global_bias: Whether a global reference k-mer output may be applied to every end-motif row.
  • unsupported_motifs: What to do when an observed sample motif has no positive correction factor under the selected mode. Use "error", "drop", or "keep_na".
  • two_sided_correction: Required when motif labels contain both outside and inside bases, such as "AC_GT". Use "joint", "split", "outside", or "inside". Leave as NULL for one-sided motifs or motif groups.
  • ...: Method-specific arguments.
  • window_idxs: Optional one-based window index vector for windowed output.
  • max_blacklisted_fraction: Maximum row blacklisted_fraction in 0..1 to retain before returning counts.
  • groups: Optional group name vector for grouped output. Use either groups or group_idxs, not both.
  • group_idxs: Optional one-based group index vector for grouped output.

Returns

A dense numeric matrix.

Details

Reference correction divides each observed end-motif count by a reference-based correction factor for the matched row. This factor is computed from the motif frequencies in the reference k-mer output and normalized so a uniform reference composition leaves counts unchanged. Motifs that are common in the reference row are scaled down. Motifs that are rare in the reference row are scaled up. Only motifs with a positive reference frequency contribute to the row's correction support.

Two-sided correction modes:

When motif labels contain both outside and inside bases, such as "AC_GT", two_sided_correction chooses both the motif labels in the result and the correction factor used for each returned count.

  • "joint" keeps full labels such as "AC_GT" and corrects each count using the exact reference k-mer "ACGT".
  • "split" keeps full labels such as "AC_GT", but calculates the correction factor from the two sides separately. For "AC_GT", separate correction factors are calculated for outside label "AC" and inside label "GT". Those two correction factors are multiplied and applied to the observed "AC_GT" count. Use this when you want full two-sided motif labels in the result, but the exact full reference k-mers are too sparse or you want the reference correction to treat outside and inside sequence composition separately.
  • "outside" returns outside labels such as "AC_". For each outside label, all full motif counts with that outside label are summed first. For example, "AC_AA" and "AC_GT" both contribute to the "AC_" count. That summed count is corrected using the outside label "AC".
  • "inside" returns inside labels such as "_GT". For each inside label, all full motif counts with that inside label are summed first. For example, "AA_GT" and "AC_GT" both contribute to the "_GT" count. That summed count is corrected using the inside label "GT".

For "split", "outside", and "inside", side-specific reference frequencies are calculated from the loaded full-length reference k-mers. For example, the outside frequency for "AC" is the sum of frequencies for loaded k-mers with prefix "AC", such as "ACTG" and "ACAA". The inside frequency for "TG" is the corresponding sum over loaded k-mers with suffix "TG". Separate shorter reference k-mer runs are not required.

A motifs file used for the reference output restricts these sums to the k-mers in that file. Without a motifs file, all k-mers in the reference output can contribute, including k-mers absent from the sample end-motif output.

The returned matrix has one column per motif on the selected correction-mode axis. "outside" and "inside" can therefore have fewer columns than the raw count matrix. For these side modes, column names contain the corrected motif labels in matrix order.

Sparse end-motif output is not densified unless the method explicitly receives allow_densify = TRUE. Dense matrices have a fixed row and motif shape, so unsupported_motifs = "drop" is not supported here. Use end_motif_data_frame(..., ref_kmers = ref_kmers, unsupported_motifs = "drop") when unsupported motifs should be omitted.

When motif labels contain both outside and inside bases, such as "AC_GT", two_sided_correction is required to choose among these four interpretations.

sparse_counts_matrix​

sparse_counts_matrix

Sparse output is returned without building a zero-filled dense matrix. Dense output is read into memory before conversion to a sparse matrix.

sparse_counts_matrix.cfdnalab_global_end_motif_counts(x, motifs = NULL, motif_idxs = NULL, ...)

sparse_counts_matrix.cfdnalab_windowed_end_motif_counts(
  x,
  window_idxs = NULL,
  motifs = NULL,
  motif_idxs = NULL,
  ...
)

sparse_counts_matrix.cfdnalab_grouped_end_motif_counts(
  x,
  groups = NULL,
  group_idxs = NULL,
  motifs = NULL,
  motif_idxs = NULL,
  ...
)

sparse_counts_matrix(x, ...)

sparse_counts_matrix.cfdnalab_global_ref_kmer_frequencies(x, motifs = NULL, motif_idxs = NULL, ...)

sparse_counts_matrix.cfdnalab_windowed_ref_kmer_frequencies(
  x,
  window_idxs = NULL,
  motifs = NULL,
  motif_idxs = NULL,
  ...
)

sparse_counts_matrix.cfdnalab_grouped_ref_kmer_frequencies(
  x,
  groups = NULL,
  group_idxs = NULL,
  motifs = NULL,
  motif_idxs = NULL,
  ...
)

Arguments

  • x: A cfDNAlab object with count values or reconstructable counts.
  • motifs: Optional motif label vector. Use either motifs or motif_idxs, not both.
  • motif_idxs: Optional one-based motif index vector.
  • ...: Reserved for future methods.
  • window_idxs: Optional one-based window index vector for windowed output.
  • groups: Optional group name vector for grouped output. Use either groups or group_idxs, not both.
  • group_idxs: Optional one-based group index vector for grouped output.

Returns

A Matrix sparse matrix.

sparse_corrected_counts_matrix​

sparse_corrected_counts_matrix

These methods divide counts by reference-based correction factors. For a one-sided motif, and for "joint" two-sided correction, the factor comes from the matching full reference motif. "split" keeps each full two-sided label but calculates outside and inside factors independently and multiplies them. "outside" first sums counts over inside bases, divides each sum by its outside factor, and returns labels such as "AC_". "inside" first sums over outside bases, divides by the inside factor, and returns labels such as "_GT".

sparse_corrected_counts_matrix.cfdnalab_global_end_motif_counts(
  x,
  ref_kmers,
  motifs = NULL,
  motif_idxs = NULL,
  use_global_bias = FALSE,
  unsupported_motifs = "error",
  two_sided_correction = NULL,
  ...
)

sparse_corrected_counts_matrix.cfdnalab_windowed_end_motif_counts(
  x,
  ref_kmers,
  window_idxs = NULL,
  motifs = NULL,
  motif_idxs = NULL,
  max_blacklisted_fraction = 1,
  use_global_bias = FALSE,
  unsupported_motifs = "error",
  two_sided_correction = NULL,
  ...
)

sparse_corrected_counts_matrix.cfdnalab_grouped_end_motif_counts(
  x,
  ref_kmers,
  groups = NULL,
  group_idxs = NULL,
  motifs = NULL,
  motif_idxs = NULL,
  max_blacklisted_fraction = 1,
  use_global_bias = FALSE,
  unsupported_motifs = "error",
  two_sided_correction = NULL,
  ...
)

sparse_corrected_counts_matrix(x, ...)

Arguments

  • x: A cfDNAlab end-motif object.
  • ref_kmers: Reference k-mer object used for correction.
  • motifs: Optional motif label vector. Use either motifs or motif_idxs, not both.
  • motif_idxs: Optional one-based motif index vector.
  • use_global_bias: Whether a global reference k-mer output may be applied to every end-motif row.
  • unsupported_motifs: What to do when an observed sample motif has no positive correction factor under the selected mode. Use "error", "drop", or "keep_na".
  • two_sided_correction: Required when motif labels contain both outside and inside bases, such as "AC_GT". Use "joint", "split", "outside", or "inside". Leave as NULL for one-sided motifs or motif groups.
  • ...: Method-specific arguments.
  • window_idxs: Optional one-based window index vector for windowed output.
  • max_blacklisted_fraction: Maximum row blacklisted_fraction in 0..1 to retain before returning counts.
  • groups: Optional group name vector for grouped output. Use either groups or group_idxs, not both.
  • group_idxs: Optional one-based group index vector for grouped output.

Returns

A Matrix sparse matrix.

Details

Reference correction divides each observed end-motif count by a reference-based correction factor for the matched row. This factor is computed from the motif frequencies in the reference k-mer output and normalized so a uniform reference composition leaves counts unchanged. Motifs that are common in the reference row are scaled down. Motifs that are rare in the reference row are scaled up. Only motifs with a positive reference frequency contribute to the row's correction support.

Two-sided correction modes:

When motif labels contain both outside and inside bases, such as "AC_GT", two_sided_correction chooses both the motif labels in the result and the correction factor used for each returned count.

  • "joint" keeps full labels such as "AC_GT" and corrects each count using the exact reference k-mer "ACGT".
  • "split" keeps full labels such as "AC_GT", but calculates the correction factor from the two sides separately. For "AC_GT", separate correction factors are calculated for outside label "AC" and inside label "GT". Those two correction factors are multiplied and applied to the observed "AC_GT" count. Use this when you want full two-sided motif labels in the result, but the exact full reference k-mers are too sparse or you want the reference correction to treat outside and inside sequence composition separately.
  • "outside" returns outside labels such as "AC_". For each outside label, all full motif counts with that outside label are summed first. For example, "AC_AA" and "AC_GT" both contribute to the "AC_" count. That summed count is corrected using the outside label "AC".
  • "inside" returns inside labels such as "_GT". For each inside label, all full motif counts with that inside label are summed first. For example, "AA_GT" and "AC_GT" both contribute to the "_GT" count. That summed count is corrected using the inside label "GT".

For "split", "outside", and "inside", side-specific reference frequencies are calculated from the loaded full-length reference k-mers. For example, the outside frequency for "AC" is the sum of frequencies for loaded k-mers with prefix "AC", such as "ACTG" and "ACAA". The inside frequency for "TG" is the corresponding sum over loaded k-mers with suffix "TG". Separate shorter reference k-mer runs are not required.

A motifs file used for the reference output restricts these sums to the k-mers in that file. Without a motifs file, all k-mers in the reference output can contribute, including k-mers absent from the sample end-motif output.

The returned matrix has one column per motif on the selected correction-mode axis. "outside" and "inside" can therefore have fewer columns than the raw count matrix. For these side modes, column names contain the corrected motif labels in matrix order.

Sparse output is returned without building a zero-filled dense matrix. Dense output is read into memory before conversion to a sparse matrix. Sparse matrices have a fixed row and motif shape, so unsupported_motifs = "drop" is not supported here. Use end_motif_data_frame(..., ref_kmers = ref_kmers, unsupported_motifs = "drop") when unsupported motifs should be omitted.

When motif labels contain both outside and inside bases, such as "AC_GT", two_sided_correction is required to choose among these four interpretations.

schema_version​

schema_version

Return the cfDNAlab schema version.

schema_version(x, ...)

schema_version.cfdnalab_zarr_store(x, ...)

Arguments

  • x: A cfDNAlab loader object.
  • ...: Reserved for future methods.

Returns

An integer schema version.

Reference K-mer Frequencies​

Load reference k-mer frequency Zarr stores and extract frequency tables, dense arrays, sparse matrices, and reconstructed counts.

TopicSummary
read_ref_kmersLoads a <prefix>.ref_kmers.zarr output directory created with the cfdna ref-kmers CLI tool from the main cfDNAlab rust package.
storage_modeReturn the output storage mode.
row_modeReturn the output row mode.
motif_axis_kindReturn the reference k-mer motif-axis kind.
kmer_sizeReturn the reference k-mer size.
canonicalReturn whether reference k-mers were canonicalized.
orientation"both" averages the reference-forward sequence and its reverse complement.
all_motifsFor full k-mer output, this means every A/C/G/T k-mer for the requested k.
assign_byReturn the reference k-mer window assignment rule.
motifsFor ordinary end-motif stores, the motif column contains motif labels.
motif_idxLook up a motif index.
window_metadataReturn window metadata.
group_metadataReturn group metadata.
group_idxLook up a group index.
reference_contig_footprintReturn the reference contig footprint.
row_scaling_factorsReference k-mer outputs store frequencies.
ref_kmer_data_frameSparse output stores only non-zero frequencies.
dense_frequencies_matrixSparse output stores only non-zero frequencies.
dense_frequencies_vectorSparse output stores only non-zero frequencies.
sparse_frequencies_matrixSparse output is returned without building a zero-filled dense matrix.
schema_versionReturn the cfDNAlab schema version.

read_ref_kmers​

read_ref_kmers

Loads a <prefix>.ref_kmers.zarr output directory created with the cfdna ref-kmers CLI tool from the main cfDNAlab rust package. The directory is a Zarr store on disk, but ordinary workflows can use the data frame and matrix helpers without working with Zarr directly.

read_ref_kmers(path)

Arguments

  • path: Path to a cfDNAlab reference k-mer .zarr directory.

Returns

One of cfdnalab_global_ref_kmer_frequencies, cfdnalab_windowed_ref_kmer_frequencies, or cfdnalab_grouped_ref_kmer_frequencies, depending on the row mode.

Details

Reference k-mer outputs store frequencies. Count helpers reconstruct counts by multiplying each frequency row by its row_scaling_factor. A row can describe the whole reference, a genomic window, a BED interval, or a grouped BED entry depending on how the command was run.

The loader validates the cfDNAlab schema, row metadata, motif metadata, frequency layout, and the metadata needed to reconstruct counts.

Examples

ref_kmers <- read_ref_kmers("sample.ref_kmers.zarr")
motifs(ref_kmers)
sparse_frequencies_matrix(ref_kmers)

storage_mode​

storage_mode

Return the output storage mode.

storage_mode.cfdnalab_end_motif_counts(x, ...)

storage_mode(x, ...)

storage_mode.cfdnalab_ref_kmer_frequencies(x, ...)

Arguments

  • x: A cfDNAlab object with dense or sparse matrix output.
  • ...: Reserved for future methods.

Returns

A scalar character value, currently "dense" or "sparse_coo".

row_mode​

row_mode

Return the output row mode.

row_mode.cfdnalab_end_motif_counts(x, ...)

row_mode(x, ...)

row_mode.cfdnalab_ref_kmer_frequencies(x, ...)

Arguments

  • x: A cfDNAlab object with matrix rows.
  • ...: Reserved for future methods.

Returns

A scalar character value describing the row axis.

motif_axis_kind​

motif_axis_kind

Return the reference k-mer motif-axis kind.

motif_axis_kind(x, ...)

motif_axis_kind.cfdnalab_ref_kmer_frequencies(x, ...)

Arguments

  • x: A cfDNAlab reference k-mer object.
  • ...: Reserved for future methods.

Returns

A scalar character value, either "motif" or "motif_group".

kmer_size​

kmer_size

Return the reference k-mer size.

kmer_size(x, ...)

kmer_size.cfdnalab_ref_kmer_frequencies(x, ...)

Arguments

  • x: A cfDNAlab reference k-mer object.
  • ...: Reserved for future methods.

Returns

A scalar integer k-mer size.

canonical​

canonical

Return whether reference k-mers were canonicalized.

canonical(x, ...)

canonical.cfdnalab_ref_kmer_frequencies(x, ...)

Arguments

  • x: A cfDNAlab reference k-mer object.
  • ...: Reserved for future methods.

Returns

A scalar logical.

orientation​

orientation

"both" averages the reference-forward sequence and its reverse complement. "reference_forward" uses only the sequence read left-to-right from the stored reference.

orientation(x, ...)

orientation.cfdnalab_ref_kmer_frequencies(x, ...)

Arguments

  • x: A cfDNAlab reference k-mer object.
  • ...: Reserved for future methods.

Returns

A scalar character value.

all_motifs​

all_motifs

For full k-mer output, this means every A/C/G/T k-mer for the requested k. For motifs-file output, this means every target from the motifs file.

all_motifs(x, ...)

all_motifs.cfdnalab_ref_kmer_frequencies(x, ...)

Arguments

  • x: A cfDNAlab reference k-mer object.
  • ...: Reserved for future methods.

Returns

A scalar logical.

assign_by​

assign_by

Return the reference k-mer window assignment rule.

assign_by(x, ...)

assign_by.cfdnalab_ref_kmer_frequencies(x, ...)

Arguments

  • x: A cfDNAlab reference k-mer object.
  • ...: Reserved for future methods.

Returns

A scalar character value.

motifs​

motifs

For ordinary end-motif stores, the motif column contains motif labels. For grouped motifs-file output, the same column contains user-defined group names from the motif axis. Reference k-mer stores use the same column for k-mer labels or k-mer group names. For observed-only reference k-mer output, this is the combined set of motifs or motifs-file targets observed anywhere in the output.

motifs.cfdnalab_end_motif_counts(x, ...)

motifs(x, ...)

motifs.cfdnalab_ref_kmer_frequencies(x, ...)

Arguments

  • x: A cfDNAlab object with a motif axis.
  • ...: Reserved for future methods.

Returns

A data frame with one row per motif-axis label.

motif_idx​

motif_idx

Look up a motif index.

motif_idx.cfdnalab_end_motif_counts(x, motif, ...)

motif_idx(x, ...)

motif_idx.cfdnalab_ref_kmer_frequencies(x, motif, ...)

Arguments

  • x: A cfDNAlab object with motif labels.
  • motif: Motif label to look up.
  • ...: Method-specific lookup arguments.

Returns

A scalar one-based integer motif index.

window_metadata​

window_metadata

Return window metadata.

window_metadata.cfdnalab_windowed_end_motif_counts(x, ...)

window_metadata(x, ...)

window_metadata.cfdnalab_windowed_length_counts(x, ...)

window_metadata.cfdnalab_windowed_ref_kmer_frequencies(x, ...)

Arguments

  • x: A cfDNAlab object with window rows.
  • ...: Reserved for future methods.

Returns

A data frame with one row per window. Public genomic window metadata uses window_idx, chrom, start, and end columns.

group_metadata​

group_metadata

Return group metadata.

group_metadata.cfdnalab_grouped_end_motif_counts(x, ...)

group_metadata(x, ...)

group_metadata.cfdnalab_grouped_length_counts(x, ...)

group_metadata.cfdnalab_midpoint_profiles(x, ...)

group_metadata.cfdnalab_grouped_ref_kmer_frequencies(x, ...)

Arguments

  • x: A cfDNAlab object with a group axis.
  • ...: Reserved for future methods.

Returns

A data frame with one row per group.

group_idx​

group_idx

Look up a group index.

group_idx.cfdnalab_grouped_end_motif_counts(x, group_name, ...)

group_idx(x, ...)

group_idx.cfdnalab_grouped_length_counts(x, group_name, ...)

group_idx.cfdnalab_midpoint_profiles(x, group_name, ...)

group_idx.cfdnalab_grouped_ref_kmer_frequencies(x, group_name, ...)

Arguments

  • x: A cfDNAlab object with group labels.
  • group_name: Group name to look up.
  • ...: Method-specific lookup arguments.

Returns

A scalar one-based integer group index.

reference_contig_footprint​

reference_contig_footprint

Return the reference contig footprint.

reference_contig_footprint(x, ...)

reference_contig_footprint.cfdnalab_ref_kmer_frequencies(x, ...)

Arguments

  • x: A cfDNAlab reference k-mer object.
  • ...: Reserved for future methods.

Returns

JSON-decoded reference contig footprint metadata.

row_scaling_factors​

row_scaling_factors

Reference k-mer outputs store frequencies. Multiplying a row's frequency by its row_scaling_factor gives the reconstructed count for that row.

row_scaling_factors(x, ...)

row_scaling_factors.cfdnalab_ref_kmer_frequencies(x, ...)

Arguments

  • x: A cfDNAlab reference k-mer object.
  • ...: Reserved for future methods.

Returns

A data frame with row metadata and row_scaling_factor.

ref_kmer_data_frame​

ref_kmer_data_frame

Sparse output stores only non-zero frequencies. By default, sparse output returns those stored rows only. With densify = TRUE, the data frame also includes zero-frequency rows for the selected rows and the selected motifs returned by motifs(x). For observed-only output, those selected labels are the combined set observed anywhere in the output. Densifying does not add every possible k-mer unless all_motifs(x) is TRUE. Dense output always includes zeroes.

ref_kmer_data_frame(x, ...)

ref_kmer_data_frame.cfdnalab_global_ref_kmer_frequencies(x, densify = FALSE, motifs = NULL, motif_idxs = NULL, ...)

ref_kmer_data_frame.cfdnalab_windowed_ref_kmer_frequencies(
  x,
  window_idxs = NULL,
  densify = FALSE,
  motifs = NULL,
  motif_idxs = NULL,
  max_blacklisted_fraction = 1,
  ...
)

ref_kmer_data_frame.cfdnalab_grouped_ref_kmer_frequencies(
  x,
  groups = NULL,
  group_idxs = NULL,
  densify = FALSE,
  motifs = NULL,
  motif_idxs = NULL,
  max_blacklisted_fraction = 1,
  ...
)

Arguments

  • x: A cfDNAlab reference k-mer object.
  • ...: Method-specific selection arguments.
  • densify: If TRUE, sparse output adds explicit zero-frequency rows for selected motifs in motifs(x). For observed-only output, this is the combined set observed anywhere in the output. Densifying does not add every possible k-mer unless all_motifs(x) is TRUE. Dense outputs ignore this option.
  • motifs: Optional motif label vector. Use either motifs or motif_idxs, not both.
  • motif_idxs: Optional one-based motif index vector.
  • window_idxs: Optional one-based window index vector for windowed output.
  • max_blacklisted_fraction: Maximum row blacklisted_fraction in 0..1 to retain before returning values. The default 1.0 keeps all selected rows.
  • groups: Optional group name vector for grouped output. Use either groups or group_idxs, not both.
  • group_idxs: Optional one-based group index vector for grouped output.

Returns

A data frame containing row metadata, motif metadata, frequency, and reconstructed count.

dense_frequencies_matrix​

dense_frequencies_matrix

Sparse output stores only non-zero frequencies. This method does not create a zero-filled dense matrix from sparse output unless it explicitly receives allow_densify = TRUE. Densifying fills zeroes only across the motif axis returned by motifs(x).

dense_frequencies_matrix(x, ...)

dense_frequencies_matrix.cfdnalab_global_ref_kmer_frequencies(
  x,
  allow_densify = FALSE,
  motifs = NULL,
  motif_idxs = NULL,
  ...
)

dense_frequencies_matrix.cfdnalab_windowed_ref_kmer_frequencies(
  x,
  allow_densify = FALSE,
  window_idxs = NULL,
  motifs = NULL,
  motif_idxs = NULL,
  ...
)

dense_frequencies_matrix.cfdnalab_grouped_ref_kmer_frequencies(
  x,
  allow_densify = FALSE,
  groups = NULL,
  group_idxs = NULL,
  motifs = NULL,
  motif_idxs = NULL,
  ...
)

Arguments

  • x: A cfDNAlab reference k-mer object.
  • ...: Method-specific arguments.
  • allow_densify: If TRUE, allow sparse output to be converted to a zero-filled dense matrix in memory. Zero filling uses the selected motifs from motifs(x), not every possible k-mer unless all_motifs(x) is TRUE. Sparse output errors by default.
  • motifs: Optional motif label vector. Use either motifs or motif_idxs, not both.
  • motif_idxs: Optional one-based motif index vector.
  • window_idxs: Optional one-based window index vector for windowed output.
  • groups: Optional group name vector for grouped output. Use either groups or group_idxs, not both.
  • group_idxs: Optional one-based group index vector for grouped output.

Returns

A dense numeric matrix.

dense_frequencies_vector​

dense_frequencies_vector

Sparse output stores only non-zero frequencies. This method does not create a zero-filled dense vector from sparse output unless it explicitly receives allow_densify = TRUE. Densifying fills zeroes only across the motif axis returned by motifs(x).

dense_frequencies_vector(x, ...)

dense_frequencies_vector.cfdnalab_global_ref_kmer_frequencies(x, allow_densify = FALSE, ...)

Arguments

  • x: A cfDNAlab global reference k-mer object.
  • ...: Method-specific arguments.
  • allow_densify: If TRUE, allow sparse output to be converted to a zero-filled dense vector in memory. Zero filling uses the motif axis from motifs(x), not every possible k-mer unless all_motifs(x) is TRUE.

Returns

A named numeric vector with one value per motif.

sparse_frequencies_matrix​

sparse_frequencies_matrix

Sparse output is returned without building a zero-filled dense matrix. Dense output is read into memory before conversion to a sparse matrix.

sparse_frequencies_matrix(x, ...)

sparse_frequencies_matrix.cfdnalab_global_ref_kmer_frequencies(x, motifs = NULL, motif_idxs = NULL, ...)

sparse_frequencies_matrix.cfdnalab_windowed_ref_kmer_frequencies(
  x,
  window_idxs = NULL,
  motifs = NULL,
  motif_idxs = NULL,
  ...
)

sparse_frequencies_matrix.cfdnalab_grouped_ref_kmer_frequencies(
  x,
  groups = NULL,
  group_idxs = NULL,
  motifs = NULL,
  motif_idxs = NULL,
  ...
)

Arguments

  • x: A cfDNAlab reference k-mer object.
  • ...: Method-specific arguments.
  • motifs: Optional motif label vector. Use either motifs or motif_idxs, not both.
  • motif_idxs: Optional one-based motif index vector.
  • window_idxs: Optional one-based window index vector for windowed output.
  • groups: Optional group name vector for grouped output. Use either groups or group_idxs, not both.
  • group_idxs: Optional one-based group index vector for grouped output.

Returns

A Matrix sparse matrix.

schema_version​

schema_version

Return the cfDNAlab schema version.

schema_version(x, ...)

schema_version.cfdnalab_zarr_store(x, ...)

Arguments

  • x: A cfDNAlab loader object.
  • ...: Reserved for future methods.

Returns

An integer schema version.

Length Counts​

Load fragment length-count TSV outputs and return counts, fractions, or densities as arrays, matrices, vectors, or data frames.

TopicSummary
read_lengthsLoads a <prefix>.length_counts.tsv.zst file created with the cfdna lengths CLI command.
length_binsReturn length-bin metadata.
length_bin_idxLook up the length-bin index containing a fragment length.
length_counts_matrixReturn length-count values as a matrix.
length_counts_vectorReturn global length-count values as a vector.
length_data_frameReturn length-count values as a data frame.
window_metadataReturn window metadata.
group_metadataReturn group metadata.
group_idxLook up a group index.

read_lengths​

read_lengths

Loads a <prefix>.length_counts.tsv.zst file created with the cfdna lengths CLI command.

read_lengths(path)

Arguments

  • path: Path to a cfDNAlab length-count TSV file, typically .tsv.zst.

Returns

A mode-specific cfdnalab_length_counts object: cfdnalab_global_length_counts, cfdnalab_windowed_length_counts, or cfdnalab_grouped_length_counts.

Examples

lengths <- read_lengths("sample.length_counts.tsv.zst")
length_bins(lengths)
length_data_frame(lengths, value = "fraction")

length_bins​

length_bins

Return length-bin metadata.

length_bins(x, ...)

length_bins.cfdnalab_length_counts(x, ...)

length_bins.cfdnalab_midpoint_profiles(x, ...)

Arguments

  • x: A cfDNAlab object with length bins.
  • ...: Reserved for future methods.

Returns

A data frame with one row per length bin.

length_bin_idx​

length_bin_idx

Look up the length-bin index containing a fragment length.

length_bin_idx(x, ...)

length_bin_idx.cfdnalab_length_counts(x, length, ...)

length_bin_idx.cfdnalab_midpoint_profiles(x, length, ...)

Arguments

  • x: A cfDNAlab object with length bins.
  • ...: Method-specific lookup arguments.
  • length: Fragment length in base pairs.

Returns

A scalar one-based integer length-bin index.

Details

Errors if no length bin contains the requested fragment length.

length_counts_matrix​

length_counts_matrix

Return length-count values as a matrix.

length_counts_matrix(x, ...)

length_counts_matrix.cfdnalab_global_length_counts(
  x,
  with_lengths = NULL,
  with_length_range = NULL,
  length_bin_idxs = NULL,
  ...
)

length_counts_matrix.cfdnalab_windowed_length_counts(
  x,
  window_idxs = NULL,
  with_lengths = NULL,
  with_length_range = NULL,
  length_bin_idxs = NULL,
  ...
)

length_counts_matrix.cfdnalab_grouped_length_counts(
  x,
  groups = NULL,
  group_idxs = NULL,
  with_lengths = NULL,
  with_length_range = NULL,
  length_bin_idxs = NULL,
  ...
)

Arguments

  • x: A cfDNAlab length-count object.
  • ...: Reserved for future methods.
  • with_lengths: Optional fragment length vector in base pairs. Returned columns use the length bins containing these lengths. Multiple lengths must select distinct length bins.
  • with_length_range: Optional two-value fragment length range in base pairs. Returned columns use whole length bins that overlap the half-open range [start, end).
  • length_bin_idxs: Optional one-based length-bin index vector. Use only one of with_lengths, with_length_range, or length_bin_idxs.
  • window_idxs: Optional one-based window index vector.
  • groups: Optional group name vector. Use either groups or group_idxs, not both.
  • group_idxs: Optional one-based group index vector.

Returns

A numeric matrix with one row per output unit and one column per length bin.

length_counts_vector​

length_counts_vector

Return global length-count values as a vector.

length_counts_vector(x, ...)

length_counts_vector.cfdnalab_global_length_counts(
  x,
  with_lengths = NULL,
  with_length_range = NULL,
  length_bin_idxs = NULL,
  ...
)

Arguments

  • x: A cfDNAlab global length-count object.
  • ...: Reserved for future methods.
  • with_lengths: Optional fragment length vector in base pairs. Returned values use the length bins containing these lengths. Multiple lengths must select distinct length bins.
  • with_length_range: Optional two-value fragment length range in base pairs. Returned values use whole length bins that overlap the half-open range [start, end).
  • length_bin_idxs: Optional one-based length-bin index vector. Use only one of with_lengths, with_length_range, or length_bin_idxs.

Returns

A named numeric vector with one value per length bin.

length_data_frame​

length_data_frame

Return length-count values as a data frame.

length_data_frame(x, ...)

length_data_frame.cfdnalab_global_length_counts(
  x,
  with_lengths = NULL,
  with_length_range = NULL,
  length_bin_idxs = NULL,
  value = "count",
  denominator = "all_bins",
  keep_wide = FALSE,
  ...
)

length_data_frame.cfdnalab_windowed_length_counts(
  x,
  window_idxs = NULL,
  with_lengths = NULL,
  with_length_range = NULL,
  length_bin_idxs = NULL,
  value = "count",
  denominator = "all_bins",
  keep_wide = FALSE,
  max_blacklisted_fraction = 1,
  ...
)

length_data_frame.cfdnalab_grouped_length_counts(
  x,
  groups = NULL,
  group_idxs = NULL,
  with_lengths = NULL,
  with_length_range = NULL,
  length_bin_idxs = NULL,
  value = "count",
  denominator = "all_bins",
  keep_wide = FALSE,
  max_blacklisted_fraction = 1,
  ...
)

Arguments

  • x: A cfDNAlab length-count object.
  • ...: Method-specific selection arguments.
  • with_lengths: Optional fragment length vector in base pairs. Returned values use the length bins containing these lengths. Multiple lengths must select distinct length bins.
  • with_length_range: Optional two-value fragment length range in base pairs. Returned values use whole length bins that overlap the half-open range [start, end).
  • length_bin_idxs: Optional one-based length-bin index vector. Use only one of with_lengths, with_length_range, or length_bin_idxs.
  • value: Which value to return: "count" returns raw counts. "fraction" returns counts divided by the row total. "density" returns fractions divided by length_width_bp, giving fraction per base pair so bins with different widths are comparable.
  • denominator: For value = "fraction" or value = "density", "all_bins" divides by the row total over all length bins, while "selected_bins" divides by the total over the returned length bins. Ignored for value = "count".
  • keep_wide: If TRUE, return one row per output unit with one value column per length bin. If FALSE, return one row per output unit and length bin.
  • window_idxs: Optional one-based window index vector.
  • max_blacklisted_fraction: Optional maximum blacklisted_fraction in 0..1 to retain before reshaping. The default 1.0 keeps all rows.
  • groups: Optional group name vector. Use either groups or group_idxs, not both.
  • group_idxs: Optional one-based group index vector.

Returns

A data frame with length-bin metadata and count-derived values.

window_metadata​

window_metadata

Return window metadata.

window_metadata.cfdnalab_windowed_end_motif_counts(x, ...)

window_metadata(x, ...)

window_metadata.cfdnalab_windowed_length_counts(x, ...)

window_metadata.cfdnalab_windowed_ref_kmer_frequencies(x, ...)

Arguments

  • x: A cfDNAlab object with window rows.
  • ...: Reserved for future methods.

Returns

A data frame with one row per window. Public genomic window metadata uses window_idx, chrom, start, and end columns.

group_metadata​

group_metadata

Return group metadata.

group_metadata.cfdnalab_grouped_end_motif_counts(x, ...)

group_metadata(x, ...)

group_metadata.cfdnalab_grouped_length_counts(x, ...)

group_metadata.cfdnalab_midpoint_profiles(x, ...)

group_metadata.cfdnalab_grouped_ref_kmer_frequencies(x, ...)

Arguments

  • x: A cfDNAlab object with a group axis.
  • ...: Reserved for future methods.

Returns

A data frame with one row per group.

group_idx​

group_idx

Look up a group index.

group_idx.cfdnalab_grouped_end_motif_counts(x, group_name, ...)

group_idx(x, ...)

group_idx.cfdnalab_grouped_length_counts(x, group_name, ...)

group_idx.cfdnalab_midpoint_profiles(x, group_name, ...)

group_idx.cfdnalab_grouped_ref_kmer_frequencies(x, group_name, ...)

Arguments

  • x: A cfDNAlab object with group labels.
  • group_name: Group name to look up.
  • ...: Method-specific lookup arguments.

Returns

A scalar one-based integer group index.