variant_aware

variant_aware#

Unified variant-aware scoring entry point for BRIDGE.

The script reads sequence windows from a FASTA file, optionally applies an allele substitution (REF -> ALT) based on metadata encoded in each FASTA header, and runs BRIDGE checkpoints to produce per-record prediction scores.

Pipelines#

The behavior is selected by optional CLI flags:

GWAS mode (default):
- Activated when no other pipeline flag is provided (or when –gwas is set).
- Uses a single BRIDGE checkpoint whose name is derived from the FASTA filename stem (i.e., <model_save_path>/<fasta_stem>.pth).
- Output format (one line per record):
```
<header_without_>       Prediction_score:<float>
```
Ribosnitch mode (–ribosnitch / –ribosnitches):
- For each FASTA record, extracts the last two tokens in the header as candidate cell lines and scores the sequence against every checkpoint in –model_save_path whose filename ends with _<cell_line>.pth.
- If –variation_mode=after (or –ribosnitch_after_variation) is active, the ALT allele is substituted before scoring (strand-aware: bases are complemented on ‘-’ strand).
- Output format (one line per (record, checkpoint)):
```
<header_without_>       <checkpoint_stem>       <float>
```
  Results are written under:
```
<ribosnitch_out_dir>/{before_mut,after_mut}/<basename(variant_out_file)>
```
Variant-catalog mode (–genomic_variants / –variant_catalog):
- For curated variant collections such as ClinVar / TCGA / 1000 Genomes, where FASTA headers include:
  - a region token: chr:start-end(strand)
  - an SNV token: POS:REF>ALT
  - model-id fields: typically “… <PROTEIN> in <CELL_LINE>”
- Provides robust parsing and optional off-by-one handling when locating the variant within the window.
- Output format matches the standalone catalog script:
```
<header_without_>       model_id=<...>  mode=<before|after>     Prediction_score:<float>
```

Common inputs#

–fasta_sequence_path : FASTA of window sequences (wrapped/multi-line FASTA is supported).
–variation_mode : before scores the input sequence as-is; after attempts ALT substitution.
–Transformer_path : transformer used by build_Transformer_embeddings.
–model_save_path : directory containing BRIDGE .pth checkpoints.
–variant_out_file : path to append results.

Functions

`build_argparser`()	Build and return the argument parser for the script.
`find_variant_index`(seq, seq_start, var_pos, ...)	Locate the 0-based variant index inside the window sequence.
`main`()	Main entry point for variant-aware scoring using BRIDGE.
`parse_header_catalog`(header_raw)	Parse a catalog-variant header (ClinVar, TCGA, 1000G style) from a FASTA header.
`parse_protein_cell_line`(fields)	Heuristically parses protein and cell line from header tokens in a FASTA header.
`process_sequences`(names, seqs, args, hub)	Process each FASTA record and append GWAS/BRIDGE variant-aware predictions.
`process_sequences_catalog_variants`(headers, ...)	Variant-aware scoring for ClinVar/TCGA/1000G-style FASTA batches (SNVs).
`process_sequences_gwas`(names, seqs, args, hub)	Process each FASTA record and append GWAS/BRIDGE variant-aware predictions.
`run_ribosnitches`(names, seqs, args, device)	Run ribosnitch scoring using the BRIDGE pipeline components.

Classes

ParsedHeader(header_raw, chrom, start, end, ...)

Parsed representation of a variant-window FASTA header.

variant_aware.process_sequences_gwas(names, seqs, args, hub)[source]#

Process each FASTA record and append GWAS/BRIDGE variant-aware predictions.

Parameters:

names (List[str]) – List of FASTA record headers (sequence identifiers).
seqs (List[str]) – List of FASTA sequence strings.
args (argparse.Namespace) – Command line arguments containing configurations like variation mode and output file.
hub (ModelHub) – A ModelHub object to manage model loading and device handling.

Return type:

None

Returns:

None. Results are written to the file specified in args.variant_out_file.

Exceptions:

Logs errors when:

Parsing the variant information fails.

Variant position is out of bounds or mismatches the REF base.

Example

>>> process_sequences_gwas(names, sequences, args, hub)

variant_aware.process_sequences(names, seqs, args, hub)[source]#

Process each FASTA record and append GWAS/BRIDGE variant-aware predictions.

Parameters:

names (List[str]) – List of FASTA record headers (sequence identifiers).
seqs (List[str]) – List of FASTA sequence strings.
args (argparse.Namespace) – Command line arguments containing configurations like variation mode and output file.
hub (ModelHub) – A ModelHub object to manage model loading and device handling.

Return type:

None

Returns:

None. Results are written to the file specified in args.variant_out_file.

Exceptions:

Logs errors when:

Parsing the variant information fails.

Variant position is out of bounds or mismatches the REF base.

Example

>>> process_sequences_gwas(names, sequences, args, hub)

class variant_aware.ParsedHeader(header_raw, chrom, start, end, strand, var_pos, ref, alt, protein, cell_line)[source]#

