seismicrna.duplex package

seismicrna.duplex.run(input_path: Iterable[str | Path] = Sentinel.UNSET, *, duplex_pair: bool = True, dimer: bool = False, duplex_file: str | None = None, duplex_sequence: Iterable[str] = (), duplex_table_region: bool = False, duplex_full_ref: Iterable[str] = (), duplex_region_ref: Iterable[str] = (), branch: str = '', verify_times: bool = True, num_cpus: int = 4, force: bool = False)

Combine two references into a duplex for cofolding.

Each of these ways of choosing the 3’ strand contributes its own duplexes, so any combination of them can be used at once:

  • --duplex-pair (the default): every pairwise combination of the input tables that share the same branches.

  • --dimer: the input table itself (a homodimer).

  • --duplex-file / --duplex-sequence: a partner without data (a FASTA file or a raw 5’-to-3’ sequence).

By default each strand spans its full reference (with the table’s data mapped onto its region); --duplex-table-region restricts every strand to its table region, and --duplex-full-ref / --duplex-region-ref override that choice per reference.

Parameters:

  • duplex_pair (bool) – Duplex every pair of input profiles [keyword-only, default: True]

  • dimer (bool) – Duplex each input profile with itself, to model a homodimer [keyword-only, default: False]

  • duplex_file (str | None) – Duplex each input profile with the sequences in this FASTA file (the second strand of each duplex, without any mutational data) [keyword-only, default: None]

  • duplex_sequence (Iterable) – Duplex each input profile with a named strand given as its name and its raw sequence 5’ to 3’ (e.g. –duplex-sequence ASO ATTCACTTTCATAATGCTGG); this second strand carries no mutational data [keyword-only, default: ()]

  • duplex_table_region (bool) – Default for every strand: build it from only the source table’s region (–duplex-table-region), or from its full reference sequence with the table’s data mapped onto that region (–duplex-full, the default) [keyword-only, default: False]

  • duplex_full_ref (Iterable) – Build the strand for this reference from its full reference sequence, overriding –duplex-full/–duplex-table-region for it (repeatable) [keyword-only, default: ()]

  • duplex_region_ref (Iterable) – Build the strand for this reference from only its table region, overriding –duplex-full/–duplex-table-region for it (repeatable) [keyword-only, default: ()]

  • branch (str) – Create a new branch of the workflow with this name [keyword-only, default: ‘’]

  • verify_times (bool) – Verify that report files from later steps have later timestamps [keyword-only, default: True]

  • num_cpus (int) – Use up to this many CPUs simultaneously [keyword-only, default: 4]

  • force (bool) – Force all tasks to run, overwriting any existing output files [keyword-only, default: False]

Subpackages

Submodules

class seismicrna.duplex.dataset.DuplexDataset(report_file: str | Path, verify_times: bool = True)

Bases: RegionDataset

Dataset made by combining two source datasets from different references into one duplex, without duplicating their read-level data (the sources are reached through table1/table2).

property best_k

Best number of clusters.

property cut: int

Length of the 5’ strand (position of the strand break).

property data_dirs

All directories containing data for the dataset.

property dataset1
property dataset2
property duplex_ks: list[int]

Numbers of clusters in the duplex (empty if unclustered).

get_batch(batch_num: int)

Get a specific batch of data.

classmethod get_report_type()

Type of report.

property header_depth: int

3 when the duplex is clustered (relationship, K, cluster), else 1 (relationship).

Type:

Number of column-header rows in the duplex CSV

property ks

Numbers of clusters.

property num_batches

Number of batches.

property pattern

Pattern of mutations to count.

property probe: str
property refseq

Sequence of the reference.

property region

Region of the dataset.

property source_tables

The two source position tables (loaded lazily); an entry is None for a data-less strand (e.g. a bare sequence).

property table1

Position table of the 5’ strand’s source (always present).

property table2

Position table of the 3’ strand’s source, or None if it has no data (a bare sequence).

seismicrna.duplex.dataset.fuse_names(name_a: str, name_b: str, collapse_identical: bool = True)

Join two identifiers. An empty name is dropped (returns the other). Two identical names collapse to one when collapse_identical is True (e.g. the shared sample of a homodimer); pass False to keep them joined (e.g. a homodimer reference X__X, so its fold is not mistaken for a monomer fold of X).

