`ms_sv()` is the SV input link of the msuiter grammar. It is an S7 generic: given a file path it reads a BEDPE file (`.bedpe`, optionally `.gz`), derives the rearrangement class and the kat-region clustered flag exactly like SigProfilerMatrixGenerator and returns a typed data.frame; given a data.frame with the same columns it runs the same pipeline directly. All violations raise `msuiter_error_*` conditions.
Arguments
- x
A character string naming one BEDPE file (`.bedpe`, optionally `.gz`), or a data.frame carrying the six coordinate columns `chrom1, start1, end1, chrom2, start2, end2` plus either an `svclass` (or `SVTYPE`) column or the `strand1`/`strand2` pair, and optionally `sample`.
- ...
No passthrough arguments: anything arriving in `...` is rejected as an argument-spelling error (`msuiter_error_input`).
Value
A data.frame with columns `sample` (only when present in the input), `chrom1, start1, end1, chrom2, start2, end2` (verbatim coordinates), `svtype` (one of `deletion`, `tandem-duplication`, `inversion`, `translocation`), `size_bp` and `clustered`, with the io `provenance` in attribute `"provenance"`.
Details
Rearrangement classes follow SPMG `SVMatrixGenerator.py` (master `edccbea6`, :1100-1128): a provided `svclass`/`SVTYPE` column is used verbatim and must contain exactly `deletion`, `tandem-duplication`, `inversion` or `translocation` (foreign labels hit a KeyError downstream upstream, :1251, and are rejected here at read time); otherwise the strands decide: different chromosomes -> `translocation`, mixed strands -> `inversion`, `(+,+)` -> `deletion`, `(-,-)` -> `tandem-duplication`, anything else is an error (:1123-1126). The short channel names `del`/`tds`/`inv`/`trans` come from the upstream `svclass_mapping` (:1228-1233) and are applied by the catalog layer (sv32.rs), not here.
`size_bp` is `abs(start1 - start2)` for every event (:1138-1159; ignored by SV32 for translocations, :1158-1161). BEDPE coordinates are consumed verbatim (0-based half-open per the BEDPE specification): every downstream quantity is a difference or an ordering, hence offset-invariant. Non-translocation events below 1000 bp are NOT dropped here – the drop is the catalog layer's ledger rule (:1184-1189); the io layer only reports `n_below_1kb_non_trans` in the parse statistics.
The `clustered` flag is the output of upstream `annotateBedpe` (:797-930): breakpoints are pooled per chromosome (both ends of every event), kat regions are segmented by exactPcf (`kmin = 10`, `3e9 / n_breakpoints / 10` (:824-845) and `gamma = 25 * MAD` breakpoint rate factor >= 1 (:872-890, assignPvalues :485-501), and a rearrangement is clustered when any of its breakpoints falls in a kat region (:916-927). Chromosomes with 10 or fewer breakpoints are never clustered (:825-827, :860-862). The port is validated against real upstream annotateBedpe goldens (34 BEDPEs, identical flags). Complexity is O(n^2) in the breakpoints of a chromosome, as upstream's exactPcf.
Chromosome names are passed through verbatim (upstream strips a leading `chr`, :1041-1055 – a deliberate divergence: the msuiter catalog layer is chromosome-opaque). An `is_clustered` input column is ignored (upstream overwrites it, :919-926).
The returned `provenance` attribute carries `source`/`format`, the `parse` statistics (`n_lines`, `n_records`, `n_derived_svclass`, `n_provided_svclass`, `n_translocation`, `n_below_1kb_non_trans`) and the `kat` parameter block (`kmin`, `min_bps`, `genome_size`, `peak_factor`, `gamma_sdev`, `n_kat_regions`).
Examples
lines <- c(
"chrom1\tstart1\tend1\tchrom2\tstart2\tend2\tstrand1\tstrand2",
"19\t21268384\t21268385\t19\t21327858\t21327859\t+\t+",
"19\t30000000\t30000001\t19\t31000000\t31000001\t+\t-",
"3\t1000000\t1000001\t7\t2000000\t2000001\t+\t+"
)
path <- tempfile(fileext = ".bedpe")
writeLines(lines, path)
sv <- ms_sv(path)
sv$svtype
#> [1] "deletion" "inversion" "translocation"
sv$clustered # sparse input: no chromosome exceeds the 10-breakpoint gate
#> [1] FALSE FALSE FALSE
unlink(path)