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, ...)

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, ...)

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 end-motif storage mode.
row_modeReturn the end-motif row mode.
motifsFor ordinary end-motif stores, the motif column contains concrete motif labels.
motif_idxLook up a motif index.
has_motifTest whether an end-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 stores are not densified unless the method explicitly receives allow_densify = TRUE.
dense_counts_vectorSparse stores are not densified unless the method explicitly receives allow_densify = TRUE.
sparse_counts_matrixSparse stores are converted directly from their stored COO arrays.
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 end-motif storage mode.

storage_mode.cfdnalab_end_motif_counts(x, ...)

storage_mode(x, ...)

Arguments

  • x: A cfDNAlab end-motif object.
  • ...: Reserved for future methods.

Returns

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

row_mode​

row_mode

Return the end-motif row mode.

row_mode.cfdnalab_end_motif_counts(x, ...)

row_mode(x, ...)

Arguments

  • x: A cfDNAlab end-motif object.
  • ...: Reserved for future methods.

Returns

A scalar character value describing the row axis.

motifs​

motifs

For ordinary end-motif stores, the motif column contains concrete motif labels. For grouped motifs-file output, the same column contains user-defined group names from the motif axis.

motifs.cfdnalab_end_motif_counts(x, ...)

motifs(x, ...)

Arguments

  • x: A cfDNAlab end-motif object.
  • ...: 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, ...)

Arguments

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

Returns

A scalar one-based integer motif index.

has_motif​

has_motif

Test whether an end-motif label exists.

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

has_motif(x, ...)

Arguments

  • x: A cfDNAlab end-motif object.
  • 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, ...)

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, ...)

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, ...)

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, densify = FALSE, motifs = NULL, motif_idxs = NULL, ...)

end_motif_data_frame.cfdnalab_windowed_end_motif_counts(
  x,
  window_idxs = NULL,
  densify = FALSE,
  motifs = NULL,
  motif_idxs = NULL,
  max_blacklisted_fraction = 1,
  ...
)

end_motif_data_frame.cfdnalab_grouped_end_motif_counts(
  x,
  groups = NULL,
  group_idxs = NULL,
  densify = FALSE,
  motifs = NULL,
  motif_idxs = NULL,
  max_blacklisted_fraction = 1,
  ...
)

end_motif_data_frame(x, ...)

Arguments

  • x: A cfDNAlab end-motif object.
  • 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.
  • ...: 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.

dense_counts_matrix​

dense_counts_matrix

Sparse stores are not densified unless the method explicitly receives allow_densify = TRUE.

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, ...)

Arguments

  • x: A cfDNAlab end-motif object.
  • 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 stores are not densified unless the method explicitly receives allow_densify = TRUE.

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

dense_counts_vector(x, ...)

Arguments

  • x: A cfDNAlab global end-motif object.
  • 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.

sparse_counts_matrix​

sparse_counts_matrix

Sparse stores are converted directly from their stored COO arrays. Dense stores are read into memory before conversion.

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, ...)

Arguments

  • x: A cfDNAlab end-motif object.
  • 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.

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, ...)

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, ...)

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, ...)

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.