mutcleaner.core.dataset#

Classes

MutationDataset([name])

Dataset container for cleaned mutation data with multiple reference sequences.

class mutcleaner.core.dataset.MutationDataset(name=None)[source]#

Bases: object

Dataset container for cleaned mutation data with multiple reference sequences.

All mutation sets must be linked to a reference sequence when added to the dataset. This ensures data integrity and enables proper validation and analysis.

Methods

`add_mutation_set`(mutation_set, reference_id)	Add a mutation set to the dataset, linking to a reference sequence
`add_mutation_sets`(mutation_sets, reference_ids)	Add multiple mutation sets to the dataset
`add_reference_sequence`(sequence_id, sequence)	Add a reference sequence with a unique identifier
`convert_codon_to_amino_acid_sets`([...])	Convert all codon mutation sets to amino acid mutation sets
`filter_by_effect_type`(effect_type)	Filter dataset by amino acid mutation effect type (synonymous, missense, nonsense)
`filter_by_mutation_type`(mutation_type)	Filter dataset by mutation type
`filter_by_reference`(reference_id)	Filter dataset to only include mutation sets from a specific reference sequence
`from_dataframe`(df, reference_sequences[, ...])	Create a MutationDataset from a DataFrame containing mutation data.
`get_mutation_set_label`(mutation_set_index)	Get the label for a specific mutation set
`get_mutation_set_reference`(mutation_set_index)	Get the reference sequence ID for a specific mutation set
`get_position_coverage`([reference_id])	Get statistics about position coverage across reference sequences
`get_reference_sequence`(sequence_id)	Get a reference sequence by ID
`get_statistics`()	Get basic statistics about the dataset
`list_reference_sequences`()	Get list of all reference sequence IDs
`load`(filepath[, load_type])	Load a dataset from files.
`load_by_reference`(base_dir[, dataset_name, ...])	Load a dataset from mutcleaner reference-based format.
`remove_mutation_set`(mutation_set_index)	Remove a mutation set from the dataset
`remove_reference_sequence`(sequence_id)	Remove a reference sequence
`save`(filepath[, save_type])	Save the dataset to files.
`save_by_reference`(base_dir)	Save dataset by reference_id, creating separate folders for each reference.
`set_mutation_set_label`(mutation_set_index, label)	Set the label for a specific mutation set
`set_mutation_set_reference`(...)	Set the reference sequence for a specific mutation set
`to_dataframe`()	Convert dataset to pandas DataFrame
`validate_against_references`()	Validate mutations against their reference sequences

add_mutation_set(mutation_set, reference_id, label=None)[source]#: Add a mutation set to the dataset, linking to a reference sequence

add_mutation_sets(mutation_sets, reference_ids, labels=None)[source]#: Add multiple mutation sets to the dataset

add_reference_sequence(sequence_id, sequence)[source]#: Add a reference sequence with a unique identifier

convert_codon_to_amino_acid_sets(convert_labels=False)[source]#

Convert all codon mutation sets to amino acid mutation sets

Parameters:: convert_labels (bool) – Whether to save the labels with the mutation sets (default: False)
Return type:: MutationDataset

filter_by_effect_type(effect_type)[source]#

Filter dataset by amino acid mutation effect type (synonymous, missense, nonsense)

Return type:: MutationDataset

filter_by_mutation_type(mutation_type)[source]#

Filter dataset by mutation type

Return type:: MutationDataset

filter_by_reference(reference_id)[source]#

Filter dataset to only include mutation sets from a specific reference sequence

Return type:: MutationDataset

classmethod from_dataframe(df, reference_sequences, name=None, specific_mutation_type=None)[source]#

Create a MutationDataset from a DataFrame containing mutation data.

This method reconstructs a MutationDataset from a flattened DataFrame representation, typically used for loading saved mutation datasets from files. The DataFrame should contain mutation information with each row representing a single mutation within mutation sets.

Parameters:: df – DataFrame containing mutation data with the following required columns: - ‘mutation_set_id’: Identifier for grouping mutations into sets - ‘reference_id’: Identifier for the reference sequence - ‘mutation_string’: String representation of the mutation - ‘position’: Position of the mutation in the sequence - ‘mutation_type’: Type of mutation (‘amino_acid’, ‘codon_dna’, ‘codon_rna’)
Return type:: MutationDataset
Returns:: A new MutationDataset instance populated with the mutation sets and reference sequences from the DataFrame.
Raises:: ValueError – If the DataFrame is empty, missing required columns, or references sequences not provided in reference_sequences dict.

Notes

Mutations are grouped by ‘mutation_set_id’ to reconstruct mutation sets
The method automatically determines the appropriate mutation set type

(AminoAcidMutationSet, CodonMutationSet, or generic MutationSet) based on the mutation types within each set - Metadata is extracted from columns with ‘set_’ and ‘mutation_’ prefixes - Only reference sequences that are actually used in the DataFrame are added to the dataset

