From 5e0fa4fa70838ded00b3e9568a089daf5903b8dc Mon Sep 17 00:00:00 2001 From: CAITLYN CHITWOOD Date: Tue, 12 May 2026 16:12:07 -0500 Subject: [PATCH 1/8] Add NO_DIFF_MARKER for explicit no-change representation in sequence comparisons. Remove fallback value and instead raise ValueError for pre-annotated parsing errors. Update related tests. --- sortscore/analysis/annotation.py | 29 +++++++++++++--------------- sortscore/utils/load_experiment.py | 30 ++++++++++++++++++----------- sortscore/utils/sequence_parsing.py | 4 +++- tests/unit/test_annotation.py | 30 ++++++++++++++++++++++++++--- tests/unit/test_sequence_parsing.py | 5 +++++ 5 files changed, 67 insertions(+), 31 deletions(-) create mode 100644 tests/unit/test_sequence_parsing.py diff --git a/sortscore/analysis/annotation.py b/sortscore/analysis/annotation.py index 265774c..191e73d 100644 --- a/sortscore/analysis/annotation.py +++ b/sortscore/analysis/annotation.py @@ -12,6 +12,9 @@ import pandas as pd from sortscore.utils.sequence_parsing import compare_to_reference, compare_codon_lists, translate_dna +NO_DIFF_MARKER = '=' + + # TODO: #37 redundant, see if we can remove def annotate_scores_dataframe( scores_df: pd.DataFrame, @@ -54,27 +57,24 @@ def annotate_scores_dataframe( # Add DNA sequence differences df['dna_seq_diff'] = df['variant_seq'].apply( - lambda x: compare_to_reference(wt_dna_seq, x) + lambda x: compare_to_reference(wt_dna_seq, x, no_change_marker=NO_DIFF_MARKER) ) - df['dna_seq_diff'] = df['dna_seq_diff'].fillna('') # Add AA sequence annotations only if not pre-annotated if not has_pre_annotated_aa: wt_aa_seq = translate_dna(wt_dna_seq) df['aa_seq'] = df['variant_seq'].apply(translate_dna) df['aa_seq_diff'] = df['aa_seq'].apply( - lambda x: compare_to_reference(wt_aa_seq, x) + lambda x: compare_to_reference(wt_aa_seq, x, no_change_marker=NO_DIFF_MARKER) ) - df['aa_seq_diff'] = df['aa_seq_diff'].fillna('') elif mutagenesis_type == 'aa': # For AA variants, add sequence differences only if not pre-annotated if not has_pre_annotated_aa: wt_aa_seq = translate_dna(wt_dna_seq) if len(wt_dna_seq) % 3 == 0 else wt_dna_seq df['aa_seq_diff'] = df['variant_seq'].apply( - lambda x: compare_to_reference(wt_aa_seq, x) + lambda x: compare_to_reference(wt_aa_seq, x, no_change_marker=NO_DIFF_MARKER) ) - df['aa_seq_diff'] = df['aa_seq_diff'].fillna('') # Map stop codon representations to * for standard notation in aa_seq_diff column if 'aa_seq_diff' in df.columns: @@ -114,32 +114,29 @@ def add_sequence_differences( if mutagenesis_type in {'codon', 'snv'}: # Add DNA sequence differences df['dna_seq_diff'] = df['variant_seq'].apply( - lambda x: compare_to_reference(wt_dna_seq, x) + lambda x: compare_to_reference(wt_dna_seq, x, no_change_marker=NO_DIFF_MARKER) ) - df['dna_seq_diff'] = df['dna_seq_diff'].fillna('') # Add AA sequence differences wt_aa_seq = translate_dna(wt_dna_seq) df['aa_seq'] = df['variant_seq'].apply(translate_dna) df['aa_seq_diff'] = df['aa_seq'].apply( - lambda x: compare_to_reference(wt_aa_seq, x) + lambda x: compare_to_reference(wt_aa_seq, x, no_change_marker=NO_DIFF_MARKER) ) - df['aa_seq_diff'] = df['aa_seq_diff'].fillna('') elif mutagenesis_type == 'aa': # For AA variants, sequences are already amino acids wt_aa_seq = translate_dna(wt_dna_seq) if len(wt_dna_seq) % 3 == 0 else wt_dna_seq df['aa_seq_diff'] = df['variant_seq'].apply( - lambda x: compare_to_reference(wt_aa_seq, x) + lambda x: compare_to_reference(wt_aa_seq, x, no_change_marker=NO_DIFF_MARKER) ) - df['aa_seq_diff'] = df['aa_seq_diff'].fillna('') return df def classify_aa_variant(aa_diff, dna_diff=None): - if not aa_diff or aa_diff == '': + if aa_diff == NO_DIFF_MARKER: # Check if this is true WT (no DNA changes) or synonymous (DNA changes but same AA) - if dna_diff is not None and (not dna_diff or dna_diff == ''): + if dna_diff == NO_DIFF_MARKER: return 'wt_dna' else: return 'synonymous' @@ -149,9 +146,9 @@ def classify_aa_variant(aa_diff, dna_diff=None): return 'missense_aa' def classify_dna_variant(dna_diff, aa_diff): - if not dna_diff or dna_diff == '': + if dna_diff == NO_DIFF_MARKER: return 'wt_dna' - elif not aa_diff or aa_diff == '': + elif aa_diff == NO_DIFF_MARKER: return 'synonymous' else: return 'missense_dna' diff --git a/sortscore/utils/load_experiment.py b/sortscore/utils/load_experiment.py index a9d026b..83abb0e 100644 --- a/sortscore/utils/load_experiment.py +++ b/sortscore/utils/load_experiment.py @@ -523,6 +523,7 @@ def _convert_aa_changes_to_annotations(self) -> None: This creates an aa_seq_diff column in the format 'ref.position.alt' for differences from the wild-type sequence, and uses the existing annotation function to determine annotation types. """ + from sortscore.analysis.annotation import NO_DIFF_MARKER from sortscore.utils.sequence_parsing import translate_dna # Get the wild-type AA sequence for annotation @@ -536,9 +537,9 @@ def _convert_aa_changes_to_annotations(self) -> None: try: ref_aa, position, alt_aa = parse_aa_change(variant_seq) except ValueError: - # If parsing fails, treat as empty difference - aa_seq_diffs.append('') - continue + raise ValueError( + f"Invalid pre-annotated amino-acid variant: '{variant_seq}'." + ) # Verify the reference AA matches the WT sequence if not (1 <= position <= len(wt_aa_seq)): @@ -557,8 +558,8 @@ def _convert_aa_changes_to_annotations(self) -> None: aa_seq_diff = f"{ref_aa}.{position}.{alt_aa}" aa_seq_diffs.append(aa_seq_diff) else: - # No difference (e.g., M1M) - aa_seq_diffs.append('') + # Mark no-change variants explicitly. + aa_seq_diffs.append(NO_DIFF_MARKER) # Add the aa_seq_diff column df['aa_seq_diff'] = aa_seq_diffs @@ -626,6 +627,7 @@ def annotate_variants(self, df, wt_ref_seq: str, wt_aa_seq: str, mutagenesis_typ mutagenesis_type : str 'aa' for amino acid variants, 'codon' for multiple nucleotide changes in single frame, 'snv' for single nucleotide variants. """ + from sortscore.analysis.annotation import NO_DIFF_MARKER from sortscore.utils.sequence_parsing import compare_to_reference, translate_dna # AA annotation @@ -635,13 +637,19 @@ def annotate_variants(self, df, wt_ref_seq: str, wt_aa_seq: str, mutagenesis_typ elif mutagenesis_type in {'codon', 'snv'}: df['aa_seq'] = df['variant_seq'].apply(translate_dna) # Translate DNA to AA # DNA annotation - df['dna_seq_diff'] = df['variant_seq'].apply(lambda x: compare_to_reference(wt_ref_seq, x)) - df['dna_seq_diff'] = df['dna_seq_diff'].fillna('') - df['dna_diff_count'] = df['dna_seq_diff'].apply(lambda x: 0 if not x else x.count(',') + 1) + df['dna_seq_diff'] = df['variant_seq'].apply( + lambda x: compare_to_reference(wt_ref_seq, x, no_change_marker=NO_DIFF_MARKER) + ) + df['dna_diff_count'] = df['dna_seq_diff'].apply( + lambda x: 0 if x == NO_DIFF_MARKER else x.count(',') + 1 + ) - df['aa_seq_diff'] = df['aa_seq'].apply(lambda x: compare_to_reference(wt_aa_seq, x)) - df['aa_seq_diff'] = df['aa_seq_diff'].fillna('') - df['aa_diff_count'] = df['aa_seq_diff'].apply(lambda x: 0 if not x else x.count(',') + 1) + df['aa_seq_diff'] = df['aa_seq'].apply( + lambda x: compare_to_reference(wt_aa_seq, x, no_change_marker=NO_DIFF_MARKER) + ) + df['aa_diff_count'] = df['aa_seq_diff'].apply( + lambda x: 0 if x == NO_DIFF_MARKER else x.count(',') + 1 + ) def _validate_mutagenesis_type_against_counts(self) -> None: """ diff --git a/sortscore/utils/sequence_parsing.py b/sortscore/utils/sequence_parsing.py index 439956e..11a82bf 100644 --- a/sortscore/utils/sequence_parsing.py +++ b/sortscore/utils/sequence_parsing.py @@ -146,7 +146,7 @@ def translate_dna(dna_sequence: str) -> str: dna_seq = Seq(dna_sequence) return str(dna_seq.translate()) -def compare_to_reference(ref_seq: str, sequence: str) -> str: +def compare_to_reference(ref_seq: str, sequence: str, no_change_marker: str = '') -> str: """ Compare a protein sequence to a reference and report differences. @@ -181,6 +181,8 @@ def compare_to_reference(ref_seq: str, sequence: str) -> str: var_aa = '*' if sequence[i] == 'X' else sequence[i] difference = f'{ref_aa}.{i+1}.{var_aa}' differences.append(difference) + if not differences: + return no_change_marker return ', '.join(differences) def get_codons(dna_seq: str) -> List[str]: diff --git a/tests/unit/test_annotation.py b/tests/unit/test_annotation.py index 0ea0c7f..6d99afc 100644 --- a/tests/unit/test_annotation.py +++ b/tests/unit/test_annotation.py @@ -1,6 +1,8 @@ import pandas as pd +import pytest from sortscore.analysis.annotation import annotate_scores_dataframe +from sortscore.utils.load_experiment import ExperimentConfig def test_annotate_scores_dataframe_supports_codon_mutagenesis_type(): @@ -22,8 +24,8 @@ def test_annotate_scores_dataframe_supports_codon_mutagenesis_type(): assert "annotate_dna" in annotated.columns assert "annotate_aa" in annotated.columns - assert annotated.loc[0, "aa_seq_diff"] == "" - assert annotated.loc[0, "dna_seq_diff"] == "" + assert annotated.loc[0, "aa_seq_diff"] == "=" + assert annotated.loc[0, "dna_seq_diff"] == "=" assert annotated.loc[0, "annotate_dna"] == "wt_dna" assert annotated.loc[0, "annotate_aa"] == "wt_dna" @@ -31,7 +33,29 @@ def test_annotate_scores_dataframe_supports_codon_mutagenesis_type(): assert annotated.loc[1, "annotate_dna"] == "missense_dna" assert annotated.loc[1, "annotate_aa"] == "missense_aa" - assert annotated.loc[2, "aa_seq_diff"] == "" + assert annotated.loc[2, "aa_seq_diff"] == "=" assert annotated.loc[2, "dna_seq_diff"] != "" assert annotated.loc[2, "annotate_dna"] == "synonymous" assert annotated.loc[2, "annotate_aa"] == "synonymous" + + +def test_preannotated_aa_parse_errors_raise_value_error(): + config = ExperimentConfig( + experiment_name="exp", + experiment_setup_file="unused.csv", + wt_seq="ATGGCC", # MA + mutagenesis_type="aa", + ) + config.counts = { + 1: { + 1: pd.DataFrame( + { + "variant_seq": ["M1M", "not-a-variant"], + "count": [1, 1], + } + ) + } + } + + with pytest.raises(ValueError, match="Invalid pre-annotated amino-acid variant"): + config._convert_aa_changes_to_annotations() diff --git a/tests/unit/test_sequence_parsing.py b/tests/unit/test_sequence_parsing.py new file mode 100644 index 0000000..0ffde8a --- /dev/null +++ b/tests/unit/test_sequence_parsing.py @@ -0,0 +1,5 @@ +from sortscore.utils.sequence_parsing import compare_to_reference + + +def test_compare_to_reference_returns_explicit_no_diff_marker(): + assert compare_to_reference("MA", "MA", no_change_marker="=") == "=" From 846a431b2801d762c099829cca21f301ee87d6c5 Mon Sep 17 00:00:00 2001 From: CAITLYN CHITWOOD Date: Tue, 12 May 2026 16:31:21 -0500 Subject: [PATCH 2/8] Add unit tests to ensure retention of synonymous rows in AA score tables --- tests/unit/test_aa_scores.py | 49 ++++++++++++++++++++++++++++++++++++ 1 file changed, 49 insertions(+) create mode 100644 tests/unit/test_aa_scores.py diff --git a/tests/unit/test_aa_scores.py b/tests/unit/test_aa_scores.py new file mode 100644 index 0000000..dd749f0 --- /dev/null +++ b/tests/unit/test_aa_scores.py @@ -0,0 +1,49 @@ +import pandas as pd + +from sortscore.analysis.aa_scores import build_aa_scores_table +from sortscore.analysis.variant_aggregation import aggregate_aa_data + + +def assert_synonymous_no_diff_group_retained(df: pd.DataFrame, score_col: str = "avgscore") -> None: + """Assert that synonymous no-diff rows collapse into a single retained AA group.""" + assert set(df["aa_seq_diff"]) == {"=", "A.2.S"} + syn_rows = df[ + (df["aa_seq_diff"] == "=") & + (df["annotate_aa"] == "synonymous") + ] + assert len(syn_rows) == 1 + syn_row = syn_rows.iloc[0] + assert syn_row[score_col] == 12.0 + return syn_row + + +def test_build_aa_scores_table_retains_synonymous_no_diff_rows(): + scores_df = pd.DataFrame( + { + "aa_seq_diff": ["=", "=", "A.2.S"], + "annotate_aa": ["synonymous", "synonymous", "missense_aa"], + "avgscore": [10.0, 14.0, 30.0], + "avgscore_rep_weighted": [11.0, 15.0, 31.0], + } + ) + + aa_scores = build_aa_scores_table(scores_df, "avgscore") + + # The two synonymous input rows should collapse into one retained no-diff AA row. + syn_row = assert_synonymous_no_diff_group_retained(aa_scores) + assert syn_row["avgscore_rep_weighted"] == 13.0 + + +def test_aggregate_aa_data_retains_synonymous_no_diff_rows(): + scores_df = pd.DataFrame( + { + "aa_seq_diff": ["=", "=", "A.2.S"], + "annotate_aa": ["synonymous", "synonymous", "missense_aa"], + "avgscore": [10.0, 14.0, 30.0], + } + ) + + aa_data = aggregate_aa_data(scores_df, "avgscore") + + # AA aggregation should keep the synonymous no-diff group instead of dropping it. + assert_synonymous_no_diff_group_retained(aa_data) From 743a42a4aff30e6b9542be6d4896f811eb26e270 Mon Sep 17 00:00:00 2001 From: CAITLYN CHITWOOD Date: Wed, 13 May 2026 00:33:38 -0500 Subject: [PATCH 3/8] Refactor output directory structure in batch normalization --- docs/batch_processing.md | 6 +++--- sortscore/analysis/batch_normalization.py | 4 +++- tests/unit/test_batch_normalization.py | 2 +- 3 files changed, 7 insertions(+), 5 deletions(-) diff --git a/docs/batch_processing.md b/docs/batch_processing.md index 865325a..966d5e1 100644 --- a/docs/batch_processing.md +++ b/docs/batch_processing.md @@ -152,9 +152,9 @@ Specify your own list of pathogenic control variants. Batch processing generates: ### Score Files -- `batch_scores.csv`: Combined normalized scores with batch tracking -- `batch_aa_scores.csv`: Combined amino acid level normalized scores when AA aggregation is available -- `batch_stats.json`: Comprehensive statistics and normalization factors +- `/normalized//scores/batch_scores.csv`: Combined normalized scores with batch tracking +- `/normalized//scores/batch_aa_scores.csv`: Combined amino acid level normalized scores when AA aggregation is available +- `/normalized//scores/batch_stats.json`: Statistics and normalization factors ### Visualizations - Unified scaling: Single colorbar applies to all data diff --git a/sortscore/analysis/batch_normalization.py b/sortscore/analysis/batch_normalization.py index eaeb809..9f7ef31 100644 --- a/sortscore/analysis/batch_normalization.py +++ b/sortscore/analysis/batch_normalization.py @@ -157,7 +157,7 @@ def run_batch_analysis(batch_config: Dict[str, Any]) -> Dict[str, Any]: method = batch_config.get('batch_normalization_method', 'zscore_2pole') pathogenic_control_type = batch_config.get('pathogenic_control_type', 'nonsense') pathogenic_variants = batch_config.get('pathogenic_variants', None) - output_dir = str(Path(str(batch_config.get('combined_output_dir', '.'))).expanduser().resolve()) + base_output_dir = Path(str(batch_config.get('combined_output_dir', '.'))).expanduser().resolve() # Load all tile score tables from batch config entries. experiments = [] @@ -214,6 +214,8 @@ def run_batch_analysis(batch_config: Dict[str, Any]) -> Dict[str, Any]: else: raise ValueError(f"Unknown normalization method: {method}") + output_dir = str((base_output_dir / 'normalized' / method).resolve()) + logger.info(f"Applied {method} normalization to {len(normalized_scores)} variants") normalized_aa_scores = _build_batch_aa_scores(normalized_scores, experiments) diff --git a/tests/unit/test_batch_normalization.py b/tests/unit/test_batch_normalization.py index 5aa0a39..93da93c 100644 --- a/tests/unit/test_batch_normalization.py +++ b/tests/unit/test_batch_normalization.py @@ -8,7 +8,7 @@ def test_save_batch_results_preserves_decimal_score_precision(tmp_path): - output_dir = Path(tmp_path) + output_dir = Path(tmp_path) / "normalized" / "zscore_2pole" normalized_scores = pd.DataFrame( { "variant_seq": ["AAA"], From 4bc0823da6c27a824f1a8c6383ac40e26a414305 Mon Sep 17 00:00:00 2001 From: CAITLYN CHITWOOD Date: Wed, 13 May 2026 01:19:30 -0500 Subject: [PATCH 4/8] Refactor summary stats calculation and add unit tests --- sortscore/analysis/summary_stats.py | 109 +++++++++++++--------------- tests/unit/test_summary_stats.py | 28 +++++++ 2 files changed, 77 insertions(+), 60 deletions(-) create mode 100644 tests/unit/test_summary_stats.py diff --git a/sortscore/analysis/summary_stats.py b/sortscore/analysis/summary_stats.py index f9fe69e..1d3621e 100644 --- a/sortscore/analysis/summary_stats.py +++ b/sortscore/analysis/summary_stats.py @@ -1,7 +1,7 @@ """ Summary stats calculation and export for Sort-seq analysis. -This module provides functions for calculating comprehensive summary stats +This module provides functions for calculating summary stats from Sort-seq variant analysis results and saving them to JSON format. """ import json @@ -11,10 +11,23 @@ from typing import Dict, Any, Optional from sortscore.analysis.variant_aggregation import aggregate_synonymous_variants +def _summarize_subset(df: pd.DataFrame, score_col: str) -> Optional[Dict[str, Any]]: + if score_col not in df.columns or df.empty: + return None + scores = pd.to_numeric(df[score_col], errors='coerce').dropna() + if scores.empty: + return None + return { + 'avg': round(float(scores.mean())), + 'min': round(float(scores.min())), + 'max': round(float(scores.max())), + } + + # TODO: #47 Separate DNA-level and AA-level stats into different functions or modes def calculate_summary_stats(scores_df: pd.DataFrame, experiment, score_col: Optional[str] = None) -> Dict[str, Any]: """ - Calculate comprehensive summary stats from variant scores. + Calculate summary stats from variant scores. This function computes stats for different variant categories including overall stats, wild-type scores, synonymous variants, nonsense variants, @@ -39,7 +52,7 @@ def calculate_summary_stats(scores_df: pd.DataFrame, experiment, score_col: Opti >>> stats = calculate_summary_stats(scores_df, experiment) >>> print(stats['all_avg']) # Overall average score """ - stats = {} + stats: Dict[str, Any] = {} # Determine score column if not provided if score_col is None: @@ -52,67 +65,43 @@ def calculate_summary_stats(scores_df: pd.DataFrame, experiment, score_col: Opti if score_col not in scores_df.columns: logging.warning(f"Score column '{score_col}' not found in data") return stats - - # Overall stats - mean_val = scores_df[score_col].mean() - min_val = scores_df[score_col].min() - max_val = scores_df[score_col].max() - stats['all_avg'] = round(float(mean_val)) if pd.notna(mean_val) else None - stats['all_min'] = round(float(min_val)) if pd.notna(min_val) else None - stats['all_max'] = round(float(max_val)) if pd.notna(max_val) else None - + + overall_summary = _summarize_subset(scores_df, score_col) + if overall_summary is not None: + stats['overall'] = overall_summary + # Add annotation-based stats if available if 'annotate_dna' in scores_df.columns: - # WT stats from DNA level wt_subset = scores_df[scores_df['annotate_dna'] == 'wt_dna'] - if len(wt_subset) > 0: - stats['wt_dna'] = round(float(mean_val)) if pd.notna(mean_val) else None - - # Synonymous (WT) stats from DNA level - syn_subset = scores_df[scores_df['annotate_dna'] == 'synonymous'] - if len(syn_subset) > 0: - mean_val = syn_subset[score_col].mean() - min_val = syn_subset[score_col].min() - max_val = syn_subset[score_col].max() - stats['synonymous_wt_avg'] = round(float(mean_val)) if pd.notna(mean_val) else None - stats['synonymous_wt_min'] = round(float(min_val)) if pd.notna(min_val) else None - stats['synonymous_wt_max'] = round(float(max_val)) if pd.notna(max_val) else None - - # Missense and nonsense: use AA-aggregated scores with annotate_aa - if 'aa_seq_diff' in scores_df.columns: + wt_summary = _summarize_subset(wt_subset, score_col) + + synonymous_wt_subset = scores_df[scores_df['annotate_dna'] == 'synonymous'] + synonymous_wt_summary = _summarize_subset(synonymous_wt_subset, score_col) + + if wt_summary is not None: + stats['wt'] = wt_summary + if synonymous_wt_summary is not None: + stats['synonymous_wt'] = synonymous_wt_summary + + # Summarize AA-level categories from the file being described. + aa_scores: Optional[pd.DataFrame] = None + if 'dna_seq_diff' in scores_df.columns and 'aa_seq_diff' in scores_df.columns: aa_scores = aggregate_synonymous_variants(scores_df) - if score_col in aa_scores.columns: - # Synonymous stats from AA level (aggregated synonymous variants) - syn_aa_subset = aa_scores[aa_scores['annotate_aa'] == 'synonymous'] - if len(syn_aa_subset) > 0: - mean_val = syn_aa_subset[score_col].mean() - min_val = syn_aa_subset[score_col].min() - max_val = syn_aa_subset[score_col].max() - #TODO: #47 This currently gets added to DNA stats - stats['syn_avg'] = round(float(mean_val)) if pd.notna(mean_val) else None - stats['syn_min'] = round(float(min_val)) if pd.notna(min_val) else None - stats['syn_max'] = round(float(max_val)) if pd.notna(max_val) else None - - # Nonsense stats from AA level - nonsense_subset = aa_scores[aa_scores['annotate_aa'] == 'nonsense'] - if len(nonsense_subset) > 0: - mean_val = nonsense_subset[score_col].mean() - min_val = nonsense_subset[score_col].min() - max_val = nonsense_subset[score_col].max() - stats['nonsense_avg'] = round(float(mean_val)) if pd.notna(mean_val) else None - stats['nonsense_min'] = round(float(min_val)) if pd.notna(min_val) else None - stats['nonsense_max'] = round(float(max_val)) if pd.notna(max_val) else None - - # Missense stats from AA level - missense_subset = aa_scores[aa_scores['annotate_aa'] == 'missense_aa'] - if len(missense_subset) > 0: - mean_val = missense_subset[score_col].mean() - min_val = missense_subset[score_col].min() - max_val = missense_subset[score_col].max() - stats['missense_avg'] = round(float(mean_val)) if pd.notna(mean_val) else None - stats['missense_min'] = round(float(min_val)) if pd.notna(min_val) else None - stats['missense_max'] = round(float(max_val)) if pd.notna(max_val) else None - + elif 'annotate_aa' in scores_df.columns: + aa_scores = scores_df + + if aa_scores is not None and score_col in aa_scores.columns: + nonsense_subset = aa_scores[aa_scores['annotate_aa'] == 'nonsense'] + nonsense_summary = _summarize_subset(nonsense_subset, score_col) + + missense_subset = aa_scores[aa_scores['annotate_aa'] == 'missense_aa'] + missense_summary = _summarize_subset(missense_subset, score_col) + + if nonsense_summary is not None: + stats['nonsense'] = nonsense_summary + if missense_summary is not None: + stats['missense'] = missense_summary + return stats diff --git a/tests/unit/test_summary_stats.py b/tests/unit/test_summary_stats.py new file mode 100644 index 0000000..cb5be31 --- /dev/null +++ b/tests/unit/test_summary_stats.py @@ -0,0 +1,28 @@ +from types import SimpleNamespace + +import pandas as pd + +from sortscore.analysis.summary_stats import calculate_summary_stats + + +def test_calculate_summary_stats_returns_flat_sections(): + scores_df = pd.DataFrame( + { + "aa_seq_diff": ["=", "A.2.S", "Q.3.*"], + "annotate_aa": ["synonymous", "missense_aa", "nonsense"], + "annotate_dna": ["synonymous", "missense_dna", "missense_dna"], + "avgscore": [10.0, 20.0, 5.0], + "avgscore_rep_weighted": [11.0, 21.0, 6.0], + } + ) + + stats = calculate_summary_stats( + scores_df, + SimpleNamespace(avg_method="simple-avg"), + score_col="avgscore", + ) + + assert stats["overall"] == {"avg": 12, "min": 5, "max": 20} + assert stats["synonymous_wt"] == {"avg": 10, "min": 10, "max": 10} + assert stats["missense"] == {"avg": 20, "min": 20, "max": 20} + assert stats["nonsense"] == {"avg": 5, "min": 5, "max": 5} From 1b6bc8951f68c6aae0eb5ded5a7bbe098eb82532 Mon Sep 17 00:00:00 2001 From: CAITLYN CHITWOOD Date: Wed, 13 May 2026 14:03:14 -0500 Subject: [PATCH 5/8] Refactor batch normalization stats summary output and update related tests --- sortscore/analysis/batch_normalization.py | 195 +++++++++++++++------- sortscore/analysis/summary_stats.py | 24 +-- sortscore/analysis/workflows.py | 8 +- tests/unit/test_batch_normalization.py | 96 ++++++++++- tests/unit/test_summary_stats.py | 5 +- 5 files changed, 244 insertions(+), 84 deletions(-) diff --git a/sortscore/analysis/batch_normalization.py b/sortscore/analysis/batch_normalization.py index 9f7ef31..b2ec5f3 100644 --- a/sortscore/analysis/batch_normalization.py +++ b/sortscore/analysis/batch_normalization.py @@ -27,6 +27,7 @@ logger = logging.getLogger(__name__) from sortscore.analysis.aa_scores import _get_score_column_from_avg_method, build_aa_scores_table +from sortscore.analysis.summary_stats import calculate_summary_stats def _ensure_avgscore_column(scores_df: pd.DataFrame) -> pd.DataFrame: @@ -95,6 +96,90 @@ def _build_batch_aa_scores( return pd.concat(aa_batch_frames, ignore_index=True) +def _build_stage_section( + *, + global_values: Optional[Dict[str, Any]] = None, + tile_values: Optional[Dict[str, Dict[str, Any]]] = None, + factor_values: Optional[Dict[str, float]] = None, + factor_key: str = 'normalization_factor', +) -> Dict[str, Any]: + stage: Dict[str, Any] = {} + if global_values: + stage['global'] = dict(global_values) + + tile_keys = set() + if tile_values: + tile_keys.update(tile_values.keys()) + if factor_values: + tile_keys.update(factor_values.keys()) + + for batch_key in sorted(tile_keys): + tile_stats: Dict[str, Any] = {} + if tile_values and batch_key in tile_values: + tile_stats.update(tile_values[batch_key]) + if factor_values and batch_key in factor_values: + tile_stats[factor_key] = factor_values[batch_key] + stage[batch_key] = tile_stats + + return stage + + +def _build_final_batch_stats(normalized_scores: pd.DataFrame) -> Dict[str, Any]: + """Create final stats for global and per-tile normalized outputs.""" + final_stats: Dict[str, Any] = { + 'global': calculate_summary_stats(normalized_scores, 'avgscore'), + } + for batch_name, batch_df in normalized_scores.groupby('batch'): + final_stats[cast(str, batch_name)] = calculate_summary_stats( + batch_df, + 'avgscore', + ) + return final_stats + + +def _build_normalization_stats( + *, + raw_tile_values: Optional[Dict[str, Dict[str, Any]]] = None, + raw_global_values: Optional[Dict[str, Any]] = None, + wt_stage_global_values: Optional[Dict[str, Any]] = None, + zscore_tile_values: Optional[Dict[str, Dict[str, Any]]] = None, + zscore_global_values: Optional[Dict[str, Any]] = None, + final_scores: pd.DataFrame, + wt_factors: Optional[Dict[str, float]] = None, + path_factors: Optional[Dict[str, float]] = None, + normalization_factors: Optional[Dict[str, float]] = None, +) -> Dict[str, Any]: + stats: Dict[str, Any] = {} + + stats['raw'] = _build_stage_section( + global_values=raw_global_values, + tile_values=raw_tile_values, + ) + + if wt_stage_global_values is not None or wt_factors is not None: + stats['wt_alignment'] = _build_stage_section( + global_values=wt_stage_global_values, + factor_values=wt_factors, + ) + + if zscore_global_values is not None or zscore_tile_values is not None or path_factors is not None: + stats['zscore'] = _build_stage_section( + global_values=zscore_global_values, + tile_values=zscore_tile_values, + factor_values=path_factors, + factor_key='pathogenic_normalization_factor', + ) + + if normalization_factors is not None: + scaling_stage = {'per_tile': {}} + for batch_name, factor in normalization_factors.items(): + scaling_stage['per_tile'][batch_name] = {'normalization_factor': factor} + stats['scaling'] = scaling_stage + + stats['final'] = _build_final_batch_stats(final_scores) + return stats + + def _load_scores_from_output_dir(output_dir: str) -> pd.DataFrame: """Load best available score CSV from `output_dir/scores`.""" scores_dir = Path(output_dir).expanduser().resolve() / 'scores' @@ -390,23 +475,21 @@ def apply_2pole_normalization( normalized_scores.loc[batch_mask, col] * factor ) - # Create combined statistics - combined_stats = { - 'syn_median_global_raw': A, - 'non_median_global_raw': C, - 'normalization_method': '2pole', - 'pathogenic_control_type': pathogenic_control_type - } - - # Add experiment-specific stats and factors - for exp_name, stats in all_stats.items(): - combined_stats[f'syn_median_{exp_name}_raw'] = stats.get('syn_median', np.nan) - combined_stats[f'non_avg_{exp_name}_raw'] = stats.get('non_avg', np.nan) - combined_stats[f'normalization_factor_{exp_name}'] = normalization_factors.get(exp_name, 1.0) - - # Recalculate final statistics from normalized data - final_stats = recalculate_final_statistics(normalized_scores, 'avgscore') - combined_stats.update(final_stats) + combined_stats = _build_normalization_stats( + raw_tile_values={ + batch_name: { + 'syn_median': stats.get('syn_median'), + 'non_avg': stats.get('non_avg'), + } + for batch_name, stats in all_stats.items() + }, + raw_global_values={ + 'syn_median': A, + 'pathogenic_median': C, + }, + final_scores=normalized_scores, + normalization_factors=normalization_factors, + ) logger.info(f"2-pole normalization complete with factors: {normalization_factors}") return normalized_scores, combined_stats @@ -539,28 +622,22 @@ def apply_zscore_2pole_normalization( final_scores.loc[batch_mask, col] * factor ) - # Create combined statistics - combined_stats = { - 'wt_dna_score_global_raw': A, - 'syn_mean_global_zscore': syn_mean, - 'syn_std_global_zscore': syn_std, - 'non_avg_global_zscore_z': C, - 'normalization_method': 'zscore_2pole', - 'pathogenic_control_type': pathogenic_control_type - } - - # Add experiment-specific stats and factors - for exp_name, stats in all_stats.items(): - combined_stats[f'wt_dna_score_{exp_name}_raw'] = stats.get('wt_dna_score', np.nan) - combined_stats[f'normalization_factor_wt_{exp_name}'] = wt_normalization_factors.get(exp_name, 1.0) - - for exp_name, stats in zscore_stats.items(): - combined_stats[f'non_avg_{exp_name}_zscore_z'] = stats.get('non_avg_zscore', np.nan) - combined_stats[f'normalization_factor_path_{exp_name}'] = path_normalization_factors.get(exp_name, 1.0) - - # Recalculate final statistics from normalized data - final_stats = recalculate_final_statistics(final_scores, 'avgscore') - combined_stats.update(final_stats) + combined_stats = _build_normalization_stats( + raw_tile_values={ + batch_name: {'wt_dna_score': stats.get('wt_dna_score')} + for batch_name, stats in all_stats.items() + }, + raw_global_values={'wt_dna_score': A}, + wt_stage_global_values={ + 'syn_mean': syn_mean, + 'syn_std': syn_std, + }, + zscore_tile_values=zscore_stats, + zscore_global_values={'non_avg_zscore': C}, + final_scores=final_scores, + wt_factors=wt_normalization_factors, + path_factors=path_normalization_factors, + ) logger.info("Z-score 2-pole normalization complete") return final_scores, combined_stats @@ -686,26 +763,26 @@ def apply_zscore_center_normalization( if col in final_scores.columns and syn_std != 0: final_scores[col] = (final_scores[col] - syn_mean) / syn_std - # Create combined statistics (no pathogenic control type since not used) - combined_stats = { - f'{reference_type}_score_global_raw': global_reference_avg, - 'syn_mean_global_ref_norm': syn_mean, - 'syn_std_global_ref_norm': syn_std, - 'normalization_method': 'zscore_center', - 'reference_type': reference_type - } - - # Add experiment-specific stats and factors - for exp_name, stats in all_stats.items(): - if reference_type == 'wt_dna': - combined_stats[f'wt_dna_score_{exp_name}_raw'] = stats.get('wt_dna_score', np.nan) - else: - combined_stats[f'syn_median_{exp_name}_raw'] = stats.get('syn_median', np.nan) - combined_stats[f'normalization_factor_{exp_name}'] = normalization_factors.get(exp_name, 1.0) - - # Recalculate final statistics from normalized data - final_stats = recalculate_final_statistics(final_scores, 'avgscore') - combined_stats.update(final_stats) + combined_stats = _build_normalization_stats( + raw_tile_values={ + batch_name: ( + {'wt_dna_score': stats.get('wt_dna_score')} + if reference_type == 'wt_dna' + else {'syn_median': stats.get('syn_median')} + ) + for batch_name, stats in all_stats.items() + }, + raw_global_values={ + 'reference_type': reference_type, + 'reference_avg': global_reference_avg, + }, + wt_stage_global_values={ + 'syn_mean': syn_mean, + 'syn_std': syn_std, + }, + final_scores=final_scores, + normalization_factors=normalization_factors, + ) logger.info("Z-score centering normalization complete") return final_scores, combined_stats diff --git a/sortscore/analysis/summary_stats.py b/sortscore/analysis/summary_stats.py index 1d3621e..8b8f8f8 100644 --- a/sortscore/analysis/summary_stats.py +++ b/sortscore/analysis/summary_stats.py @@ -25,7 +25,7 @@ def _summarize_subset(df: pd.DataFrame, score_col: str) -> Optional[Dict[str, An # TODO: #47 Separate DNA-level and AA-level stats into different functions or modes -def calculate_summary_stats(scores_df: pd.DataFrame, experiment, score_col: Optional[str] = None) -> Dict[str, Any]: +def calculate_summary_stats(scores_df: pd.DataFrame, score_col: str) -> Dict[str, Any]: """ Calculate summary stats from variant scores. @@ -37,10 +37,8 @@ def calculate_summary_stats(scores_df: pd.DataFrame, experiment, score_col: Opti ---------- scores_df : pd.DataFrame DataFrame containing variant scores and annotations - experiment : ExperimentConfig - Experiment configuration containing metadata - score_col : Optional[str] - Score column name to use. If None, determined from experiment.avg_method + score_col : str + Score column name to use. Returns ------- @@ -49,19 +47,11 @@ def calculate_summary_stats(scores_df: pd.DataFrame, experiment, score_col: Opti Examples -------- - >>> stats = calculate_summary_stats(scores_df, experiment) - >>> print(stats['all_avg']) # Overall average score + >>> stats = calculate_summary_stats(scores_df, 'avgscore') + >>> print(stats['overall']) """ stats: Dict[str, Any] = {} - - # Determine score column if not provided - if score_col is None: - if experiment.avg_method == 'simple-avg': - score_col = 'avgscore' - else: - score_col_suffix = experiment.avg_method.replace('-', '_') - score_col = f'avgscore_{score_col_suffix}' - + if score_col not in scores_df.columns: logging.warning(f"Score column '{score_col}' not found in data") return stats @@ -144,7 +134,7 @@ def save_summary_stats( Examples -------- - >>> stats = calculate_summary_stats(scores_df, experiment) + >>> stats = calculate_summary_stats(scores_df, 'avgscore') >>> stats_file = save_summary_stats(stats, experiment, 'output/scores', logger) """ stats_file = os.path.join(scores_dir, f"{experiment.experiment_name}_{stats_basename}.json") diff --git a/sortscore/analysis/workflows.py b/sortscore/analysis/workflows.py index 13205a2..6cc5d2b 100644 --- a/sortscore/analysis/workflows.py +++ b/sortscore/analysis/workflows.py @@ -13,7 +13,7 @@ from sortscore.analysis.variant_aggregation import aggregate_synonymous_variants from sortscore.analysis.statistics import calculate_replicate_statistics, round_score_columns, get_replicate_score_columns from sortscore.analysis.summary_stats import calculate_summary_stats, save_summary_stats -from sortscore.analysis.aa_scores import process_and_save_aa_scores +from sortscore.analysis.aa_scores import _get_score_column_from_avg_method, process_and_save_aa_scores def calculate_variant_scores(experiment, merged_df: pd.DataFrame) -> pd.DataFrame: @@ -109,7 +109,8 @@ def process_dna_workflow(experiment, output_dir: str, analysis_logger) -> Option ) # Calculate and save statistics on the final processed DNA data - stats = calculate_summary_stats(scores_df_rounded, experiment) + score_col = _get_score_column_from_avg_method(experiment.avg_method) + stats = calculate_summary_stats(scores_df_rounded, score_col) save_summary_stats( stats, experiment, @@ -184,7 +185,8 @@ def process_aa_workflow(experiment, output_dir: str, analysis_logger, if os.path.exists(aa_scores_file): final_scores_df = pd.read_csv(aa_scores_file) - stats = calculate_summary_stats(final_scores_df, experiment) + score_col = _get_score_column_from_avg_method(experiment.avg_method) + stats = calculate_summary_stats(final_scores_df, score_col) save_summary_stats( stats, experiment, diff --git a/tests/unit/test_batch_normalization.py b/tests/unit/test_batch_normalization.py index 93da93c..4a5d12a 100644 --- a/tests/unit/test_batch_normalization.py +++ b/tests/unit/test_batch_normalization.py @@ -4,7 +4,11 @@ import pytest from sortscore.analysis.aa_scores import build_aa_scores_table -from sortscore.analysis.batch_normalization import save_batch_results +from sortscore.analysis.batch_normalization import ( + _build_normalization_stats, + run_batch_analysis, + save_batch_results, +) def test_save_batch_results_preserves_decimal_score_precision(tmp_path): @@ -80,3 +84,93 @@ def test_build_aa_scores_table_preserves_decimal_stats_for_aa_only_scores(): assert row["SEM"] == pytest.approx(1.5) assert row["CI_lower"] == pytest.approx(-8.559307104263047) assert row["CI_upper"] == pytest.approx(29.559307104263045) + + +def test_build_normalization_stats_returns_nested_stage_and_final_sections(): + raw_scores = pd.DataFrame( + { + "batch": ["tile1", "tile1", "tile2", "tile2"], + "aa_seq_diff": ["=", "Q.2.*", "=", "A.3.S"], + "annotate_aa": ["synonymous", "nonsense", "synonymous", "missense_aa"], + "annotate_dna": ["wt_dna", "missense_dna", "synonymous", "missense_dna"], + "avgscore": [10.0, 2.0, 12.0, 20.0], + } + ) + final_scores = raw_scores.copy() + final_scores["avgscore"] = [0.0, -2.0, 1.0, 3.0] + + stats = _build_normalization_stats( + raw_tile_values={ + "tile1": {"wt_dna_score": 10.0, "non_avg": 2.0}, + "tile2": {"syn_median": 12.0}, + }, + raw_global_values={"wt_dna_score": 10.0}, + wt_stage_global_values={"syn_mean": 11.0, "syn_std": 1.4142135623730951}, + zscore_tile_values={ + "tile1": {"non_avg_zscore": -2.0}, + "tile2": {}, + }, + zscore_global_values={"non_avg_zscore": -2.0}, + final_scores=final_scores, + wt_factors={"tile1": 1.1, "tile2": 0.9}, + path_factors={"tile1": 1.5, "tile2": 0.5}, + ) + + assert "raw" in stats + assert "wt_alignment" in stats + assert "zscore" in stats + assert stats["raw"]["global"]["wt_dna_score"] == 10.0 + assert stats["raw"]["tile1"]["wt_dna_score"] == 10.0 + assert stats["raw"]["tile2"]["syn_median"] == 12.0 + assert stats["wt_alignment"]["global"]["syn_mean"] == 11.0 + assert stats["wt_alignment"]["tile1"]["normalization_factor"] == 1.1 + assert stats["zscore"]["global"]["non_avg_zscore"] == -2.0 + assert stats["zscore"]["tile1"]["non_avg_zscore"] == -2.0 + assert stats["zscore"]["tile2"]["pathogenic_normalization_factor"] == 0.5 + assert stats["final"]["global"]["overall"] == {"avg": 0, "min": -2, "max": 3} + assert stats["final"]["tile1"]["nonsense"] == {"avg": -2, "min": -2, "max": -2} + + +def test_run_batch_analysis_loads_batch_config_entries(tmp_path): + tile_output_dir = tmp_path / "tile1" + scores_dir = tile_output_dir / "scores" + scores_dir.mkdir(parents=True) + + pd.DataFrame( + { + "variant_seq": ["AAA", "AAG", "TAA"], + "dna_seq_diff": ["=", "A.1.G", "T.1.A"], + "aa_seq_diff": ["=", "K.1.R", "Q.1.*"], + "annotate_dna": ["wt_dna", "synonymous", "missense_dna"], + "annotate_aa": ["synonymous", "synonymous", "nonsense"], + "avgscore": [10.0, 12.0, 2.0], + "avgscore_rep_weighted": [10.0, 12.0, 2.0], + "Rep1.score": [10.0, 12.0, 2.0], + "Rep2.score": [10.0, 12.0, 2.0], + } + ).to_csv(scores_dir / "tile1_dna_scores.csv", index=False) + + results = run_batch_analysis( + { + "batch_normalization_method": "zscore_2pole", + "pathogenic_control_type": "nonsense", + "combined_output_dir": str(tmp_path), + "experiments": [ + { + "tile": 1, + "output_dir": str(tile_output_dir), + "avg_method": "simple-avg", + "min_pos": 1, + "max_pos": 3, + "wt_seq": "AAA", + "mutagenesis_type": "codon", + } + ], + } + ) + + assert results["method"] == "zscore_2pole" + assert results["output_dir"] == str((tmp_path / "normalized" / "zscore_2pole").resolve()) + assert len(results["experiments"]) == 1 + assert results["experiments"][0].min_pos == 1 + assert not results["normalized_scores"].empty diff --git a/tests/unit/test_summary_stats.py b/tests/unit/test_summary_stats.py index cb5be31..bb7a3bc 100644 --- a/tests/unit/test_summary_stats.py +++ b/tests/unit/test_summary_stats.py @@ -1,5 +1,3 @@ -from types import SimpleNamespace - import pandas as pd from sortscore.analysis.summary_stats import calculate_summary_stats @@ -18,8 +16,7 @@ def test_calculate_summary_stats_returns_flat_sections(): stats = calculate_summary_stats( scores_df, - SimpleNamespace(avg_method="simple-avg"), - score_col="avgscore", + "avgscore", ) assert stats["overall"] == {"avg": 12, "min": 5, "max": 20} From 76abafa606eb8d75aa3dba75552d813221b39b89 Mon Sep 17 00:00:00 2001 From: CAITLYN CHITWOOD Date: Wed, 13 May 2026 15:05:04 -0500 Subject: [PATCH 6/8] Add median and standard deviation calculations to summary stat and update tests --- sortscore/analysis/batch_normalization.py | 108 ++++++---------------- sortscore/analysis/summary_stats.py | 8 +- tests/unit/test_batch_normalization.py | 55 ++++++++++- tests/unit/test_summary_stats.py | 8 +- 4 files changed, 88 insertions(+), 91 deletions(-) diff --git a/sortscore/analysis/batch_normalization.py b/sortscore/analysis/batch_normalization.py index b2ec5f3..9f74111 100644 --- a/sortscore/analysis/batch_normalization.py +++ b/sortscore/analysis/batch_normalization.py @@ -569,6 +569,7 @@ def apply_zscore_2pole_normalization( syn_scores.extend(syn_subset['avgscore'].dropna().tolist()) syn_mean = np.mean(syn_scores) if syn_scores else 0.0 + syn_median = float(np.median(syn_scores)) if syn_scores else np.nan syn_std = np.std(syn_scores, ddof=1) if len(syn_scores) > 1 else 1.0 # Apply Z-score transformation @@ -629,7 +630,8 @@ def apply_zscore_2pole_normalization( }, raw_global_values={'wt_dna_score': A}, wt_stage_global_values={ - 'syn_mean': syn_mean, + 'syn_avg': syn_mean, + 'syn_median': syn_median, 'syn_std': syn_std, }, zscore_tile_values=zscore_stats, @@ -755,6 +757,7 @@ def apply_zscore_center_normalization( syn_scores = reference_normalized_scores['avgscore'].dropna().tolist() syn_mean = np.mean(syn_scores) if syn_scores else 0.0 + syn_median = float(np.median(syn_scores)) if syn_scores else np.nan syn_std = np.std(syn_scores, ddof=1) if len(syn_scores) > 1 else 1.0 # Apply z-score transformation (final normalization) @@ -777,7 +780,8 @@ def apply_zscore_center_normalization( 'reference_avg': global_reference_avg, }, wt_stage_global_values={ - 'syn_mean': syn_mean, + 'syn_avg': syn_mean, + 'syn_median': syn_median, 'syn_std': syn_std, }, final_scores=final_scores, @@ -788,70 +792,6 @@ def apply_zscore_center_normalization( return final_scores, combined_stats -def recalculate_final_statistics( - normalized_scores: pd.DataFrame, - score_col: str -) -> Dict[str, Any]: - """ - Recalculate statistics from fully normalized score data. - - Parameters - ---------- - normalized_scores : pd.DataFrame - Fully normalized scores DataFrame - score_col : str - Name of main score column to use for calculations - - Returns - ------- - Dict[str, Any] - Dictionary of recalculated statistics - """ - final_stats = {} - - # Global final statistics - if score_col in normalized_scores.columns: - scores = normalized_scores[score_col].dropna() - if len(scores) > 0: - final_stats['all_avg_global_final'] = float(scores.mean()) - final_stats['all_min_global_final'] = float(scores.min()) - final_stats['all_max_global_final'] = float(scores.max()) - - if 'annotate_aa' in normalized_scores.columns and score_col in normalized_scores.columns: - nonsense_subset = normalized_scores[normalized_scores['annotate_aa'] == 'nonsense'] - if len(nonsense_subset) > 0: - nonsense_scores = nonsense_subset[score_col].dropna() - if len(nonsense_scores) > 0: - final_stats['nonsense_avg_global_final'] = float(nonsense_scores.mean()) - - # Per-batch final statistics - for batch_name, batch_df in normalized_scores.groupby('batch'): - batch_prefix = f'{batch_name}_final' - - if score_col in batch_df.columns: - scores = batch_df[score_col].dropna() - if len(scores) > 0: - final_stats[f'all_avg_{batch_prefix}'] = float(scores.mean()) - - # Missense average per batch - if 'annotate_aa' in batch_df.columns: - missense_subset = batch_df[batch_df['annotate_aa'] == 'missense_aa'] - if len(missense_subset) > 0 and score_col in missense_subset.columns: - missense_scores = missense_subset[score_col].dropna() - if len(missense_scores) > 0: - final_stats[f'missense_avg_{batch_prefix}'] = float(missense_scores.mean()) - - # Nonsense average per batch - if 'annotate_aa' in batch_df.columns: - nonsense_subset = batch_df[batch_df['annotate_aa'] == 'nonsense'] - if len(nonsense_subset) > 0 and score_col in nonsense_subset.columns: - nonsense_scores = nonsense_subset[score_col].dropna() - if len(nonsense_scores) > 0: - final_stats[f'nonsense_avg_{batch_prefix}'] = float(nonsense_scores.mean()) - - return final_stats - - def generate_batch_visualizations( results: Dict[str, Any], batch_config: Dict[str, Any], @@ -883,19 +823,18 @@ def generate_batch_visualizations( # Determine score column to visualize score_col = 'avgscore' # Default, could be made configurable - # Calculate WT score for colorbar reference if available - wt_score = None combined_stats = results.get('combined_stats', {}) - - # Try to get normalized WT score from stats - if results['method'] == 'zscore_2pole': - # For z-score method, WT should be close to 0 after normalization - wt_score = 0.0 - elif results['method'] == '2pole': - # For 2-pole method, try to get global synonymous median - wt_score = combined_stats.get('syn_median_global_raw') - - # Build colorbar ticks/labels informed by combined stats. + + final_global_stats = combined_stats.get('final', {}).get('global', {}) + wt_stats = final_global_stats.get('wt') + syn_wt_stats = final_global_stats.get('synonymous_wt') + if wt_stats is not None and 'avg' in wt_stats: + wt_score = wt_stats['avg'] + elif syn_wt_stats is not None and 'avg' in syn_wt_stats: + wt_score = syn_wt_stats['avg'] + else: + wt_score = None + def _build_colorbar_ticks(score_series: pd.Series) -> Tuple[Optional[List[float]], Optional[List[str]]]: series = pd.to_numeric(score_series, errors='coerce').dropna() if len(series) == 0: @@ -906,9 +845,18 @@ def _build_colorbar_ticks(score_series: pd.Series) -> Tuple[Optional[List[float] pathogenic_tick = None if config_obj.pathogenic_control_type == 'nonsense': - pathogenic_tick = combined_stats.get('nonsense_avg_global_final') + pathogenic_tick = ( + combined_stats.get('final', {}) + .get('global', {}) + .get('nonsense', {}) + .get('avg') + ) if pathogenic_tick is None: - pathogenic_tick = combined_stats.get('non_avg_global_zscore_z') + pathogenic_tick = ( + combined_stats.get('zscore', {}) + .get('global', {}) + .get('non_avg_zscore') + ) ticks = [(data_min, f'{data_min:.1f}')] if wt_score is not None and pd.notna(wt_score): diff --git a/sortscore/analysis/summary_stats.py b/sortscore/analysis/summary_stats.py index 8b8f8f8..e08bca3 100644 --- a/sortscore/analysis/summary_stats.py +++ b/sortscore/analysis/summary_stats.py @@ -17,10 +17,12 @@ def _summarize_subset(df: pd.DataFrame, score_col: str) -> Optional[Dict[str, An scores = pd.to_numeric(df[score_col], errors='coerce').dropna() if scores.empty: return None + std = float(scores.std(ddof=1)) if len(scores) > 1 else 0.0 return { - 'avg': round(float(scores.mean())), - 'min': round(float(scores.min())), - 'max': round(float(scores.max())), + 'avg': round(float(scores.mean()), 2), + 'min': round(float(scores.min()), 2), + 'max': round(float(scores.max()), 2), + 'std': round(std, 2), } diff --git a/tests/unit/test_batch_normalization.py b/tests/unit/test_batch_normalization.py index 4a5d12a..a9d5180 100644 --- a/tests/unit/test_batch_normalization.py +++ b/tests/unit/test_batch_normalization.py @@ -6,6 +6,7 @@ from sortscore.analysis.aa_scores import build_aa_scores_table from sortscore.analysis.batch_normalization import ( _build_normalization_stats, + generate_batch_visualizations, run_batch_analysis, save_batch_results, ) @@ -105,7 +106,7 @@ def test_build_normalization_stats_returns_nested_stage_and_final_sections(): "tile2": {"syn_median": 12.0}, }, raw_global_values={"wt_dna_score": 10.0}, - wt_stage_global_values={"syn_mean": 11.0, "syn_std": 1.4142135623730951}, + wt_stage_global_values={"syn_avg": 11.0, "syn_median": 11.0, "syn_std": 1.4142135623730951}, zscore_tile_values={ "tile1": {"non_avg_zscore": -2.0}, "tile2": {}, @@ -122,13 +123,14 @@ def test_build_normalization_stats_returns_nested_stage_and_final_sections(): assert stats["raw"]["global"]["wt_dna_score"] == 10.0 assert stats["raw"]["tile1"]["wt_dna_score"] == 10.0 assert stats["raw"]["tile2"]["syn_median"] == 12.0 - assert stats["wt_alignment"]["global"]["syn_mean"] == 11.0 + assert stats["wt_alignment"]["global"]["syn_avg"] == 11.0 + assert stats["wt_alignment"]["global"]["syn_median"] == 11.0 assert stats["wt_alignment"]["tile1"]["normalization_factor"] == 1.1 assert stats["zscore"]["global"]["non_avg_zscore"] == -2.0 assert stats["zscore"]["tile1"]["non_avg_zscore"] == -2.0 assert stats["zscore"]["tile2"]["pathogenic_normalization_factor"] == 0.5 - assert stats["final"]["global"]["overall"] == {"avg": 0, "min": -2, "max": 3} - assert stats["final"]["tile1"]["nonsense"] == {"avg": -2, "min": -2, "max": -2} + assert stats["final"]["global"]["overall"] == {"avg": 0.5, "min": -2.0, "max": 3.0, "std": 2.08} + assert stats["final"]["tile1"]["nonsense"] == {"avg": -2.0, "min": -2.0, "max": -2.0, "std": 0.0} def test_run_batch_analysis_loads_batch_config_entries(tmp_path): @@ -174,3 +176,48 @@ def test_run_batch_analysis_loads_batch_config_entries(tmp_path): assert len(results["experiments"]) == 1 assert results["experiments"][0].min_pos == 1 assert not results["normalized_scores"].empty + + +def test_generate_batch_visualizations_uses_structured_stats_for_ticks(monkeypatch, tmp_path): + calls = [] + + def _fake_plot_tiled_heatmap(**kwargs): + calls.append(kwargs) + + monkeypatch.setattr( + "sortscore.visualization.heatmaps.plot_tiled_heatmap", + _fake_plot_tiled_heatmap, + ) + + results = { + "method": "2pole", + "normalized_scores": pd.DataFrame( + { + "batch": ["tile1", "tile1"], + "avgscore": [1.0, 3.0], + "annotate_aa": ["synonymous", "nonsense"], + } + ), + "normalized_aa_scores": pd.DataFrame(), + "combined_stats": { + "final": { + "global": { + "wt": {"avg": 1.5}, + "nonsense": {"avg": 2.5}, + } + }, + }, + "experiments": [], + } + batch_config = { + "batch_normalization_method": "2pole", + "pathogenic_control_type": "nonsense", + "experiments": [], + } + + generate_batch_visualizations(results, batch_config, str(tmp_path)) + + assert len(calls) == 1 + assert calls[0]["wt_score"] == 1.5 + assert calls[0]["tick_values"] == [1.0, 1.5, 2.5, 3.0] + assert calls[0]["tick_labels"] == ["1.0", "WT Avg", "(-) Control Avg", "3.0"] diff --git a/tests/unit/test_summary_stats.py b/tests/unit/test_summary_stats.py index bb7a3bc..3830284 100644 --- a/tests/unit/test_summary_stats.py +++ b/tests/unit/test_summary_stats.py @@ -19,7 +19,7 @@ def test_calculate_summary_stats_returns_flat_sections(): "avgscore", ) - assert stats["overall"] == {"avg": 12, "min": 5, "max": 20} - assert stats["synonymous_wt"] == {"avg": 10, "min": 10, "max": 10} - assert stats["missense"] == {"avg": 20, "min": 20, "max": 20} - assert stats["nonsense"] == {"avg": 5, "min": 5, "max": 5} + assert stats["overall"] == {"avg": 11.67, "min": 5.0, "max": 20.0, "std": 7.64} + assert stats["synonymous_wt"] == {"avg": 10.0, "min": 10.0, "max": 10.0, "std": 0.0} + assert stats["missense"] == {"avg": 20.0, "min": 20.0, "max": 20.0, "std": 0.0} + assert stats["nonsense"] == {"avg": 5.0, "min": 5.0, "max": 5.0, "std": 0.0} From a1893dc60157558ae6ce8a12bed9de22410749a4 Mon Sep 17 00:00:00 2001 From: CAITLYN CHITWOOD Date: Wed, 13 May 2026 15:05:31 -0500 Subject: [PATCH 7/8] Update version to 0.1.0. Update changelog for stable release --- CHANGELOG.md | 26 +++++++++++++++++++++++++- pyproject.toml | 4 ++-- sortscore/__init__.py | 2 +- sortscore/analysis/summary_stats.py | 1 + tests/unit/test_summary_stats.py | 8 ++++---- 5 files changed, 33 insertions(+), 8 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index dc8991f..6463b8d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -17,6 +17,29 @@ with [PEP 440](https://peps.python.org/pep-0440/) pre-release identifiers for pa ### Fixed - +## [0.1.0] - 2026-05-12 + +### Added +- First stable release after the alpha/beta publishing cycle and successful testing by external users. +- Batch amino acid score outputs for combined normalization runs. +- Average positional score bar in batch heatmap outputs. +- GitHub Actions workflow for pull request pytest runs. +- Integration coverage for `run_batch_analysis(...)` batch-config loading. + +### Changed +- Promoted package metadata from beta to stable release status. +- Simplified batch output naming by removing date/output suffixes from score file paths and related tests. +- Updated batch visualization layout, including grid refinements and removal of the batch figure title. +- Represent no sequence difference explicitly as `=` during annotation and parsing. +- Preserve synonymous/no-difference rows in amino acid score outputs. +- Write batch normalization outputs under `normalized//`. +- Simplify summary stats output to focus on the scored file and expose normalization inputs directly in batch stats. + +### Fixed +- Preserved decimal precision in batch score exports, including `score.r#b#`, replicate score columns, and `avgscore`. +- Preserved decimal precision in AA score statistics exports, including `SD_codon`, `SD_rep`, `SEM`, and confidence interval columns. +- Stopped rounding scores before plotting and corrected global pathogenic heatmap tick handling. + ## [0.1.0b3] - 2026-03-11 ### Added @@ -63,7 +86,8 @@ with [PEP 440](https://peps.python.org/pep-0440/) pre-release identifiers for pa ### Fixed - -[Unreleased]: https://github.com/dbaldridge-lab/sortscore/compare/0.1.0b3...HEAD +[Unreleased]: https://github.com/dbaldridge-lab/sortscore/compare/0.1.0...HEAD +[0.1.0]: https://github.com/dbaldridge-lab/sortscore/compare/0.1.0b3...0.1.0 [0.1.0b1]: https://github.com/dbaldridge-lab/sortscore/compare/0.1.0a1...0.1.0b1 [0.1.0a1]: https://github.com/dbaldridge-lab/sortscore/releases/tag/0.1.0a1 [0.1.0b2]: https://github.com/dbaldridge-lab/sortscore/compare/0.1.0b1...0.1.0b2 diff --git a/pyproject.toml b/pyproject.toml index 0932baf..ba6cf3e 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta" [project] name = "sortscore" -version = "0.1.0b3" +version = "0.1.0" description = "A modular Python package for Sort-seq variant analysis" readme = "README.md" requires-python = ">=3.10" @@ -14,7 +14,7 @@ authors = [ ] keywords = ["bioinformatics", "sequencing", "variant-analysis", "sort-seq"] classifiers = [ - "Development Status :: 4 - Beta", + "Development Status :: 5 - Production/Stable", "Intended Audience :: Science/Research", "Topic :: Scientific/Engineering :: Bio-Informatics", "License :: OSI Approved :: MIT License", diff --git a/sortscore/__init__.py b/sortscore/__init__.py index 17384d6..bdce2b3 100644 --- a/sortscore/__init__.py +++ b/sortscore/__init__.py @@ -5,7 +5,7 @@ calculating activity scores, and generating visualizations. """ -__version__ = "0.1.0b3" +__version__ = "0.1.0" __author__ = "Caitlyn Chitwood" __email__ = "c.chitwood@wustl.edu" diff --git a/sortscore/analysis/summary_stats.py b/sortscore/analysis/summary_stats.py index e08bca3..186ee01 100644 --- a/sortscore/analysis/summary_stats.py +++ b/sortscore/analysis/summary_stats.py @@ -20,6 +20,7 @@ def _summarize_subset(df: pd.DataFrame, score_col: str) -> Optional[Dict[str, An std = float(scores.std(ddof=1)) if len(scores) > 1 else 0.0 return { 'avg': round(float(scores.mean()), 2), + 'median': round(float(scores.median()), 2), 'min': round(float(scores.min()), 2), 'max': round(float(scores.max()), 2), 'std': round(std, 2), diff --git a/tests/unit/test_summary_stats.py b/tests/unit/test_summary_stats.py index 3830284..baae3d4 100644 --- a/tests/unit/test_summary_stats.py +++ b/tests/unit/test_summary_stats.py @@ -19,7 +19,7 @@ def test_calculate_summary_stats_returns_flat_sections(): "avgscore", ) - assert stats["overall"] == {"avg": 11.67, "min": 5.0, "max": 20.0, "std": 7.64} - assert stats["synonymous_wt"] == {"avg": 10.0, "min": 10.0, "max": 10.0, "std": 0.0} - assert stats["missense"] == {"avg": 20.0, "min": 20.0, "max": 20.0, "std": 0.0} - assert stats["nonsense"] == {"avg": 5.0, "min": 5.0, "max": 5.0, "std": 0.0} + assert stats["overall"] == {"avg": 11.67, "median": 10.0, "min": 5.0, "max": 20.0, "std": 7.64} + assert stats["synonymous_wt"] == {"avg": 10.0, "median": 10.0, "min": 10.0, "max": 10.0, "std": 0.0} + assert stats["missense"] == {"avg": 20.0, "median": 20.0, "min": 20.0, "max": 20.0, "std": 0.0} + assert stats["nonsense"] == {"avg": 5.0, "median": 5.0, "min": 5.0, "max": 5.0, "std": 0.0} From e59c5d075796cf3e48882cbc6b9869f868c63e4b Mon Sep 17 00:00:00 2001 From: CAITLYN CHITWOOD Date: Wed, 13 May 2026 15:14:52 -0500 Subject: [PATCH 8/8] Fix batch normalization stats test expectation --- tests/unit/test_batch_normalization.py | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-) diff --git a/tests/unit/test_batch_normalization.py b/tests/unit/test_batch_normalization.py index a9d5180..e79c953 100644 --- a/tests/unit/test_batch_normalization.py +++ b/tests/unit/test_batch_normalization.py @@ -129,8 +129,20 @@ def test_build_normalization_stats_returns_nested_stage_and_final_sections(): assert stats["zscore"]["global"]["non_avg_zscore"] == -2.0 assert stats["zscore"]["tile1"]["non_avg_zscore"] == -2.0 assert stats["zscore"]["tile2"]["pathogenic_normalization_factor"] == 0.5 - assert stats["final"]["global"]["overall"] == {"avg": 0.5, "min": -2.0, "max": 3.0, "std": 2.08} - assert stats["final"]["tile1"]["nonsense"] == {"avg": -2.0, "min": -2.0, "max": -2.0, "std": 0.0} + assert stats["final"]["global"]["overall"] == { + "avg": 0.5, + "median": 0.5, + "min": -2.0, + "max": 3.0, + "std": 2.08, + } + assert stats["final"]["tile1"]["nonsense"] == { + "avg": -2.0, + "median": -2.0, + "min": -2.0, + "max": -2.0, + "std": 0.0, + } def test_run_batch_analysis_loads_batch_config_entries(tmp_path):