seismicrna.duplex.dataset.load_source_table(table_file: str | Path)

Load a source position table (filter or cluster) from its CSV.

class seismicrna.duplex.io.DuplexFile

Bases: HasRegFilePath, ABC

classmethod get_step()

Step of the workflow.

class seismicrna.duplex.io.DuplexIO

Bases: DuplexFile, RegFileIO, ABC

class seismicrna.duplex.io.DuplexRefseqIO(*args, refseq: DNA, **kwargs)

Bases: RegBrickleIO, DuplexFile, RegFileIO

The fused reference sequence of a duplex, stored like any other reference sequence (a brickle file referenced by checksum), in the duplex’s region directory alongside its table and report.

classmethod get_file_seg_type()

Type of the last segment in the path.

property refseq
class seismicrna.duplex.main.Strand(seq: DNA, ref: str, reg: str, sample: str, branches: dict, table: object | None, source: str, table_region: bool = False)

Bases: object

One strand of a duplex to be combined.

branches: dict
classmethod from_sequence(seq: DNA, name: str)
classmethod from_table(table, top: Path, table_region: bool = False)
ref: str
reg: str
sample: str
seq: DNA
source: str
table: object | None
table_region: bool = False
seismicrna.duplex.main.iter_duplex_pairs(tables: Iterable)

Yield every pair of tables whose branches match.

Unlike a comparison graph, whose two tables must share a reference and region, a duplex is two different references, so its two strands are grouped by their branches instead: make_duplex refuses to duplex references from different branches, so pairing only within a branch avoids building pairs that would just be rejected.

seismicrna.duplex.main.iter_raw_strands(sequences: Iterable[tuple[str, DNA]])

Yield a data-less Strand for every (name, sequence) pair (each sequence given 5’ to 3’).

seismicrna.duplex.main.iter_sequence_strands(fasta: Path)

Yield a data-less Strand for every sequence in a FASTA file.

seismicrna.duplex.main.make_duplex(strand1: Strand, strand2: Strand, top: Path, *, branch: str, force: bool)

Fuse two strands into one duplex position table.

The 5’ strand (strand1) must carry data (its columns define the table); the 3’ strand may be data-less (e.g. a bare sequence). When either strand is clustered, the duplex is the cross-product of the two strands’ clusters (at each strand’s best K): one fused profile per combination of a 5’-strand cluster and a 3’-strand cluster.

seismicrna.duplex.main.run(input_path: Iterable[str | Path] = Sentinel.UNSET, *, duplex_pair: bool = True, dimer: bool = False, duplex_file: str | None = None, duplex_sequence: Iterable[str] = (), duplex_table_region: bool = False, duplex_full_ref: Iterable[str] = (), duplex_region_ref: Iterable[str] = (), branch: str = '', verify_times: bool = True, num_cpus: int = 4, force: bool = False)

Combine two references into a duplex for cofolding.

Each of these ways of choosing the 3’ strand contributes its own duplexes, so any combination of them can be used at once:

  • --duplex-pair (the default): every pairwise combination of the input tables that share the same branches.

  • --dimer: the input table itself (a homodimer).

  • --duplex-file / --duplex-sequence: a partner without data (a FASTA file or a raw 5’-to-3’ sequence).

By default each strand spans its full reference (with the table’s data mapped onto its region); --duplex-table-region restricts every strand to its table region, and --duplex-full-ref / --duplex-region-ref override that choice per reference.