Examples

>>> import pandas as pd
>>> from sequences import ProteinSequence
>>>
>>> # Create sample DataFrame
>>> df = pd.DataFrame({
...     'mutation_set_id': ['set1', 'set1', 'set2'],
...     'reference_id': ['prot1', 'prot1', 'prot2'],
...     'mutation_string': ['A1V', 'L2P', 'G5R'],
...     'position': [1, 2, 5],
...     'mutation_type': ['amino_acid', 'amino_acid', 'amino_acid'],
...     'wild_amino_acid': ['A', 'L', 'G'],
...     'mutant_amino_acid': ['V', 'P', 'R'],
...     'mutation_set_name': ['variant1', 'variant1', 'variant2'],
...     'label': ['pathogenic', 'pathogenic', 'benign']
... })
>>>
>>> # Define reference sequences
>>> ref_seqs = {
...     'prot1': ProteinSequence('ALDEFG', name='protein1'),
...     'prot2': ProteinSequence('MKGLRK', name='protein2')
... }
>>>
>>> # Create MutationDataset
>>> dataset = MutationDataset.from_dataframe(df, ref_seqs, name="my_dataset")
>>> print(len(dataset.mutation_sets))
2

get_mutation_set_label(mutation_set_index)[source]#

Get the label for a specific mutation set

Return type:: Any

get_mutation_set_reference(mutation_set_index)[source]#

Get the reference sequence ID for a specific mutation set

Return type:: str

get_position_coverage(reference_id=None)[source]#

Get statistics about position coverage across reference sequences

Return type:: Dict[str, Any]

get_reference_sequence(sequence_id)[source]#

Get a reference sequence by ID

Return type:: BaseSequence

get_statistics()[source]#

Get basic statistics about the dataset

Return type:: Dict[str, Any]

list_reference_sequences()[source]#

Get list of all reference sequence IDs

Return type:: List[str]

classmethod load(filepath, load_type=None)[source]#

Load a dataset from files.

Parameters:

filepath (str) – Base filepath (with or without extension)
load_type (Optional[str]) – Type of load format (“mutcleaner”, “dataframe” or “pickle”). If None, auto-detect from file extension.

Return type:

MutationDataset

Returns:

Examples

>>> # Auto-detect from extension
>>> dataset = MutationDataset.load("my_study.csv")
>>> dataset = MutationDataset.load("my_study.pkl")

>>> # Explicit type
>>> dataset = MutationDataset.load("my_study", "dataframe")

classmethod load_by_reference(base_dir, dataset_name=None, is_zero_based=True)[source]#

Load a dataset from mutcleaner reference-based format.

Expected directory structure:

base_dir/
├── reference_id_1/
│   ├── data.csv
│   ├── wt.fasta
│   └── metadata.json
├── reference_id_2/
│   ├── data.csv
│   ├── wt.fasta
│   └── metadata.json
└── ...

Parameters:

base_dir (Union[str, Path]) – Base directory containing reference folders
dataset_name (Optional[str]) – Optional name for the loaded dataset
is_zero_based (bool) – Whether origin mutation positions are zero-based

Return type:

MutationDataset

Returns:

remove_mutation_set(mutation_set_index)[source]#: Remove a mutation set from the dataset

remove_reference_sequence(sequence_id)[source]#: Remove a reference sequence

save(filepath, save_type='mutcleaner')[source]#

Save the dataset to files.

Parameters:

filepath (str) – Base filepath (without extension)
save_type (Optional[Literal['mutcleaner', 'pickle', 'dataframe']]) – Type of save format (“mutcleaner”, “dataframe” or “pickle”)
save_type="dataframe": (For) –
- Saves mutations as {filepath}.csv - Saves reference sequences as {filepath}_refs.pkl - Saves metadata as {filepath}_meta.json
save_type="pickle": (For) –
- Saves entire dataset as {filepath}.pkl

Examples

>>> dataset.save("my_study", "dataframe")
>>> # Creates: my_study.csv, my_study_refs.pkl, my_study_meta.json

save_by_reference(base_dir)[source]#

Save dataset by reference_id, creating separate folders for each reference.

For each reference_id, creates:

{base_dir}/{reference_id}/data.csv: mutation data with columns [mutation_name, mutated_sequence, label]
{base_dir}/{reference_id}/wt.fasta: wild-type reference sequence
{base_dir}/{reference_id}/metadata.json: statistics and metadata for this reference

Parameters:: base_dir (Union[str, Path]) – Base directory to create reference folders in
Return type:: None

set_mutation_set_label(mutation_set_index, label)[source]#: Set the label for a specific mutation set

set_mutation_set_reference(mutation_set_index, reference_id)[source]#: Set the reference sequence for a specific mutation set

to_dataframe()[source]#

Convert dataset to pandas DataFrame

Return type:: DataFrame

validate_against_references()[source]#

Validate mutations against their reference sequences

Return type:: Dict[str, Any]