mutcleaner.utils.sequence_io#

Utilities for reading and writing sequence files without BioPython dependency.

Functions

load_sequences(file_path[, header_parser, ...])

Load sequences from various file formats

parse_custom_delimiter_header([delimiter, ...])

Create a header parser for custom delimiter-based formats

parse_fasta(file_path[, header_parser, ...])

Parse FASTA file with custom header parsing

parse_ncbi_header(header)

Parse NCBI FASTA header to extract ID and metadata

parse_simple_header(header)

Simple header parser that uses the first word as ID

parse_uniprot_header(header)

Parse UniProt FASTA header to extract ID and metadata

write_fasta(sequences, file_path[, ...])

Write sequences to FASTA file
mutcleaner.utils.sequence_io.load_sequences(file_path, header_parser=None, format=None, id_column=None, sequence_column=None)[source]#

Load sequences from various file formats

Parameters:

  • file_path (Union[str, Path]) – Path to sequence file

  • header_parser (Optional[Callable[[str], Tuple[str, Dict[str, str]]]]) – Function to parse FASTA headers (only used for FASTA format)

  • format (Optional[str]) – File format. If None, inferred from extension. Supported: ‘fasta’, ‘csv’, ‘tsv’, ‘json’

  • id_column (Optional[str]) – Column name for sequence IDs (CSV/TSV only)

  • sequence_column (Optional[str]) – Column name for sequences (CSV/TSV only)

Return type:

Dict[str, str]

Returns:

Dictionary mapping sequence IDs to sequences

Examples

>>> # Load UniProt FASTA
>>> seqs = load_sequences("uniprot.fasta")

>>> # Load FASTA with custom parser
>>> seqs = load_sequences("genes.fasta", header_parser=parse_simple_header)

>>> # Load CSV with specified columns
>>> seqs = load_sequences("sequences.csv", id_column="protein_id", sequence_column="aa_sequence")

>>> # Load with automatic column detection
>>> seqs = load_sequences("sequences.csv")
mutcleaner.utils.sequence_io.parse_custom_delimiter_header(delimiter='|', id_position=0)[source]#

Create a header parser for custom delimiter-based formats

Parameters:

  • delimiter (str) – Delimiter character to split the header

  • id_position (int) – Position of the ID in the split parts (0-based)

Return type:

Callable

Returns:

Header parser function

Examples

>>> parser = parse_custom_delimiter_header('|', 1)
>>> parser("db|GENE1|other|info")
('GENE1', {'parts': ['db', 'other', 'info']})
mutcleaner.utils.sequence_io.parse_fasta(file_path, header_parser=None, clean_sequence=True)[source]#

Parse FASTA file with custom header parsing

Parameters:

  • file_path (Union[str, Path]) – Path to FASTA file

  • header_parser (Optional[Callable[[str], Tuple[str, Dict[str, str]]]]) – Function to parse headers. Should take header string and return (id, metadata). If None, uses parse_uniprot_header as default.

  • clean_sequence (bool) – Whether to clean sequences (remove whitespace, numbers, etc.)

Return type:

Dict[str, Dict[str, Any]]

Returns:

Dictionary mapping sequence IDs to {‘sequence’: str, ‘metadata’: dict}

Examples

>>> # Use default UniProt parser
>>> sequences = parse_fasta("proteins.fasta")

>>> # Use NCBI parser
>>> sequences = parse_fasta("ncbi_proteins.fasta", header_parser=parse_ncbi_header)

>>> # Use simple parser
>>> sequences = parse_fasta("genes.fasta", header_parser=parse_simple_header)

>>> # Custom parser
>>> def my_parser(header):
...     return header.split('_')[0], {'full_header': header}
>>> sequences = parse_fasta("custom.fasta", header_parser=my_parser)
mutcleaner.utils.sequence_io.parse_ncbi_header(header)[source]#

Parse NCBI FASTA header to extract ID and metadata

Parameters:

header (str) – FASTA header line (without ‘>’)

Return type:

Tuple[str, Dict[str, str]]

Returns:

(sequence_id, metadata_dict)

Examples

>>> parse_ncbi_header("gi|123456|ref|NP_000001.1| protein description [Homo sapiens]")
('NP_000001.1', {'gi': '123456', 'db': 'ref', 'description': 'protein description [Homo sapiens]'})
>>> parse_ncbi_header("NP_000001.1 protein description")
('NP_000001.1', {'description': 'protein description'})
mutcleaner.utils.sequence_io.parse_simple_header(header)[source]#

Simple header parser that uses the first word as ID

Parameters:

header (str) – FASTA header line (without ‘>’)

Return type:

Tuple[str, Dict[str, str]]

Returns:

(sequence_id, metadata_dict)

Examples

>>> parse_simple_header("GENE1 some description text")
('GENE1', {'description': 'some description text'})
>>> parse_simple_header("GENE1")
('GENE1', {})
mutcleaner.utils.sequence_io.parse_uniprot_header(header)[source]#

Parse UniProt FASTA header to extract ID and metadata

Parameters:

header (str) – FASTA header line (without ‘>’)

Return type:

Tuple[str, Dict[str, str]]

Returns:

(sequence_id, metadata_dict)

Examples

>>> parse_uniprot_header("sp|P12345|PROT_HUMAN Protein description OS=Homo sapiens")
('P12345', {'db': 'sp', 'entry_name': 'PROT_HUMAN', 'description': 'Protein description OS=Homo sapiens'})
>>> parse_uniprot_header("P12345|PROT_HUMAN Description")
('P12345', {'entry_name': 'PROT_HUMAN', 'description': 'Description'})
>>> parse_uniprot_header("P12345")
('P12345', {})
mutcleaner.utils.sequence_io.write_fasta(sequences, file_path, wrap_length=60, header_formatter=None)[source]#

Write sequences to FASTA file

Parameters:

  • sequences (Union[Dict[str, str], Dict[str, Dict[str, Any]]]) – Dictionary mapping IDs to sequences or {‘sequence’: str, ‘metadata’: dict}

  • file_path (Union[str, Path]) – Output file path

  • wrap_length (int) – Line length for sequence wrapping (0 for no wrapping)

  • header_formatter (Optional[Callable[[str, Dict], str]]) – Function to format headers. Takes (id, metadata) and returns header string.

Return type:

None

Examples

>>> # Simple sequences
>>> seqs = {'GENE1': 'ACDEF', 'GENE2': 'KLMNO'}
>>> write_fasta(seqs, 'output.fasta')

>>> # With metadata
>>> seqs = {
...     'P12345': {
...         'sequence': 'ACDEF',
...         'metadata': {'description': 'Protein 1', 'organism': 'Human'}
...     }
... }
>>> write_fasta(seqs, 'output.fasta')