Parameters:

  • duplex_pair (bool) – Duplex every pair of input profiles [keyword-only, default: True]

  • dimer (bool) – Duplex each input profile with itself, to model a homodimer [keyword-only, default: False]

  • duplex_file (str | None) – Duplex each input profile with the sequences in this FASTA file (the second strand of each duplex, without any mutational data) [keyword-only, default: None]

  • duplex_sequence (Iterable) – Duplex each input profile with a named strand given as its name and its raw sequence 5’ to 3’ (e.g. –duplex-sequence ASO ATTCACTTTCATAATGCTGG); this second strand carries no mutational data [keyword-only, default: ()]

  • duplex_table_region (bool) – Default for every strand: build it from only the source table’s region (–duplex-table-region), or from its full reference sequence with the table’s data mapped onto that region (–duplex-full, the default) [keyword-only, default: False]

  • duplex_full_ref (Iterable) – Build the strand for this reference from its full reference sequence, overriding –duplex-full/–duplex-table-region for it (repeatable) [keyword-only, default: ()]

  • duplex_region_ref (Iterable) – Build the strand for this reference from only its table region, overriding –duplex-full/–duplex-table-region for it (repeatable) [keyword-only, default: ()]

  • branch (str) – Create a new branch of the workflow with this name [keyword-only, default: ‘’]

  • verify_times (bool) – Verify that report files from later steps have later timestamps [keyword-only, default: True]

  • num_cpus (int) – Use up to this many CPUs simultaneously [keyword-only, default: 4]

  • force (bool) – Force all tasks to run, overwriting any existing output files [keyword-only, default: False]

seismicrna.duplex.main.strand_clusters(strand: Strand)

List the per-cluster data of one strand as (label, DataFrame) pairs, one per cluster at the table’s best number of clusters.

Each DataFrame is indexed by position (spanning either the table’s region or the full reference, per strand.table_region) and has one column per relationship. An unclustered (average) table yields a single (None, data) pair, and a data-less strand yields a single (None, None) placeholder (its positions get no data).

seismicrna.duplex.main.strand_uses_table_region(ref: str, *, default: bool, region_refs: set[str], full_refs: set[str]) → bool

Decide whether the strand for one reference spans only its table region (True) or its full reference (False), letting per-reference overrides take precedence over the global default.

class seismicrna.duplex.profile.RNACofoldProfile(*, cut: int, fold_fpaired: float | int = 0.5, **kwargs)

Bases: RNAFoldProfile

Mutational profile of a duplex of two RNAs to cofold together.

The two strands are joined (5’ strand first) by a short unpaired linker into a single sequence numbered from 1, so that the duplex is represented exactly like any other folded region and its outputs are compatible with the rest of SEISMIC-RNA (e.g. drawing and graphing). The duplex is folded by RNAcofold on the two strands alone; the linker only exists in the output, where it turns each inter-strand base pair into a drawable loop.

property cofold_shape_method

SHAPE incorporation method for RNAcofold’s --shapeMethod (RNAcofold has no modern --sp-strategy interface, so only the Deigan Dm..b.. form is available). Deigan passes the user’s slope/intercept straight through; Cordero passes the slope and intercept that back-transform the DMS pseudo-energies.

classmethod from_duplex(profile: RNAProfile, cut: int, **kwargs)

Make a duplex profile from an already-fused (duplex) profile and its strand-break position.

property intercept_param

Intercept parameter (kcal/mol) for structure prediction.

property mus_normalized

Mutation rates after normalizing and winsorizing each strand independently, since the two strands can come from different samples with different overall reactivities.

property pseudoenergies

Cordero pseudoenergies (kcal/mol) for structure prediction. Each strand is fit independently (its own scale factor), because the two strands can come from different samples whose overall reactivities differ; pooling them would bias the fit. The resulting energies share one kcal/mol scale, so a single pseudomus/shapeMethod still reproduces them for RNAcofold.

property pseudomus

Pseudo-mutation rates for structure prediction.

property slope_param

Slope parameter (kcal/mol) for structure prediction.

write_fasta(top: Path, branch: str)

Write the two strands to a FASTA file, separated by & and without the linker, as the input for RNAcofold.

write_mus_file(top: Path, branch: str)

Write the folding data (reactivities for Deigan, or Cordero pseudo-mutation rates) for RNAcofold, numbered along the two strands alone (i.e. without the linker positions).

class seismicrna.duplex.report.DuplexReport(**kwargs: Any | Callable[[Report], Any])

Bases: RegReport, DuplexIO

Report for a duplex of two source datasets into one duplex.

A duplex report records only the fused identity, the two strands’ combined sequence, the strand-break position, and pointers to the source tables; the per-position data live in the duplex’s own CSV, and the read-level data stay in the source datasets (no duplication).

classmethod get_checksum_report_fields()

