Skip to content

module adabmDCA.preprocessing

Pure and file-oriented multiple-sequence-alignment preprocessing.

Global Variables

  • RESULT_SCHEMA_VERSION

function remove_insertions

remove_insertions(alignment: 'Alignment') → Alignment

Remove dots and lowercase insertion residues from every sequence.

Args:

  • alignment: Profile alignment with insertion states in lowercase.

Returns: A new Alignment containing only the match columns.

function filter_gap_fraction

filter_gap_fraction(
    alignment: 'Alignment',
    max_gap_fraction: 'float' = 0.2,
    gap_token: 'str' = '-'
) → AlignmentFilterResult

Remove sequences whose gap fraction is greater than the threshold.

A sequence with a gap fraction exactly equal to the threshold is retained.

Args:

  • alignment: Alignment to filter.
  • max_gap_fraction: Largest allowed fraction of gaps, in [0, 1].
  • gap_token: Gap symbol.

Returns: An AlignmentFilterResult.

function preprocess_alignment

preprocess_alignment(
    input_path: 'str | Path',
    output_path: 'str | Path | None' = None,
    input_format: 'AlignmentFormat' = 'auto',
    alignment_index: 'int | None' = None,
    config: 'AlignmentProcessingConfig | None' = None,
    remove_insertions: 'bool | None' = None,
    max_gap_fraction: 'float | None' = None,
    remove_duplicates: 'bool | None' = None,
    alphabet: 'str | None' = None,
    gap_token: 'str | None' = None,
    unknown_tokens: 'str | None' = None,
    line_width: 'int' = 0
) → AlignmentProcessingResult

Clean a raw alignment for DCA: read, transform, filter and optionally write it.

Steps, each optional: remove insertions (or normalize dots to "-"), check tokens against an alphabet, drop gappy sequences, drop duplicates. Keyword options override the corresponding AlignmentProcessingConfig fields.

Args:

  • input_path: FASTA or Stockholm file.
  • output_path: FASTA file to write, or None.
  • input_format: "auto", "fasta" or "stockholm".
  • alignment_index: Alignment to read from a multi-alignment Stockholm file.
  • config: Base settings; see AlignmentProcessingConfig.
  • remove_insertions: Overrides config.remove_insertions.
  • max_gap_fraction: Overrides config.max_gap_fraction.
  • remove_duplicates: Overrides config.remove_duplicates.
  • alphabet: Overrides config.alphabet.
  • gap_token: Overrides config.gap_token.
  • unknown_tokens: Overrides config.unknown_tokens.
  • line_width: Largest sequence-line length of the output; 0 means no wrapping.

Returns: An AlignmentProcessingResult.

Raises:

  • InputValidationError: If an option is invalid, or unknown tokens are found with unknown_tokens="error".

Example: 

result = preprocess_alignment("RF00379.sto", output_path="clean.fasta",
                              remove_insertions=True, max_gap_fraction=0.2)
result.report.output_sequences

class AlignmentProcessingConfig

Transformations applied by preprocess_alignment, in this order.

Attributes:

  • remove_insertions: Delete lowercase residues and dots (insertion states of profile alignments); otherwise dots become "-".
  • max_gap_fraction: Remove sequences with a larger fraction of gaps, or None.
  • remove_duplicates: Keep only the first copy of identical sequences.
  • alphabet: Check tokens against this alphabet ("auto" detects it), or None to skip the check.
  • gap_token: Gap symbol counted by max_gap_fraction.
  • unknown_tokens: With alphabet: "gap" replaces unknown tokens with "-", "remove" drops their sequences, "error" raises.

method __init__

__init__(
    remove_insertions: 'bool' = False,
    max_gap_fraction: 'float | None' = None,
    remove_duplicates: 'bool' = False,
    alphabet: 'str | None' = None,
    gap_token: 'str' = '-',
    unknown_tokens: 'str' = 'gap'
) → None

class AlignmentProcessingReport

What preprocess_alignment changed.

Attributes:

  • input_sequences: Sequences read.
  • output_sequences: Sequences kept.
  • input_length: Alignment length before processing.
  • output_length: Alignment length after processing.
  • removed_insertion_characters: Insertion residues deleted.
  • normalized_gap_characters: Dots turned into "-".
  • removed_for_gap_fraction: Sequences dropped for too many gaps.
  • removed_as_duplicates: Duplicate sequences dropped.
  • replaced_unknown_characters: Unknown tokens replaced with "-".
  • removed_for_unknown_tokens: Sequences dropped for unknown tokens.
  • max_gap_fraction: Gap threshold used, if any.
  • removed_names: Names of all dropped sequences.

method __init__

__init__(
    input_sequences: 'int',
    output_sequences: 'int',
    input_length: 'int',
    output_length: 'int',
    removed_insertion_characters: 'int' = 0,
    normalized_gap_characters: 'int' = 0,
    removed_for_gap_fraction: 'int' = 0,
    removed_as_duplicates: 'int' = 0,
    replaced_unknown_characters: 'int' = 0,
    removed_for_unknown_tokens: 'int' = 0,
    max_gap_fraction: 'float | None' = None,
    removed_names: 'tuple[str, ]' = ()
) → None

method to_dict

to_dict() → dict[str, object]

Return the report as a dictionary.

method to_json

to_json(path: 'str | Path', indent: 'int' = 2) → Path

Write the report as a versioned JSON document.

Args:

  • path: Output file.
  • indent: JSON indentation.

Returns: The written path.

class AlignmentFilterResult

Outcome of filter_gap_fraction.

Attributes:

  • alignment: Kept sequences.
  • keep_mask: For each input sequence, whether it was kept.
  • gap_fractions: Gap fraction of each input sequence.
  • removed_names: Names of the removed sequences.
  • report: Summary of the filtering.

method __init__

__init__(
    alignment: 'Alignment',
    keep_mask: 'tuple[bool, ]',
    gap_fractions: 'tuple[float, ]',
    removed_names: 'tuple[str, ]',
    report: 'AlignmentProcessingReport'
) → None

class AlignmentProcessingResult

Outcome of preprocess_alignment.

Attributes:

  • alignment: Processed alignment.
  • keep_mask: For each input sequence, whether it was kept.
  • report: What was changed, see AlignmentProcessingReport.
  • output_path: Written FASTA file, if output_path was given.

method __init__

__init__(
    alignment: 'Alignment',
    keep_mask: 'tuple[bool, ]',
    report: 'AlignmentProcessingReport',
    output_path: 'Path | None' = None
) → None

This file was automatically generated via lazydocs.