Skip to content

module adabmDCA.alignment

Alignment containers and FASTA/Stockholm input-output helpers.

Global Variables

  • TYPE_CHECKING

function detect_alignment_format

detect_alignment_format(path: 'str | Path') → Literal['fasta', 'stockholm']

Detect whether a file is FASTA or Stockholm from its first non-empty line.

Args:

  • path: Alignment file, optionally gzip-compressed.

Returns: "fasta" or "stockholm".

Raises:

  • AlignmentFormatError: If the format cannot be recognized.

function read_alignment

read_alignment(
    path: 'str | Path',
    format: 'AlignmentFormat' = 'auto',
    alignment_index: 'int | None' = None
) → Alignment

Read one aligned FASTA or Stockholm alignment, without filtering.

For validation, alphabet detection and filtering use load_alignment.

Args:

  • path: Alignment file, optionally gzip-compressed.
  • format: "auto" (detected), "fasta" or "stockholm".
  • alignment_index: Which alignment of a multi-alignment Stockholm file to read (0-based); required when there is more than one.

Returns: The Alignment.

Raises:

  • AlignmentLoadError: If the file cannot be read.
  • AlignmentFormatError: If the content is not a valid alignment.
  • AlignmentLengthError: If the sequences have different lengths.

function write_alignment

write_alignment(
    alignment: 'Alignment',
    path: 'str | Path',
    format: "Literal['fasta']" = 'fasta',
    line_width: 'int' = 0
) → Path

Write an alignment to a FASTA file.

Args:

  • alignment: Alignment to write.
  • path: Output file.
  • format: Output format; only "fasta" is supported.
  • line_width: Largest sequence-line length; 0 writes each sequence on one line.

Returns: The written path.

function normalize_gap_symbols

normalize_gap_symbols(
    alignment: 'Alignment',
    source_gap: 'str' = '.',
    target_gap: 'str' = '-'
) → Alignment

Replace one alignment gap symbol with another.

Stockholm permits dots as gap symbols, while adabmDCA and aligned FASTA files conventionally use hyphens. This transformation does not remove alignment columns.

Args:

  • alignment: Alignment to transform.
  • source_gap: Gap symbol to replace.
  • target_gap: Replacement gap symbol.

Returns: A new Alignment.

function convert_alignment

convert_alignment(
    input_path: 'str | Path',
    output_path: 'str | Path',
    input_format: 'AlignmentFormat' = 'auto',
    output_format: "Literal['fasta']" = 'fasta',
    alignment_index: 'int | None' = None,
    line_width: 'int' = 0
) → AlignmentConversionResult

Convert a FASTA or Stockholm alignment to canonical aligned FASTA.

Dots accepted as gaps by Stockholm are written as hyphens, the gap token used throughout adabmDCA. Lowercase residues are preserved; callers that want to delete insertion residues should use preprocess_alignment.

Args:

  • input_path: FASTA or Stockholm file.
  • output_path: FASTA file to write.
  • input_format: "auto", "fasta" or "stockholm".
  • output_format: Only "fasta" is supported.
  • alignment_index: Alignment to convert in a multi-alignment Stockholm file.
  • line_width: Largest sequence-line length; 0 means no wrapping.

Returns: An AlignmentConversionResult.

function convert_stockholm_to_fasta

convert_stockholm_to_fasta(
    input_path: 'str | Path',
    output_path: 'str | Path',
    alignment_index: 'int | None' = None,
    line_width: 'int' = 0
) → AlignmentConversionResult

Convert one Stockholm alignment to FASTA; see convert_alignment.

Args:

  • input_path: Stockholm file.
  • output_path: FASTA file to write.
  • alignment_index: Alignment to convert when the file contains several.
  • line_width: Largest sequence-line length; 0 means no wrapping.

Returns: An AlignmentConversionResult.

class Alignment

Aligned sequences with optional alphabet and filtering provenance.

Names and sequences retain their input order. The alignment must contain at least one nonempty sequence, and every sequence must have the same length. Constructing an alignment checks these structural constraints; adabmDCA.input_loading.load_alignment additionally resolves the alphabet, validates symbols, and optionally filters rows.

Args:

  • names: Sequence names, one per row.
  • sequences: Aligned sequence strings in the same order as names.
  • source: Path of the source file, if known.
  • tokens: Ordered alphabet used for encoding. None until resolved; index i in an encoding corresponds to tokens[i].
  • retained_indices: Positions of the current rows in the original alignment. Defaults to 0, 1, ..., M - 1.
  • dropped_indices: Original positions removed for invalid symbols.
  • duplicate_indices: Original positions removed as duplicates.
  • original_size: Number of rows before filtering. Defaults to M.

Note:

The provenance fields are populated by load_alignment. Plain Alignment construction does not check sequences against tokens.

method __init__

__init__(
    names: 'tuple[str, ]',
    sequences: 'tuple[str, ]',
    source: 'Path | None' = None,
    tokens: 'str | None' = None,
    retained_indices: 'tuple[int, ]' = (),
    dropped_indices: 'tuple[int, ]' = (),
    duplicate_indices: 'tuple[int, ]' = (),
    original_size: 'int' = 0
) → None

property encoded_sequences

Return integer token indices as a NumPy array of shape (M, L).

Each element is the position of its residue in self.tokens.

Raises:

  • InputValidationError: If no alphabet has been resolved. Pass the alignment through load_alignment first.

property num_sequences

Number of sequences (M) currently in the alignment.

property sequence_length

Number of aligned positions (L) in each sequence.

method to_dataframe

to_dataframe() → DataFrame

Return a pandas DataFrame with name and sequence columns.

The DataFrame has one row per sequence and preserves alignment order.

method to_dict

to_dict() → dict[str, object]

Return a JSON-compatible loading report without sequence data.

The report includes the source, original and retained row counts, filtering indices, aligned length, and tokens. For an alignment that has not been loaded, filtering indices describe its unchanged rows.

method to_onehot

to_onehot(flatten: 'bool' = False) → Tensor

Encode the alignment as a CPU torch.float32 one-hot tensor.

Args:

  • flatten: If False, return shape (M, L, q). If True, combine the position and token dimensions into shape (M, L * q), useful for PCA.

Returns: A tensor whose state features follow the order of self.tokens at each aligned position.

Raises:

  • InputValidationError: If tokens is unavailable. Load the alignment with load_alignment first.

method write_fasta

write_fasta(path: 'str | Path', line_width: 'int' = 0) → Path

Write names and sequences to an aligned FASTA file.

Args:

  • path: Output file path.
  • line_width: Maximum sequence line length. 0 writes each sequence on one line.

Returns: The output path as a pathlib.Path.

class AlignmentConversionResult

Outcome of convert_alignment.

Attributes:

  • alignment: The converted alignment.
  • input_format: Detected or given input format.
  • output_format: Written format ("fasta").
  • output_path: Written file.

method __init__

__init__(
    alignment: 'Alignment',
    input_format: 'str',
    output_format: 'str',
    output_path: 'Path'
) → None

method to_dict

to_dict() → dict[str, object]

Return the formats, output path and alignment size as a dictionary.

This file was automatically generated via lazydocs.