Bases: object

Parsed representation of a variant-window FASTA header.

header_raw: str#

chrom: str#

start: int#

end: int#

strand: str#

var_pos: int#

ref: str#

alt: str#

protein: Optional[str]#

cell_line: Optional[str]#

variant_aware.parse_protein_cell_line(fields)[source]#

Heuristically parses protein and cell line from header tokens in a FASTA header.

This function identifies the protein and cell line from a list of header tokens. It prefers the format “… <PROTEIN> in <CELL>” but falls back on older conventions where the protein and cell line are assumed to be at fixed positions in the header.

Parameters:

fields (List[str]) – A list of strings representing the tokens parsed from a FASTA header.

Return type:

Tuple[Optional[str], Optional[str]]

Returns:

Tuple[Optional[str], Optional[str]] – - protein (Optional[str]): The parsed protein name, or None if not found.

cell (Optional[str]): The parsed cell line name, or None if not found.

Exceptions:: None. If the header format does not match expectations, the function will attempt to fall back on different header conventions.

Example

>>> fields = ["GeneA", "in", "CellLineA"]
>>> protein, cell = parse_protein_cell_line(fields)
>>> print(protein, cell)
"GeneA", "CellLineA"

variant_aware.parse_header_catalog(header_raw)[source]#

Parse a catalog-variant header (ClinVar, TCGA, 1000G style) from a FASTA header.

Parameters:: header_raw (str) – The raw header string to parse.
Return type:: ParsedHeader
Returns:: ParsedHeader – A dataclass containing parsed region, variant, and model information.

Exceptions:: Raises ValueError if the header does not contain expected region or variant information.

Example

>>> header = ">chr1:100-200(+) 123:A>T ProteinA in CellLineA"
>>> parsed_header = parse_header_catalog(header)

variant_aware.find_variant_index(seq, seq_start, var_pos, ref, alt, try_off_by_one=True)[source]#

Locate the 0-based variant index inside the window sequence.

This function searches for the variant position within the given sequence. It returns the index of the matching base (REF or ALT) in the sequence. Optionally, it can attempt to handle the case where the variant position is off by one (e.g., due to off-by-one errors).

Parameters:

seq (str) – The sequence string in which to find the variant position.
seq_start (int) – The starting position of the sequence window.
var_pos (int) – The position of the variant (1-based index).
ref (str) – The reference base at the variant position.
alt (str) – The alternative base at the variant position.
try_off_by_one (bool, optional) – Whether to try the adjacent position (var_pos - 1) if the exact variant position is not found. Defaults to True.

Return type:

Tuple[Optional[int], str]

Returns:

Tuple[Optional[int], str] – - The index (0-based) of the base in the sequence that matches either REF or ALT. - A string indicating whether the base at the index is “ref”, “alt”, or “none” if neither match.

Exceptions:: None. If no match is found, the function returns None, “none” without raising any errors.

Example

>>> find_variant_index("AGCTG", 0, 3, "T", "G")
(2, "ref")

variant_aware.process_sequences_catalog_variants(headers, seqs, args, hub)[source]#

Variant-aware scoring for ClinVar/TCGA/1000G-style FASTA batches (SNVs).

Parameters:

headers (List[str]) – List of FASTA record headers (with variant information).
seqs (List[str]) – List of FASTA sequences.
args (argparse.Namespace) – Command-line arguments specifying paths and scoring options.
hub (ModelHub) – ModelHub object for model loading.

Return type:

None

Returns:

None. Results are written to the file specified in args.variant_out_file.

Exceptions:: Logs warnings and skips records when: - Variant position is out of bounds. - REF/ALT mismatch occurs.

Example

>>> process_sequences_catalog_variants(headers, sequences, args, hub)

variant_aware.run_ribosnitches(names, seqs, args, device)[source]#

Run ribosnitch scoring using the BRIDGE pipeline components.

This function scores a sequence using multiple BRIDGE models based on cell-line-specific checkpoints. It applies mutation behavior and computes prediction scores for each (record, checkpoint) pair.

Parameters:

names (List[str]) – List of FASTA record headers (sequence identifiers).
seqs (List[str]) – List of FASTA sequences to be scored.
args (argparse.Namespace) – Command-line arguments that define scoring options and model paths.
device (torch.device) – The device (CPU/GPU) to perform computation on.

Return type:

None

Returns:

None. The results are written to the output file specified by args.variant_out_file.

Raises:

FileNotFoundError – If the provided model path does not exist.
ValueError – If the variant substitution cannot be applied due to base mismatches.

Example

>>> run_ribosnitches(names, sequences, args, device)

variant_aware.build_argparser()[source]#

Build and return the argument parser for the script.

Return type:: ArgumentParser

variant_aware.main()[source]#

Main entry point for variant-aware scoring using BRIDGE. Processes FASTA sequences through one of three available pipelines: GWAS, Ribosnitch, or Catalog Variants.

Return type:: None

variant_aware

Contents

variant_aware#

Pipelines#

Common inputs#