catomatic 0.2.1__tar.gz → 0.2.3__tar.gz

{catomatic-0.2.1/src/catomatic.egg-info → catomatic-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: catomatic
-Version: 0.2.1
+Version: 0.2.3
 Summary: A tool for automatically building catalogues of antibiotic resistance-associated variants
 Author: Dylan Adlard
 Author-email: Philip W Fowler <philip.fowler@ndm.ox.ac.uk>
@@ -48,15 +48,15 @@ The first is used in [https://doi.org/10.1101/2025.01.30.635633](https://doi.org
 
 This method relies on the logic that mutations that do not cause resistance can co-occur with those that do. If a mutation in isolation (solo) does not cause resistance, then it is not contributing to the phenotype when present in a mixture either.
 
-Mutations that occur in isolation across specified genes are traversed in sequence, and if their proportion of drug-susceptibility (vs. resistance) passes the specified statistical test, they are characterized as benign (susceptible) and removed from the dataset. This step repeats iteratively until no more solo benign mutations are found.
+Mutations that occur in isolation are traversed in sequence. When they meet the susceptible criteria for the selected test, they are characterized as benign (`S`) and removed from the dataset. This step repeats iteratively until no more solo benign mutations are found.
 
 Remaining mutations are classified based on their resistance rates and statistical test results. Those that don’t meet thresholds are labeled as `U`.
 
 The classification approach supports:
 
-- **No test**: assumes homogeneous susceptibility is sufficient for S
-- **Binomial test**: against a specified background resistance rate
-- **Fisher's test**: using a contingency background
+- **No test**: calls a mutation `S` during iterative unlocking when all its solo observations are susceptible; remaining solo mutations are `U`
+- **Binomial test**: tests the solo resistance rate against a specified background resistance rate
+- **Fisher's test**: compares the mutation solo contingency table with the no-mutation solo background
 
 ### Optional Interventions
 
@@ -68,9 +68,9 @@ Because the method uses GARC1 grammar, rules like `{rpoB@*_fs:R}` can be supplie
 - Be additive (lower priority than specific entries)
 - Replace matching mutations (requires `replace=True` and `wildcards` supplied)
 
-The catalogue can be returned as a dictionary or a Piezo-compatible `pandas.DataFrame`.
+The built catalogue is available as a dictionary through the `catalogue.catalogue` attribute. It can also be converted to a Piezo-compatible `pandas.DataFrame` with `build_piezo()`.
 
-Contingency tables, proportions, p-values, and Wilson confidence intervals are stored in the `EVIDENCE` field.
+Evidence is stored with each catalogue entry and exported in the `EVIDENCE` field. It includes proportions, Wilson confidence intervals, solo contingency tables used for classification, full sample-level contingency tables for description, and p-values when a statistical test is used. Sample IDs can be included with `record_ids=True`.
 
 ### Example Workflow using Fisher's:
 
@@ -125,7 +125,7 @@ from catomatic.BinaryCatalogue import BinaryBuilder
 catalogue = BinaryBuilder(samples=samples_df, mutations=mutations_df).build()
 
 # View dictionary version
-cat_dict = catalogue.return_catalogue()
+cat_dict = catalogue.catalogue
 
 # Convert to Piezo-compatible format
 catalogue_df = catalogue.build_piezo(
@@ -149,7 +149,7 @@ catalogue.to_piezo(
 
 ### CLI
 
-After installation, the simplest way to run the catomatic catalogue builder is via the command line interface using the `binary` subcommand. You must use either `--to_piezo` or `--to_json` to specify the output format. Additional metadata is required when using `--to_piezo`.
+After installation, the simplest way to run the catomatic catalogue builder is via the command line interface using the `binary` subcommand. Use `--to_piezo` or `--to_json` to export the catalogue. If neither is supplied, no file is exported. Additional metadata is required when using `--to_piezo`.
 
 #### Export to JSON
 
@@ -178,6 +178,8 @@ catomatic binary \
 
 ### CLI Parameters
 
+The Binary CLI does not expose the Python `build()` options `tails` or `min_count`. The output flags are not mutually exclusive; if both are supplied, both exporters write to the same `--outfile`, so use only one.
+
 | Parameter          | Type    | Description                                                                                    |
 | ------------------ | ------- | ---------------------------------------------------------------------------------------------- |
 | `--samples`        | `str`   | Path to the samples (phenotypes) file. Required.                                               |
@@ -190,11 +192,16 @@ catomatic binary \
 | `--version`        | `str`   | Catalogue version. Required with `--to_piezo`.                                                 |
 | `--drug`           | `str`   | Name of the drug. Required with `--to_piezo`.                                                  |
 | `--wildcards`      | `str`   | Path to JSON file containing wildcard mutation definitions. Required with `--to_piezo`.        |
-| `--test`           | `str`   | Type of statistical test to apply. One of: `None`, `Binomial`, or `Fisher`. Optional.          |
-| `--background`     | `float` | Background mutation rate (0–1). Required if `--test Binomial` is used.                         |
-| `--p`              | `float` | P-value threshold for statistical significance. Optional. Defaults to `0.95`.                  |
-| `--tails`          | `str`   | Tail type for statistical test. One of: `one`, `two`. Optional. Defaults to `two`.             |
-| `--strict_unlock`  | `flag`  | If set, disables classification of susceptible (`S`) mutations unless statistically confident. |
+| `--test`           | `str`   | Type of statistical test to apply: `Binomial` or `Fisher`. Optional; if omitted, no statistical test is used. |
+| `--background`     | `float` | Background resistance rate (0–1). Required if `--test Binomial` is used.                       |
+| `--p`              | `float` | Confidence level used for statistical testing. Optional. Defaults to `0.95` (a 0.05 significance threshold). |
+| `--strict_unlock`  | `flag`  | For two-tailed tests, require statistical significance to classify homogeneous susceptible mutations as `S` during iterative unlocking. |
+| `--frs`            | `float` | Optional fraction-read-support threshold. Requires an `FRS` column in the mutations file.       |
+| `--seed`           | `str[]`  | Optional list of mutations to seed as susceptible before building.                              |
+| `--record_ids`     | `flag`  | Include sample IDs in evidence records.                                                        |
+| `--grammar`        | `str`   | Grammar used for Piezo export. Default: `GARC1`.                                                |
+| `--values`         | `str`   | Prediction values for Piezo export. Default: `RUS`.                                             |
+| `--for_piezo`      | `flag`  | Add placeholder rows for Piezo export. Default: `False` in the CLI.                            |
 
 ## Running catomatic's Regression Builder
 
@@ -310,8 +317,8 @@ catomatic regression \
 
 ### Notes
 
-- When using post-hoc rule updates via .update(), you must provide wildcards and set replace=True if you intend to override existing entries.
-- For Piezo export, placeholder entries are inserted automatically if needed to satisfy parser requirements (R, S, and U must be represented).
+- For `BinaryBuilder`, use `update_catalogue()` to apply post-hoc rules. Supply `wildcards` and set `replace=True` to replace entries matched by an aggregate rule. Specific entries can be added or replaced without `replace=True`.
+- For Piezo export, placeholder entries are inserted when `for_piezo=True` and needed to satisfy parser requirements (R, S, and U must be represented). The Python export methods default to `for_piezo=True`; the CLI flag is off by default.
 - The EVIDENCE column includes contingency tables, proportions, confidence intervals, and p-values, and may optionally include sample IDs if `record_ids=True`.
 - To build a catalogue with the regression builder, as currently implemented, requires an ecoff as it will compare the predited effected against the background to supply an R/S/U label
   - To only calculate predicted effects, this can be done in Python by calling RegressionBuilder.predict_effects()

{catomatic-0.2.1 → catomatic-0.2.3}/README.md

@@ -23,15 +23,15 @@ The first is used in [https://doi.org/10.1101/2025.01.30.635633](https://doi.org
 
 This method relies on the logic that mutations that do not cause resistance can co-occur with those that do. If a mutation in isolation (solo) does not cause resistance, then it is not contributing to the phenotype when present in a mixture either.
 
-Mutations that occur in isolation across specified genes are traversed in sequence, and if their proportion of drug-susceptibility (vs. resistance) passes the specified statistical test, they are characterized as benign (susceptible) and removed from the dataset. This step repeats iteratively until no more solo benign mutations are found.
+Mutations that occur in isolation are traversed in sequence. When they meet the susceptible criteria for the selected test, they are characterized as benign (`S`) and removed from the dataset. This step repeats iteratively until no more solo benign mutations are found.
 
 Remaining mutations are classified based on their resistance rates and statistical test results. Those that don’t meet thresholds are labeled as `U`.
 
 The classification approach supports:
 
-- **No test**: assumes homogeneous susceptibility is sufficient for S
-- **Binomial test**: against a specified background resistance rate
-- **Fisher's test**: using a contingency background
+- **No test**: calls a mutation `S` during iterative unlocking when all its solo observations are susceptible; remaining solo mutations are `U`
+- **Binomial test**: tests the solo resistance rate against a specified background resistance rate
+- **Fisher's test**: compares the mutation solo contingency table with the no-mutation solo background
 
 ### Optional Interventions
 
@@ -43,9 +43,9 @@ Because the method uses GARC1 grammar, rules like `{rpoB@*_fs:R}` can be supplie
 - Be additive (lower priority than specific entries)
 - Replace matching mutations (requires `replace=True` and `wildcards` supplied)
 
-The catalogue can be returned as a dictionary or a Piezo-compatible `pandas.DataFrame`.
+The built catalogue is available as a dictionary through the `catalogue.catalogue` attribute. It can also be converted to a Piezo-compatible `pandas.DataFrame` with `build_piezo()`.
 
-Contingency tables, proportions, p-values, and Wilson confidence intervals are stored in the `EVIDENCE` field.
+Evidence is stored with each catalogue entry and exported in the `EVIDENCE` field. It includes proportions, Wilson confidence intervals, solo contingency tables used for classification, full sample-level contingency tables for description, and p-values when a statistical test is used. Sample IDs can be included with `record_ids=True`.
 
 ### Example Workflow using Fisher's:
 
@@ -100,7 +100,7 @@ from catomatic.BinaryCatalogue import BinaryBuilder
 catalogue = BinaryBuilder(samples=samples_df, mutations=mutations_df).build()
 
 # View dictionary version
-cat_dict = catalogue.return_catalogue()
+cat_dict = catalogue.catalogue
 
 # Convert to Piezo-compatible format
 catalogue_df = catalogue.build_piezo(
@@ -124,7 +124,7 @@ catalogue.to_piezo(
 
 ### CLI
 
-After installation, the simplest way to run the catomatic catalogue builder is via the command line interface using the `binary` subcommand. You must use either `--to_piezo` or `--to_json` to specify the output format. Additional metadata is required when using `--to_piezo`.
+After installation, the simplest way to run the catomatic catalogue builder is via the command line interface using the `binary` subcommand. Use `--to_piezo` or `--to_json` to export the catalogue. If neither is supplied, no file is exported. Additional metadata is required when using `--to_piezo`.
 
 #### Export to JSON
 
@@ -153,6 +153,8 @@ catomatic binary \
 
 ### CLI Parameters
 
+The Binary CLI does not expose the Python `build()` options `tails` or `min_count`. The output flags are not mutually exclusive; if both are supplied, both exporters write to the same `--outfile`, so use only one.
+
 | Parameter          | Type    | Description                                                                                    |
 | ------------------ | ------- | ---------------------------------------------------------------------------------------------- |
 | `--samples`        | `str`   | Path to the samples (phenotypes) file. Required.                                               |
@@ -165,11 +167,16 @@ catomatic binary \
 | `--version`        | `str`   | Catalogue version. Required with `--to_piezo`.                                                 |
 | `--drug`           | `str`   | Name of the drug. Required with `--to_piezo`.                                                  |
 | `--wildcards`      | `str`   | Path to JSON file containing wildcard mutation definitions. Required with `--to_piezo`.        |
-| `--test`           | `str`   | Type of statistical test to apply. One of: `None`, `Binomial`, or `Fisher`. Optional.          |
-| `--background`     | `float` | Background mutation rate (0–1). Required if `--test Binomial` is used.                         |
-| `--p`              | `float` | P-value threshold for statistical significance. Optional. Defaults to `0.95`.                  |
-| `--tails`          | `str`   | Tail type for statistical test. One of: `one`, `two`. Optional. Defaults to `two`.             |
-| `--strict_unlock`  | `flag`  | If set, disables classification of susceptible (`S`) mutations unless statistically confident. |
+| `--test`           | `str`   | Type of statistical test to apply: `Binomial` or `Fisher`. Optional; if omitted, no statistical test is used. |
+| `--background`     | `float` | Background resistance rate (0–1). Required if `--test Binomial` is used.                       |
+| `--p`              | `float` | Confidence level used for statistical testing. Optional. Defaults to `0.95` (a 0.05 significance threshold). |
+| `--strict_unlock`  | `flag`  | For two-tailed tests, require statistical significance to classify homogeneous susceptible mutations as `S` during iterative unlocking. |
+| `--frs`            | `float` | Optional fraction-read-support threshold. Requires an `FRS` column in the mutations file.       |
+| `--seed`           | `str[]`  | Optional list of mutations to seed as susceptible before building.                              |
+| `--record_ids`     | `flag`  | Include sample IDs in evidence records.                                                        |
+| `--grammar`        | `str`   | Grammar used for Piezo export. Default: `GARC1`.                                                |
+| `--values`         | `str`   | Prediction values for Piezo export. Default: `RUS`.                                             |
+| `--for_piezo`      | `flag`  | Add placeholder rows for Piezo export. Default: `False` in the CLI.                            |
 
 ## Running catomatic's Regression Builder
 
@@ -285,8 +292,8 @@ catomatic regression \
 
 ### Notes
 
-- When using post-hoc rule updates via .update(), you must provide wildcards and set replace=True if you intend to override existing entries.
-- For Piezo export, placeholder entries are inserted automatically if needed to satisfy parser requirements (R, S, and U must be represented).
+- For `BinaryBuilder`, use `update_catalogue()` to apply post-hoc rules. Supply `wildcards` and set `replace=True` to replace entries matched by an aggregate rule. Specific entries can be added or replaced without `replace=True`.
+- For Piezo export, placeholder entries are inserted when `for_piezo=True` and needed to satisfy parser requirements (R, S, and U must be represented). The Python export methods default to `for_piezo=True`; the CLI flag is off by default.
 - The EVIDENCE column includes contingency tables, proportions, confidence intervals, and p-values, and may optionally include sample IDs if `record_ids=True`.
 - To build a catalogue with the regression builder, as currently implemented, requires an ecoff as it will compare the predited effected against the background to supply an R/S/U label
   - To only calculate predicted effects, this can be done in Python by calling RegressionBuilder.predict_effects()

{catomatic-0.2.1 → catomatic-0.2.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "catomatic"
-version = "0.2.1"
+version = "0.2.3"
 description = "A tool for automatically building catalogues of antibiotic resistance-associated variants"
 readme = "README.md"
 # If README.md is markdown, setuptools will pick it up; optionally:

{catomatic-0.2.1 → catomatic-0.2.3}/src/catomatic/RegressionCatalogue.py

@@ -10,7 +10,7 @@ from .defence_module import (
     validate_regression_predict_inputs,
     validate_regression_classify_inputs,
 )
-from typing import Any, Optional, Sequence, Tuple
+from typing import Any, Optional, Sequence, Tuple, cast
 from intreg.meintreg import MeIntReg
 from sklearn.cluster import AgglomerativeClustering
 
@@ -188,7 +188,7 @@ class RegressionBuilder(PiezoExporter):
                     fixed_effects_data,
                     columns=fixed_effects,
                     prefix=fixed_effects,  # Prefix helps to distinguish columns
-                    drop_first=False,
+                    drop_first=True,
                 )
                 .reindex(ids, fill_value=0)
                 .astype(int)
@@ -293,7 +293,7 @@ class RegressionBuilder(PiezoExporter):
 
         snps = self.mutations[
             ~self.mutations["MUTATION"].str.contains(
-                r"(?:indel|ins|del|Z|LOF)", regex=True
+                r"(?:indel|ins|del|Z|LOF|HAP|phylo|interaction)", regex=True
             )
         ].copy()
 
@@ -379,19 +379,23 @@ class RegressionBuilder(PiezoExporter):
         if not self.censored:
             tail_dilution_factor = self.dilution_factor**self.tail_dilutions
 
+        def parse_mic_value(mic: str) -> float:
+            #if a fraction (ie 2 drugs), just keep the numerator
+            return float(mic.split('/')[0])
+
         for i, mic in enumerate(df.MIC):
             if mic.startswith("<="):  # Left-censored
-                lower_bound = float(mic[2:])
+                lower_bound = parse_mic_value(mic[2:])
                 y_low[i] = 1e-6 if self.censored else lower_bound / tail_dilution_factor
                 y_high[i] = lower_bound
             elif mic.startswith(">"):  # Right-censored
-                upper_bound = float(mic[1:])
+                upper_bound = parse_mic_value(mic[1:])
                 y_low[i] = upper_bound
                 y_high[i] = (
                     np.inf if self.censored else upper_bound * tail_dilution_factor
                 )
             else:  # Exact MIC value
-                mic_value = float(mic)
+                mic_value = parse_mic_value(mic)
                 y_low[i] = mic_value / self.dilution_factor
                 y_high[i] = mic_value
 
@@ -443,15 +447,15 @@ class RegressionBuilder(PiezoExporter):
         y_low: np.ndarray,
         y_high: np.ndarray,
         clusters: Optional[Sequence[int]],
-    ) -> Tuple[np.ndarray, np.ndarray, float]:
+    ) -> Tuple[np.ndarray, float, float]:
         """
-        Generate initial Args for the regression model.
+        Generate initial parameters for the regression model.
 
         Strategy:
             - Use interval midpoints where finite.
             - Estimate beta via least squares on the finite subset.
-            - Sample small random initial u (random effects).
             - Set sigma to log(std(midpoints)).
+            - Set tau to an initial random-effect SD of 0.5.
 
         Args:
             X: Binary design matrix.
@@ -460,23 +464,24 @@ class RegressionBuilder(PiezoExporter):
             clusters: Cluster labels (or None).
 
         Returns:
-            (beta_init, u_init, sigma_init) where sigma_init is on the log scale.
+            (beta_init, log_sigma_init, log_tau_init).
         """
-        # Need to think about this a little more carefully - perhaps init params in meintreg could be improved?
+
         midpoints = (y_low + y_high) / 2.0
         valid_mask = np.isfinite(midpoints)
         X_valid = X[valid_mask]
         midpoints_valid = midpoints[valid_mask]
-        # Initial estimate of beta via linear regression
+
         beta_init = np.linalg.lstsq(X_valid, midpoints_valid, rcond=None)[0]
-        # Initial random effects - small non-zero value
-        u_init = np.random.normal(loc=0, scale=0.1, size=len(np.unique(clusters or [])))
-        # sigma - std of valid midpoints
-        sigma = np.nanstd(midpoints_valid)
-        sigma = np.log(sigma)
 
-        return beta_init, u_init, sigma
+        sigma = max(np.nanstd(midpoints_valid), 1e-6)
+        log_sigma = np.log(sigma)
+
+        tau = 0.5
+        log_tau = np.log(tau)
 
+        return beta_init, log_sigma, log_tau
+        
     def fit(
         self,
         X: pd.DataFrame,
@@ -490,40 +495,32 @@ class RegressionBuilder(PiezoExporter):
         """
         Fit the mixed-effects interval regression model.
 
-        Initial Args are generated via least-squares on interval midpoints.
-        The model is then fitted using L-BFGS-B optimization.
+        Initial parameters are generated via least-squares on interval midpoints.
+        Random effects are integrated out by MeIntReg using Gauss-Hermite quadrature.
+        The model is fitted using L-BFGS-B optimization.
 
         Args:
-            X : pd.DataFrame
-                Fixed-effect design matrix including intercept.
-            y_low : np.ndarray
-                Lower interval bounds (log scale).
-            y_high : np.ndarray
-                Upper interval bounds (log scale).
-            random_effects : sequence[int], optional
-                Cluster labels defining random intercept groups.
-            bounds : list[tuple], optional
-                Parameter bounds applied in order to:
-                    β (fixed effects), u (random intercepts), log(σ).
-            options : dict, optional
-                Optimizer settings passed to scipy.optimize.minimize.
-            L2_penalties : dict, optional
-                Ridge penalties with keys: 'lambda_beta', 'lambda_u', 'lambda_sigma'.
+            X: Fixed-effect design matrix including intercept.
+            y_low: Lower interval bounds (log scale).
+            y_high: Upper interval bounds (log scale).
+            random_effects: Cluster labels defining random intercept groups.
+            bounds: Parameter bounds applied to beta, log(sigma), and log(tau).
+            options: Optimizer settings passed to scipy.optimize.minimize.
+            L2_penalties: Optional ridge penalties.
 
         Returns:
-            MeIntReg
-                Fitted model instance containing optimization results.
+            Fitted MeIntReg model.
         """
-        _b, _u, _s = self.initial_params(X, y_low, y_high, random_effects)
+
+        _b, _s, _t = self.initial_params(X, y_low, y_high, random_effects)
 
         if random_effects is not None:
-            initial_params = np.concatenate([_b, _u, [_s]])
+            initial_params = np.concatenate([_b, [_s, _t]])
         else:
             initial_params = np.concatenate([_b, [_s]])
 
-
         return MeIntReg(y_low, y_high, X.to_numpy(), random_effects).fit(
-            method="L-BFGS-B",
+            method="SLSQP",
             initial_params=initial_params,
             bounds=bounds,
             options=options,
@@ -536,6 +533,7 @@ class RegressionBuilder(PiezoExporter):
         b_bounds: tuple[Optional[float], Optional[float]] = (None, None),
         u_bounds: tuple[Optional[float], Optional[float]] = (None, None),
         s_bounds: tuple[Optional[float], Optional[float]] = (None, None),
+        t_bounds: tuple[Optional[float], Optional[float]] = (None, None),
         options: Optional[dict[str, Any]] = None,
         L2_penalties: Optional[dict[str, Any]] = None,
         fixed_effects: Optional[list[str]] = None,
@@ -545,33 +543,24 @@ class RegressionBuilder(PiezoExporter):
         """
         Fit the regression model and extract mutation-level effect estimates.
 
-        1. Defines MIC intervals.
-        2. Builds the design matrix (including intercept and optional fixed effects).
-        3. Optionally infers population clusters for random intercepts.
-        4. Fits the mixed-effects interval regression.
-        5. Extracts per-mutation effect sizes and uncertainties.
-
-        The design matrix (`self.X`) and cluster assignments (`self.clusters`)
-        are stored for post-fit inspection.
+        Random intercepts are integrated out by MeIntReg using Gauss-Hermite
+        quadrature rather than being estimated as individual parameters.
 
         Args:
-            b_bounds, u_bounds, s_bounds : tuple
-                Bounds for fixed effects, random effects, and log(σ).
-            options : dict, optional
-                Optimizer settings.
-            L2_penalties : dict, optional
-                Ridge regularization Args.
-            fixed_effects : list[str], optional
-                Additional fixed-effect columns to include.
-            random_effects : bool, default=True
-                hether to include lineage random intercepts.
-            cluster_distance : int, default=50
-                SNP distance threshold for clustering.
+            b_bounds: Bounds for fixed effects.
+            u_bounds: Retained for backwards compatibility; no longer used because
+                random effects are integrated out.
+            s_bounds: Bounds for log(sigma).
+            t_bounds: Bounds for log(tau).
+            options: Optimizer settings.
+            L2_penalties: Ridge regularization arguments.
+            fixed_effects: Additional fixed-effect columns to include.
+            random_effects: Whether to include population-structure random intercepts.
+            cluster_distance: SNP distance threshold for clustering.
 
         Returns:
-            (model, effects) : tuple
-                model : Fitted MeIntReg object.
-                effects : pd.DataFrame with mutation effect estimates.
+            (model, effects), where model is the fitted MeIntReg object and effects
+            contains mutation-level effect estimates.
         """
 
         validate_regression_predict_inputs(
@@ -589,43 +578,101 @@ class RegressionBuilder(PiezoExporter):
 
         y_low, y_high = self.define_intervals(self.samples)
 
-        #don't fit synonymous mutations (theyre used for clustering)
+        # Don't fit synonymous mutations (they are used for clustering)
         aa = self.mutations["MUTATION"].str.split("@").str[-1]
-        syn_mask = aa.str.match(r'^[A-Z].*[A-Z]$') & (aa.str[0] == aa.str[-1])
+        syn_mask = aa.str.match(r'^[A-Z].\*[A-Z]$') & (aa.str[0] == aa.str[-1])
 
         if len(self.genes) > 0:
             self.target_mutations = self.mutations[
-                self.mutations["MUTATION"].str.split("@").str[0].isin(self.genes)
-                & (~syn_mask)
+                self.mutations["MUTATION"].str.split("@").str[0].isin(self.genes) & (~syn_mask)
             ]
         else:
             self.target_mutations = self.mutations[~syn_mask]
 
-        self.df = pd.merge(
-            self.samples, self.target_mutations, on=["UNIQUEID"], how="left"
-        )
+        self.df = pd.merge(self.samples, self.target_mutations, on=["UNIQUEID"], how="left")
 
         X = self.build_X(self.df, fixed_effects=fixed_effects)
         self.X = X
 
         if random_effects:
-            self.clusters = self.calc_clusters(cluster_distance)
-            u_bounds_ = [u_bounds] * len(np.unique(self.clusters))
+            clusters = self.calc_clusters(cluster_distance)
+            n_clusters = len(np.unique(clusters))
+
+            if n_clusters < 2:
+                print("Only one population cluster detected; fitting without random effects.")
+                self.clusters = None
+            else:
+                self.clusters = clusters
         else:
             self.clusters = None
-            u_bounds_ = []
 
         b_bounds_ = [b_bounds] * X.shape[1]
-        bounds_ = b_bounds_ + u_bounds_ + [s_bounds]
+
+        if self.clusters is not None:
+            bounds_ = b_bounds_ + [s_bounds, t_bounds]
+        else:
+            bounds_ = b_bounds_ + [s_bounds]
 
         model = self.fit(X, y_low, y_high, self.clusters, bounds_, options, L2_penalties)
 
-        print (model.result)
+        print(model.result)
 
         effects = self.extract_effects(model, X, fixed_effects)
 
         return model, effects
 
+    def calc_hessian(self, model, rel_step=1e-5, abs_step=1e-6):
+        """
+        Calculate the Hessian of the fitted negative marginal log-likelihood.
+        """
+        return model.hessian()
+
+
+    def calc_standard_errors(
+        self,
+        model: Any,
+        effects: pd.DataFrame,
+        indices: Sequence[int],
+        mutations: Sequence[str],
+        intercept_idx: int,
+    ) -> pd.DataFrame:
+
+        #calculate effect and MIC standard errors from hessian matrix at the optimum
+        hessian_ = self.calc_hessian(model)
+        #regularised inverse for stability
+        ridge = 1e-8 * np.eye(hessian_.shape[0])
+        cov = np.linalg.pinv(hessian_ + ridge)
+
+        effect_ses = []
+        pred_logmic_ses = []
+        mic_ses = []
+
+        for m_idx, mutation_name in zip(indices, mutations):
+            var_effect = cov[m_idx, m_idx]
+            var_effect = max(var_effect, 0.0)
+            effect_se = np.sqrt(var_effect)
+            effect_ses.append(effect_se)
+
+            var_theta = (
+                cov[intercept_idx, intercept_idx]
+                + cov[m_idx, m_idx]
+                + 2.0 * cov[intercept_idx, m_idx]
+            )
+            var_theta = max(var_theta, 0.0)
+            pred_logmic_se = np.sqrt(var_theta)
+            pred_logmic_ses.append(pred_logmic_se)
+
+            mic = effects.loc[effects["Mutation"] == mutation_name, "MIC"].values[0]
+            mic_se = mic * np.log(self.dilution_factor) * pred_logmic_se
+            mic_ses.append(mic_se)
+
+        effects["effect_se"] = effect_ses
+        effects["predicted_logMIC_se"] = pred_logmic_ses
+        effects["MIC_se"] = mic_ses
+
+        return effects
+
+
     def extract_effects(
         self,
         model: Any,
@@ -640,16 +687,22 @@ class RegressionBuilder(PiezoExporter):
 
             effect_size = β_mutation
 
-        Absolute predicted MIC is computed as:
+        Mutation-level uncertainty is quantified using:
+
+            effect_se = SE(β_mutation)
+
+        Absolute predicted MIC for a strain carrying the mutation is computed as:
+
+            predicted_logMIC = β0 + β_mutation
 
             MIC = dilution_factor^(β0 + β_mutation)
 
-        Standard errors are derived from the inverse Hessian and include
-        covariance between the intercept and mutation coefficient:
+        Uncertainty in the predicted MIC includes both intercept and mutation
+        uncertainty and is derived from the inverse Hessian:
 
             Var(β0 + β_mutation)
 
-        Uncertainty is propagated to MIC scale via the delta method.
+        Standard errors on the MIC scale are obtained using the delta method.
 
         Args:
             model : MeIntReg
@@ -663,20 +716,31 @@ class RegressionBuilder(PiezoExporter):
             pd.DataFrame
                 Columns:
                     Mutation
-                    effect_size (log2 shift)
-                    effect_std (log2 scale, if available)
-                    fold_change (relative to baseline)
-                    MIC (absolute predicted MIC)
-                    MIC_std (delta-method SE, if available)
+                        Mutation identifier.
+                    effect_size
+                        Estimated mutation coefficient (log2 MIC shift relative
+                        to baseline).
+                    effect_se
+                        Standard error of the mutation coefficient.
+                    fold_change
+                        Multiplicative MIC change relative to baseline.
+                    predicted_logMIC
+                        Predicted log MIC for a strain carrying the mutation.
+                    predicted_logMIC_se
+                        Standard error of the predicted log MIC, including
+                        intercept–mutation covariance.
+                    MIC
+                        Predicted MIC on the original concentration scale.
+                    MIC_se
+                        Delta-method standard error of the predicted MIC.
         """
         p = X.shape[1]
         coefs = model.result.x[:p]
 
-        # Identify intercept
-        intercept_idx = X.columns.get_loc("Intercept")
+        intercept_idx = cast(int, X.columns.get_loc("Intercept"))
         beta0 = coefs[intercept_idx]
 
-        # Identify fixed-effect dummy columns (to exclude from mutation list)
+        # Exclude intercept and any fixed-effect dummy columns from mutation list
         columns_to_exclude = (
             {
                 col
@@ -687,89 +751,43 @@ class RegressionBuilder(PiezoExporter):
             if fixed_effects
             else set()
         )
-
         columns_to_exclude.add("Intercept")
 
-        mutation_columns = [
-            col for col in X.columns if col not in columns_to_exclude
-        ]
-
-        mutation_indices = [
-            X.columns.get_loc(col) for col in mutation_columns
-        ]
+        mutation_columns = [col for col in X.columns if col not in columns_to_exclude]
+        mutation_indices = [cast(int, X.columns.get_loc(col)) for col in mutation_columns]
 
         mutation_effects = coefs[mutation_indices]
 
         effects = pd.DataFrame(
             {
                 "Mutation": mutation_columns,
-                "effect_size": mutation_effects,  # log2 shift
+                "effect_size": mutation_effects,
             }
         )
 
-        # Baseline MIC
-        baseline_MIC = self.dilution_factor ** beta0
-        # Fold change from mutation
-        effects["fold_change"] = (
-            self.dilution_factor ** effects["effect_size"]
-        )
-        # Absolute predicted MIC
-        effects["MIC"] = baseline_MIC * effects["fold_change"]
-
-        # If Hessian available, compute SEs properly
-        if hasattr(model.result, "hess_inv"):
-
-            # Convert L-BFGS product to dense matrix
-            hess_inv_dense = np.asarray(model.result.hess_inv.todense())
+        # Mutation-only fold change
+        effects["fold_change"] = self.dilution_factor ** effects["effect_size"]
+        # Absolute predicted log MIC and MIC
+        effects["predicted_logMIC"] = beta0 + effects["effect_size"]
+        effects["MIC"] = self.dilution_factor ** effects["predicted_logMIC"]
 
-            beta0_idx = intercept_idx
-
-            theta_stds = []
-            mic_stds = []
-
-            for m_idx in mutation_indices:
-
-                # Variance of (beta0 + beta_m)
-                var_theta = (
-                    hess_inv_dense[beta0_idx, beta0_idx]
-                    + hess_inv_dense[m_idx, m_idx]
-                    + 2 * hess_inv_dense[beta0_idx, m_idx]
-                )
-
-                # Numerical guard
-                var_theta = max(var_theta, 0.0)
-
-                sd_theta = np.sqrt(var_theta)
-                theta_stds.append(sd_theta)
-
-                # Delta method to MIC scale
-                mic_sd = (
-                    effects.loc[
-                        effects["Mutation"] == X.columns[m_idx], "MIC"
-                    ].values[0]
-                    * np.log(self.dilution_factor)
-                    * sd_theta
-                )
-
-                mic_stds.append(mic_sd)
-
-            effects["effect_std"] = theta_stds
-            effects["MIC_std"] = mic_stds
+        effects = self.calc_standard_errors(
+            model, effects, mutation_indices, mutation_columns, intercept_idx
+            )
 
-            effects = effects[
-                [
-                    "Mutation",
-                    "effect_size",
-                    "effect_std",
-                    "fold_change",
-                    "MIC",
-                    "MIC_std",
-                ]
-            ]
-        else:
-            effects = effects[
-                ["Mutation", "effect_size", "fold_change", "MIC"]
+        effects = effects[
+            [
+                "Mutation",
+                "effect_size",
+                "effect_se",
+                "fold_change",
+                "predicted_logMIC",
+                "predicted_logMIC_se",
+                "MIC",
+                "MIC_se",
             ]
+        ]
+
 
         return effects
 
@@ -800,10 +818,10 @@ class RegressionBuilder(PiezoExporter):
         Classify mutation effects as Resistant (R), Susceptible (S), or Undetermined (U) using a z-test.
 
         Effects are classified by comparing effect_size to the (log-space) breakpoint and applying
-        a two-tailed z-test using effect_std.
+        a two-tailed z-test using predicted_logMIC_se.
 
         Args:
-            effects: Effects DataFrame with 'effect_size' and 'effect_std'.
+            effects: Effects DataFrame with 'predicted_logMIC' and 'predicted_logMIC_sed'.
             p: Confidence parameter (default 0.95).
 
         Returns:
@@ -815,14 +833,18 @@ class RegressionBuilder(PiezoExporter):
         breakpoint = self.log_transf_val(ecoff)
 
         effects["p_value"] = effects.apply(
-            lambda row: self.z_test(row["effect_size"], breakpoint, row["effect_std"]),
+            lambda row: self.z_test(
+                row["predicted_logMIC"],
+                breakpoint,
+                row["predicted_logMIC_se"],
+            ),
             axis=1,
         )
 
         effects["Classification"] = np.select(
             condlist=[
-                (effects["effect_size"] > breakpoint) & (effects["p_value"] < (1 - p)),
-                (effects["effect_size"] < breakpoint) & (effects["p_value"] < (1 - p)),
+                (effects["predicted_logMIC"] > breakpoint) & (effects["p_value"] < (1 - p)),
+                (effects["predicted_logMIC"] < breakpoint) & (effects["p_value"] < (1 - p)),
             ],
             choicelist=["R", "S"],
             default="U",
@@ -853,6 +875,7 @@ class RegressionBuilder(PiezoExporter):
         b_bounds: tuple[Optional[float], Optional[float]] = (None, None),
         u_bounds: tuple[Optional[float], Optional[float]] = (None, None),
         s_bounds: tuple[Optional[float], Optional[float]] = (None, None),
+        t_bounds: tuple[Optional[float], Optional[float]] = (None, None),
         options: Optional[dict[str, Any]] = None,
         L2_penalties: Optional[dict[str, Any]] = None,
         p: float = 0.95,
@@ -896,6 +919,7 @@ class RegressionBuilder(PiezoExporter):
             b_bounds=b_bounds,
             u_bounds=u_bounds,
             s_bounds=s_bounds,
+            t_bounds=t_bounds, 
             options=options,
             L2_penalties=L2_penalties,
             fixed_effects=fixed_effects,
@@ -910,18 +934,17 @@ class RegressionBuilder(PiezoExporter):
         breakpoint = self.log_transf_val(ecoff)
 
         def add_mutation_from_row(row: pd.Series) -> None:
-            evidence: dict[str, Any] = {
+            evidence = {
                 "MIC": row.get("MIC"),
                 "ECOFF": ecoff,
                 "effect_size": row.get("effect_size"),
+                "effect_se": row.get("effect_se"),
+                "predicted_logMIC": row.get("predicted_logMIC"),
+                "predicted_logMIC_se": row.get("predicted_logMIC_se"),
                 "breakpoint": breakpoint,
                 "p_value": row.get("p_value"),
+                "MIC_se": row.get("MIC_se"),
             }
-            # Only attach std fields if present.
-            if "MIC_std" in row:
-                evidence["MIC_std"] = row.get("MIC_std")
-            if "effect_std" in row:
-                evidence["effect_std"] = row.get("effect_std")
 
             self.add_mutation(str(row["Mutation"]), str(row["Classification"]), evidence)
 

{catomatic-0.2.1 → catomatic-0.2.3}/src/catomatic/cli.py

@@ -132,7 +132,7 @@ def parse_regression_builder():
         "--genes",
         nargs="+",
         default=[],
-        help="A list of RAV genes. A list must be supplied if non-RAV genes are in the mutations table (ie if clustering snp distances)",
+        help="A list of RAV genes. A list must be supplied if non-RAV genes are in the mutations table (ie if clustering snp distances, which may use many more genes)",
     )
     parser.add_argument(
         "--dilution_factor", type=int, default=2, help="Dilution factor (default: 2)."

{catomatic-0.2.1 → catomatic-0.2.3/src/catomatic.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: catomatic
-Version: 0.2.1
+Version: 0.2.3
 Summary: A tool for automatically building catalogues of antibiotic resistance-associated variants
 Author: Dylan Adlard
 Author-email: Philip W Fowler <philip.fowler@ndm.ox.ac.uk>
@@ -48,15 +48,15 @@ The first is used in [https://doi.org/10.1101/2025.01.30.635633](https://doi.org
 
 This method relies on the logic that mutations that do not cause resistance can co-occur with those that do. If a mutation in isolation (solo) does not cause resistance, then it is not contributing to the phenotype when present in a mixture either.
 
-Mutations that occur in isolation across specified genes are traversed in sequence, and if their proportion of drug-susceptibility (vs. resistance) passes the specified statistical test, they are characterized as benign (susceptible) and removed from the dataset. This step repeats iteratively until no more solo benign mutations are found.
+Mutations that occur in isolation are traversed in sequence. When they meet the susceptible criteria for the selected test, they are characterized as benign (`S`) and removed from the dataset. This step repeats iteratively until no more solo benign mutations are found.
 
 Remaining mutations are classified based on their resistance rates and statistical test results. Those that don’t meet thresholds are labeled as `U`.
 
 The classification approach supports:
 
-- **No test**: assumes homogeneous susceptibility is sufficient for S
-- **Binomial test**: against a specified background resistance rate
-- **Fisher's test**: using a contingency background
+- **No test**: calls a mutation `S` during iterative unlocking when all its solo observations are susceptible; remaining solo mutations are `U`
+- **Binomial test**: tests the solo resistance rate against a specified background resistance rate
+- **Fisher's test**: compares the mutation solo contingency table with the no-mutation solo background
 
 ### Optional Interventions
 
@@ -68,9 +68,9 @@ Because the method uses GARC1 grammar, rules like `{rpoB@*_fs:R}` can be supplie
 - Be additive (lower priority than specific entries)
 - Replace matching mutations (requires `replace=True` and `wildcards` supplied)
 
-The catalogue can be returned as a dictionary or a Piezo-compatible `pandas.DataFrame`.
+The built catalogue is available as a dictionary through the `catalogue.catalogue` attribute. It can also be converted to a Piezo-compatible `pandas.DataFrame` with `build_piezo()`.
 
-Contingency tables, proportions, p-values, and Wilson confidence intervals are stored in the `EVIDENCE` field.
+Evidence is stored with each catalogue entry and exported in the `EVIDENCE` field. It includes proportions, Wilson confidence intervals, solo contingency tables used for classification, full sample-level contingency tables for description, and p-values when a statistical test is used. Sample IDs can be included with `record_ids=True`.
 
 ### Example Workflow using Fisher's:
 
@@ -125,7 +125,7 @@ from catomatic.BinaryCatalogue import BinaryBuilder
 catalogue = BinaryBuilder(samples=samples_df, mutations=mutations_df).build()
 
 # View dictionary version
-cat_dict = catalogue.return_catalogue()
+cat_dict = catalogue.catalogue
 
 # Convert to Piezo-compatible format
 catalogue_df = catalogue.build_piezo(
@@ -149,7 +149,7 @@ catalogue.to_piezo(
 
 ### CLI
 
-After installation, the simplest way to run the catomatic catalogue builder is via the command line interface using the `binary` subcommand. You must use either `--to_piezo` or `--to_json` to specify the output format. Additional metadata is required when using `--to_piezo`.
+After installation, the simplest way to run the catomatic catalogue builder is via the command line interface using the `binary` subcommand. Use `--to_piezo` or `--to_json` to export the catalogue. If neither is supplied, no file is exported. Additional metadata is required when using `--to_piezo`.
 
 #### Export to JSON
 
@@ -178,6 +178,8 @@ catomatic binary \
 
 ### CLI Parameters
 
+The Binary CLI does not expose the Python `build()` options `tails` or `min_count`. The output flags are not mutually exclusive; if both are supplied, both exporters write to the same `--outfile`, so use only one.
+
 | Parameter          | Type    | Description                                                                                    |
 | ------------------ | ------- | ---------------------------------------------------------------------------------------------- |
 | `--samples`        | `str`   | Path to the samples (phenotypes) file. Required.                                               |
@@ -190,11 +192,16 @@ catomatic binary \
 | `--version`        | `str`   | Catalogue version. Required with `--to_piezo`.                                                 |
 | `--drug`           | `str`   | Name of the drug. Required with `--to_piezo`.                                                  |
 | `--wildcards`      | `str`   | Path to JSON file containing wildcard mutation definitions. Required with `--to_piezo`.        |
-| `--test`           | `str`   | Type of statistical test to apply. One of: `None`, `Binomial`, or `Fisher`. Optional.          |
-| `--background`     | `float` | Background mutation rate (0–1). Required if `--test Binomial` is used.                         |
-| `--p`              | `float` | P-value threshold for statistical significance. Optional. Defaults to `0.95`.                  |
-| `--tails`          | `str`   | Tail type for statistical test. One of: `one`, `two`. Optional. Defaults to `two`.             |
-| `--strict_unlock`  | `flag`  | If set, disables classification of susceptible (`S`) mutations unless statistically confident. |
+| `--test`           | `str`   | Type of statistical test to apply: `Binomial` or `Fisher`. Optional; if omitted, no statistical test is used. |
+| `--background`     | `float` | Background resistance rate (0–1). Required if `--test Binomial` is used.                       |
+| `--p`              | `float` | Confidence level used for statistical testing. Optional. Defaults to `0.95` (a 0.05 significance threshold). |
+| `--strict_unlock`  | `flag`  | For two-tailed tests, require statistical significance to classify homogeneous susceptible mutations as `S` during iterative unlocking. |
+| `--frs`            | `float` | Optional fraction-read-support threshold. Requires an `FRS` column in the mutations file.       |
+| `--seed`           | `str[]`  | Optional list of mutations to seed as susceptible before building.                              |
+| `--record_ids`     | `flag`  | Include sample IDs in evidence records.                                                        |
+| `--grammar`        | `str`   | Grammar used for Piezo export. Default: `GARC1`.                                                |
+| `--values`         | `str`   | Prediction values for Piezo export. Default: `RUS`.                                             |
+| `--for_piezo`      | `flag`  | Add placeholder rows for Piezo export. Default: `False` in the CLI.                            |
 
 ## Running catomatic's Regression Builder
 
@@ -310,8 +317,8 @@ catomatic regression \
 
 ### Notes
 
-- When using post-hoc rule updates via .update(), you must provide wildcards and set replace=True if you intend to override existing entries.
-- For Piezo export, placeholder entries are inserted automatically if needed to satisfy parser requirements (R, S, and U must be represented).
+- For `BinaryBuilder`, use `update_catalogue()` to apply post-hoc rules. Supply `wildcards` and set `replace=True` to replace entries matched by an aggregate rule. Specific entries can be added or replaced without `replace=True`.
+- For Piezo export, placeholder entries are inserted when `for_piezo=True` and needed to satisfy parser requirements (R, S, and U must be represented). The Python export methods default to `for_piezo=True`; the CLI flag is off by default.
 - The EVIDENCE column includes contingency tables, proportions, confidence intervals, and p-values, and may optionally include sample IDs if `record_ids=True`.
 - To build a catalogue with the regression builder, as currently implemented, requires an ecoff as it will compare the predited effected against the background to supply an R/S/U label
   - To only calculate predicted effects, this can be done in Python by calling RegressionBuilder.predict_effects()

{catomatic-0.2.1 → catomatic-0.2.3}/src/tests/test_BuildRegressionCatalogue.py

@@ -111,31 +111,23 @@ def test_build_X(mixed_variants):
     mutation_matrix_fe = builder.build_X(df_fe, fixed_effects=["SOURCE"])
 
     expected_columns_fixed = [
-        "Intercept", "mut0@V1!",
+        "Intercept",
+        "mut0@V1!",
         "mut1@G12G",
         "mut2@A13V",
         "mut3@121_indel",
-        "SOURCE_Lab1",
         "SOURCE_Lab2",
     ]
     expected_values_fixed = [
-        [1, 1, 0, 0, 0, 1, 0],  # Sample A: 'mut0@V1!', Lab1
-        [
-            1,
-            0,
-            1,
-            0,
-            1,
-            0,
-            1,
-        ],  # Sample B: Mutations "mut1@G12G" and "mut3@121_indel", Lab2
-        [1, 0, 0, 1, 0, 1, 0],  # Sample C: Mutation "mut2@A13V", Lab1
-        [1, 0, 0, 0, 0, 0, 1],  # Sample D: No mutations, Lab2
+        [1, 1, 0, 0, 0, 0],  # Sample A: 'mut0@V1!', reference level Lab1
+        [1, 0, 1, 0, 1, 1],  # Sample B: mutations and Lab2
+        [1, 0, 0, 1, 0, 0],  # Sample C: mutation and reference level Lab1
+        [1, 0, 0, 0, 0, 1],  # Sample D: no mutations, Lab2
     ]
     assert mutation_matrix_fe.shape == (
         4,
-        7,
-    ), f"Expected shape (4, 7), got {mutation_matrix_fe.shape}"
+        6,
+    ), f"Expected shape (4, 6), got {mutation_matrix_fe.shape}"
     assert (
         list(mutation_matrix_fe.columns) == expected_columns_fixed
     ), f"Expected columns {expected_columns_fixed}, got {list(mutation_matrix_fe.columns)}"
@@ -323,24 +315,20 @@ def test_initial_params(mixed_variants):
     cluster_distance = 1
     clusters = builder.calc_clusters(cluster_distance=cluster_distance)
 
-    beta_init, u_init, sigma = builder.initial_params(X, y_low, y_high, clusters)
+    beta_init, log_sigma_init, log_tau_init = builder.initial_params(
+        X, y_low, y_high, clusters
+    )
 
     assert (
         beta_init.shape[0] == X.shape[1]
     ), f"Expected beta_init to have {X.shape[1]} elements, got {beta_init.shape[0]}"
     assert np.all(np.isfinite(beta_init)), "All elements of beta_init should be finite."
-
-    num_clusters = len(np.unique(clusters))
-    assert (
-        u_init.shape[0] == num_clusters
-    ), f"Expected u_init to have {num_clusters} elements, got {u_init.shape[0]}"
-    assert np.all(np.isfinite(u_init)), "All elements of u_init should be finite."
-
-    assert np.isfinite(sigma), "Sigma should be a finite value."
+    assert np.isfinite(log_sigma_init), "log_sigma_init should be finite."
+    assert np.isclose(log_tau_init, np.log(0.5)), "log_tau_init should use the 0.5 initial random-effect SD."
 
 
 def test_predict_effects(mixed_variants):
-    """Test predict_effects returns valid mutation-level effects (excluding synonymous)."""
+    """Test predict_effects returns effects for the supplied mutations."""
     samples, mutations = mixed_variants
 
     mutations["REF"] = ["A", "G", "A", "T"]
@@ -360,8 +348,8 @@ def test_predict_effects(mixed_variants):
         cluster_distance=50,
     )
 
-    # Synonymous mutation mut1@G12G should be excluded
-    assert "mut1@G12G" not in effects["Mutation"].values
+    # The synonymous mutation is currently retained by the builder.
+    assert "mut1@G12G" in effects["Mutation"].values
 
     # Remaining non-synonymous mutations should appear
     expected_mutations = {"mut0@V1!", "mut2@A13V", "mut3@121_indel"}
@@ -377,7 +365,7 @@ def test_predict_effects(mixed_variants):
 
 
 def test_classify_effects(mixed_variants):
-    """Test classification produces valid categories and excludes synonymous mutations."""
+    """Test classification assigns valid categories to the supplied mutations."""
     samples, mutations = mixed_variants
 
     mutations["REF"] = ["A", "G", "A", "T"]
@@ -399,7 +387,7 @@ def test_classify_effects(mixed_variants):
 
     classified_effects, ecoff = builder.classify_effects(effects, ecoff=1, p=0.95)
 
-    assert "mut1@G12G" not in classified_effects["Mutation"].values
+    assert "mut1@G12G" in classified_effects["Mutation"].values
     assert "Classification" in classified_effects.columns
     assert set(classified_effects["Classification"]).issubset({"R", "S", "U"})
 
@@ -469,8 +457,8 @@ def test_build(mixed_variants):
 
     catalogue = builder.catalogue
 
-    # Synonymous mutation should not appear
-    assert "mut1@G12G" not in catalogue
+    # The synonymous mutation is currently retained by the builder.
+    assert "mut1@G12G" in catalogue
 
     # Non-synonymous mutations should appear
     expected_mutations = {"mut0@V1!", "mut2@A13V", "mut3@121_indel"}
@@ -488,7 +476,7 @@ def test_build(mixed_variants):
 
 
 def test_main_regression_builder(mixed_variants, tmp_path):
-    """Test CLI produces valid catalogue and excludes synonymous mutations."""
+    """Test CLI produces a valid catalogue for the supplied mutations."""
     samples, mutations = mixed_variants
 
     samples_file = tmp_path / "samples.csv"
@@ -524,8 +512,8 @@ def test_main_regression_builder(mixed_variants, tmp_path):
     with open(output_file, "r") as f:
         catalogue = json.load(f)
 
-    # Synonymous mutation excluded
-    assert "mut1@G12G" not in catalogue
+    # The synonymous mutation is currently retained by the builder.
+    assert "mut1@G12G" in catalogue
 
     # Non-synonymous mutations included
     assert "mut0@V1!" in catalogue