mutcleaner.cleaners.cdna_proteolysis_custom_cleaners#

Functions

validate_wt_sequence(dataset, name_column, ...)

Validate wild-type (WT) sequences per protein/name group by checking consistency between the explicit WT row (if present) and the WT sequence inferred from each mutant row.
mutcleaner.cleaners.cdna_proteolysis_custom_cleaners.validate_wt_sequence(dataset, name_column, mutation_column, sequence_column, wt_identifier='wt', num_workers=4)[source]#

Validate wild-type (WT) sequences per protein/name group by checking consistency between the explicit WT row (if present) and the WT sequence inferred from each mutant row. If the explicit WT row is missing, a new one is synthesized using the inferred sequence.

This step groups the dataset by name_column and, for each group:

  1. Reconstructs the WT sequence by inverting mutation sets from all mutant rows.

  2. If an explicit WT row is present (i.e., mutation_column == wt_identifier), ensures its sequence matches the consensus inferred WT sequence.

  3. If the explicit WT row is missing, synthesizes a new WT row with the inferred sequence and null experimental values.

  4. Fails the group if (a) multiple distinct inferred WT sequences are found, or (b) the inferred WT sequence does not match the explicit WT sequence. Otherwise, the group is marked as success.

Parallel execution is performed with joblib.Parallel(backend="loky") and a progress bar via tqdm. If parallel execution fails, a sequential fallback is used. Diagnostic warnings are printed with tqdm.write.

Parameters:

  • dataset (DataFrame) – Input dataframe containing at least the name, mutation, and sequence columns.

  • name_column (str) – Column that identifies a protein/name group for validation.

  • mutation_column (str) – Column containing mutation annotations. Its format must be parsable by MutationSet.from_string(sep=",", is_zero_based=True).

  • sequence_column (str) – Column containing the amino-acid sequence for that row (treated as the mutated sequence for mutants and the WT sequence for the WT row).

  • wt_identifier (str) – The exact token used in mutation_column to mark the explicit WT row.

  • num_workers (int) – Number of worker processes for parallel execution.

Return type:

Tuple[DataFrame, DataFrame]

Returns:

  • successful_df: Concatenation of original and synthesized rows for validated groups. Both mutant rows and the explicit (or synthesized) WT rows from successful groups are returned. May be empty if no group passes. - failed_df: Rows summarizing groups that failed validation. Each failed group is represented by at least one row with an additional column "error_message" describing the reason, e.g., multiple inferred WT sequences, or mismatch between inferred and explicit WT sequences. May be empty.

See also

validate_wt_sequence_grouped

The per-group worker that validates a single name/protein group.

Examples

>>> # Minimal schema example showing both explicit and synthesized WT cases:
>>> df = pd.DataFrame({
...     "protein": ["P1", "P1", "P1", "P2", "P2"],
...     "mut":     ["wt", "A0G", "L4F", "K3R", "M0A"],
...     "seq":     ["ACDELG", "GCDELG", "ACDEFG", "MNPRQ", "ANPKQ"],
... })
>>> successful, failed = validate_wt_sequence(
...     df, name_column="protein", mutation_column="mut", sequence_column="seq",
...     wt_identifier="wt", num_workers=2
... )
>>> successful
  protein  mut     seq
0      P1  A0G  GCDELG
1      P1  L4F  ACDEFG
2      P1   wt  ACDELG
3      P2  K3R  MNPRQ
4      P2  M0A  ANPKQ
5      P2   wt  MNPKQ