Checksum fields of the report.

classmethod get_file_seg_type()

Type of the last segment in the path.

classmethod get_param_report_fields()

Parameter fields of the report.

class seismicrna.duplex.table.DuplexPositionTable

Bases: DuplexTable, PartialPositionTable, ABC

Position table of a duplex of two sources into one duplex.

property cut: int

Length of the 5’ strand (position of the strand break).

property data1

Per-position data of the 5’ strand’s source.

property data2

Per-position data of the 3’ strand’s source, or None.

property table1

Position table of the 5’ strand’s source.

property table2

Position table of the 3’ strand’s source, or None if the 3’ strand has no data (a bare sequence).

class seismicrna.duplex.table.DuplexPositionTableLoader(table_file: str | Path, **kwargs)

Bases: PositionTableLoader, DuplexPositionTable

property data

Table’s data.

class seismicrna.duplex.table.DuplexTable

Bases: AverageTable, DuplexFile, ABC

classmethod get_load_function()

LoadFunction for all Dataset types for this Table.

Wrapper around RNAcofold from the ViennaRNA package by Lorenz and Hofacker at the University of Vienna: https://www.tbi.univie.ac.at/RNA/

RNAcofold predicts the secondary structure of a duplex of two RNA strands. Its input and output separate the two strands with an ampersand (&); this module removes the ampersand so that the duplex is represented as a single, continuously numbered sequence, exactly like any structure produced by seismic fold.

seismicrna.duplex.viennarna.extract_duplex(vienna_input: Path, db_output: Path, force: bool = False)

Convert the output of RNAcofold to a dot-bracket (DB) file.

RNAcofold prints, for each duplex, a title line, the two strands joined by &, and the structure of the two strands joined by & followed by the free energy in parentheses:

>NAME
SEQ5&SEQ3
STRUCT5&STRUCT3 (ENERGY)

This function replaces the & with a short unpaired linker in both the sequence and the structure, so that the duplex becomes a single molecule in which each inter-strand base pair encloses the linker as a loop, and prepends the free energy to the title (matching seismic fold):

>ENERGY = {energy} {NAME}
SEQ5{linker}SEQ3
STRUCT5{....}STRUCT3
Parameters:

  • vienna_input (Path) – Path of the RNAcofold output file to convert.

  • db_output (Path) – Path of the DB file to which to write the converted structure.

  • force (bool = False) – Overwrite the output DB file if it already exists.

seismicrna.duplex.viennarna.make_rnacofold_cmd(fasta_file: Path, vienna_file: Path, *, shape_file: Path | None, shape_method: str | None, fold_constraint: Path | None, fold_temp_c: float, fold_isolated: bool, fold_md: int)

Build the shell command to run RNAcofold.

RNAcofold offers only the older SHAPE interface (--shape / --shapeMethod), not the newer --sp-data / --sp-strategy interface of RNAfold, so reactivities are passed accordingly.

Parameters:

  • fasta_file (Path) – Input FASTA file containing the two strands separated by &.

  • vienna_file (Path) – Output path for the intermediate vienna file.

  • shape_file (Path or None) – File of per-position reactivity data passed to --shape; None disables soft constraints.

  • shape_method (str or None) – SHAPE incorporation method passed to --shapeMethod (e.g. Dm1.8b-0.6 for Deigan); None omits the flag.

  • fold_constraint (Path or None) – Hard-constraint file passed to --constraint; None omits the flag.

  • fold_temp_c (float) – Folding temperature in degrees Celsius.

  • fold_isolated (bool) – If True, allow isolated base pairs; if False, pass --noLP.

  • fold_md (int) – Maximum base-pair span in nucleotides; 0 disables the limit.

Returns:

A shell command string ready to be executed.

Return type:

str

seismicrna.duplex.viennarna.run_rnacofold(fasta_tmp: Path, ct_tmp: Path, ct_out: Path, vienna_tmp: Path, db_tmp: Path, *, shape_file: Path | None, shape_method: str | None, fold_constraint: Path | None, fold_temp_c: float, fold_isolated: bool, fold_md: int, end5: int, fold_dry_run: bool = False)

Run RNAcofold on pre-built paths, convert to CT, retitle, and renumber.