|
| 1 | +""" |
| 2 | +Kinetic flux analysis for multivariant metabolism_redux_classic simulations. |
| 3 | +
|
| 4 | +Two rows of faceted subplots, one column per variant: |
| 5 | + Top row: Scatter — per-reaction log10(avg kinetic target + ε) vs |
| 6 | + log10(avg estimated kinetic flux + ε) in mmol/(L·h), with a |
| 7 | + dashed y=x reference line and Pearson R² / R²-to-y=x annotation. |
| 8 | + Bottom row: Line — weighted kinetic objective term over continuous simulation |
| 9 | + time, broken at cell division. |
| 10 | +
|
| 11 | +Variant panels are labeled with the fraction_kinetic_target value when |
| 12 | +available from variant_metadata. |
| 13 | +""" |
| 14 | + |
| 15 | +from __future__ import annotations |
| 16 | + |
| 17 | +import os |
| 18 | +from typing import Any, TYPE_CHECKING |
| 19 | + |
| 20 | +import altair as alt |
| 21 | +import numpy as np |
| 22 | +import plotly.express as px |
| 23 | +import polars as pl |
| 24 | + |
| 25 | +from ecoli.analysis.multivariant import _variant_label |
| 26 | +from ecoli.library.parquet_emitter import ( |
| 27 | + field_metadata, |
| 28 | + ndlist_to_ndarray, |
| 29 | + read_stacked_columns, |
| 30 | +) |
| 31 | + |
| 32 | +if TYPE_CHECKING: |
| 33 | + from duckdb import DuckDBPyConnection |
| 34 | + |
| 35 | +alt.data_transformers.enable("vegafusion") |
| 36 | + |
| 37 | +PASTEL = px.colors.qualitative.Pastel |
| 38 | + |
| 39 | +# Tolerance added before log10 to handle zero fluxes |
| 40 | +LOG_EPS = 1e-8 |
| 41 | +# Seconds per hour — converts mmol/(L·s) → mmol/(L·h) |
| 42 | +S_PER_HR = 3600.0 |
| 43 | +FLUX_UNIT_STR = "mmol/(L·h)" |
| 44 | + |
| 45 | + |
| 46 | +def plot( |
| 47 | + params: dict[str, Any], |
| 48 | + conn: "DuckDBPyConnection", |
| 49 | + history_sql: str, |
| 50 | + config_sql: str, |
| 51 | + success_sql: str, |
| 52 | + sim_data_dict: dict[str, dict[int, str]], |
| 53 | + validation_data_paths: list[str], |
| 54 | + outdir: str, |
| 55 | + variant_metadata: dict[str, dict[int, Any]], |
| 56 | + variant_names: dict[str, str], |
| 57 | +) -> None: |
| 58 | + """ |
| 59 | + Faceted scatter (log avg kinetic target vs log avg kinetic flux) and |
| 60 | + kinetic term over time, one column per variant. |
| 61 | + """ |
| 62 | + # ── Resolve per-variant parameter dicts ─────────────────────────────────── |
| 63 | + experiment_id = next(iter(variant_metadata.keys()), None) |
| 64 | + per_variant_params: dict[int, Any] = ( |
| 65 | + variant_metadata[experiment_id] if experiment_id else {} |
| 66 | + ) |
| 67 | + |
| 68 | + # ── Metadata: reaction name lists ───────────────────────────────────────── |
| 69 | + kinetic_rxn_names: list[str] = field_metadata( |
| 70 | + conn, config_sql, "listeners__fba_results__target_kinetic_fluxes" |
| 71 | + ) |
| 72 | + all_rxn_names: list[str] = field_metadata( |
| 73 | + conn, config_sql, "listeners__fba_results__solution_fluxes" |
| 74 | + ) |
| 75 | + kinetic_indices = np.array( |
| 76 | + [all_rxn_names.index(name) for name in kinetic_rxn_names], dtype=int |
| 77 | + ) |
| 78 | + |
| 79 | + # ── Load raw listener data ───────────────────────────────────────────────── |
| 80 | + raw = pl.DataFrame( |
| 81 | + read_stacked_columns( |
| 82 | + history_sql, |
| 83 | + [ |
| 84 | + "listeners__fba_results__target_kinetic_fluxes AS target_kinetic_fluxes", |
| 85 | + "listeners__fba_results__estimated_fluxes AS estimated_fluxes", |
| 86 | + "listeners__fba_results__kinetics_term AS kinetics_term", |
| 87 | + "listeners__enzyme_kinetics__counts_to_molar AS counts_to_molar", |
| 88 | + ], |
| 89 | + order_results=True, |
| 90 | + conn=conn, |
| 91 | + remove_first=True, |
| 92 | + ) |
| 93 | + ) |
| 94 | + |
| 95 | + if raw.is_empty(): |
| 96 | + print("kinetic_flux_analysis: no rows returned; skipping.") |
| 97 | + return |
| 98 | + |
| 99 | + # Continuous relative time per lineage_seed |
| 100 | + min_t = raw.group_by(["lineage_seed"]).agg(pl.col("time").min().alias("t_min")) |
| 101 | + raw = raw.join(min_t, on=["lineage_seed"]) |
| 102 | + raw = raw.with_columns( |
| 103 | + ((pl.col("time") - pl.col("t_min")) / 60).alias("Time (min)") |
| 104 | + ) |
| 105 | + |
| 106 | + # ── Variant label mapping ────────────────────────────────────────────────── |
| 107 | + unique_variants: list[int] = sorted(raw["variant"].unique().to_list()) |
| 108 | + |
| 109 | + def _make_label(v: int) -> str: |
| 110 | + raw_label = _variant_label(v, per_variant_params) |
| 111 | + return " ".join(raw_label) if isinstance(raw_label, list) else raw_label |
| 112 | + |
| 113 | + variant_label_map = {v: _make_label(v) for v in unique_variants} |
| 114 | + variant_labels = [variant_label_map[v] for v in unique_variants] |
| 115 | + color_range = PASTEL[: len(unique_variants)] |
| 116 | + color_scale = alt.Scale(domain=variant_labels, range=color_range) |
| 117 | + |
| 118 | + # ── Numpy arrays ────────────────────────────────────────────────────────── |
| 119 | + target_arr = ndlist_to_ndarray(raw["target_kinetic_fluxes"]) # (T, n_kinetic) |
| 120 | + estimated_arr = ndlist_to_ndarray(raw["estimated_fluxes"]) # (T, n_all_rxns) |
| 121 | + kinetic_flux_arr = estimated_arr[:, kinetic_indices] # (T, n_kinetic) |
| 122 | + # counts_to_molar [mmol/L per count]; multiply by S_PER_HR to get mmol/(L·h) |
| 123 | + counts_to_molar = raw["counts_to_molar"].to_numpy()[:, np.newaxis] * S_PER_HR |
| 124 | + variants_col = np.array(raw["variant"].to_list()) |
| 125 | + |
| 126 | + # ── Build scatter DataFrame ──────────────────────────────────────────────── |
| 127 | + # Each data row is one (reaction, variant) pair averaged over all timesteps. |
| 128 | + # Two extra rows per variant encode the y=x reference line endpoints on the |
| 129 | + # log-transformed axes. |
| 130 | + scatter_rows: list[dict] = [] |
| 131 | + for v in unique_variants: |
| 132 | + label = variant_label_map[v] |
| 133 | + mask = variants_col == v |
| 134 | + ctm = counts_to_molar[mask] # (T_v, 1) |
| 135 | + mean_target = (target_arr[mask] * ctm).mean(axis=0) # mmol/(L·h) |
| 136 | + mean_flux = (kinetic_flux_arr[mask] * ctm).mean(axis=0) |
| 137 | + |
| 138 | + log_target = np.log10(mean_target + LOG_EPS) |
| 139 | + log_flux = np.log10(mean_flux + LOG_EPS) |
| 140 | + |
| 141 | + # R² metrics computed on log-space values |
| 142 | + ss_res = np.sum((log_flux - log_target) ** 2) |
| 143 | + ss_tot = np.sum((log_target - log_target.mean()) ** 2) |
| 144 | + r2_to_yx = float(1 - ss_res / ss_tot) if ss_tot > 0 else float("nan") |
| 145 | + pearson_r2 = float(np.corrcoef(log_flux, log_target)[0, 1]) ** 2 |
| 146 | + |
| 147 | + for i, rxn in enumerate(kinetic_rxn_names): |
| 148 | + scatter_rows.append( |
| 149 | + { |
| 150 | + "Reaction": rxn, |
| 151 | + "log_target": float(log_target[i]), |
| 152 | + "log_flux": float(log_flux[i]), |
| 153 | + "Variant": label, |
| 154 | + "r2_to_yx": r2_to_yx, |
| 155 | + "pearson_r2": pearson_r2, |
| 156 | + "is_ref": False, |
| 157 | + } |
| 158 | + ) |
| 159 | + |
| 160 | + # y=x reference line endpoints in log space for this variant's scale |
| 161 | + ref_lo = float(min(log_target.min(), log_flux.min())) |
| 162 | + ref_hi = float(max(log_target.max(), log_flux.max())) |
| 163 | + for ref_val in (ref_lo, ref_hi): |
| 164 | + scatter_rows.append( |
| 165 | + { |
| 166 | + "Reaction": f"_ref_{ref_val}", |
| 167 | + "log_target": ref_val, |
| 168 | + "log_flux": ref_val, |
| 169 | + "Variant": label, |
| 170 | + "r2_to_yx": r2_to_yx, |
| 171 | + "pearson_r2": pearson_r2, |
| 172 | + "is_ref": True, |
| 173 | + } |
| 174 | + ) |
| 175 | + |
| 176 | + scatter_df = pl.DataFrame(scatter_rows).to_pandas() |
| 177 | + |
| 178 | + log_axis_title_x = f"log₁₀(Mean Kinetic Target + ε) [{FLUX_UNIT_STR}]" |
| 179 | + log_axis_title_y = f"log₁₀(Mean Kinetic Flux + ε) [{FLUX_UNIT_STR}]" |
| 180 | + |
| 181 | + # ── Scatter layer definitions ────────────────────────────────────────────── |
| 182 | + ref_line = ( |
| 183 | + alt.Chart() |
| 184 | + .mark_line(color="lightgray", strokeDash=[5, 4], strokeWidth=1.2) |
| 185 | + .transform_filter("datum.is_ref") |
| 186 | + .encode( |
| 187 | + x=alt.X("log_target:Q"), |
| 188 | + y=alt.Y("log_flux:Q"), |
| 189 | + ) |
| 190 | + ) |
| 191 | + |
| 192 | + scatter_pts = ( |
| 193 | + alt.Chart() |
| 194 | + .mark_circle(size=55, opacity=0.75) |
| 195 | + .transform_filter("!datum.is_ref") |
| 196 | + .encode( |
| 197 | + x=alt.X("log_target:Q", title=log_axis_title_x), |
| 198 | + y=alt.Y("log_flux:Q", title=log_axis_title_y), |
| 199 | + color=alt.Color("Variant:N", scale=color_scale, legend=None), |
| 200 | + tooltip=[ |
| 201 | + alt.Tooltip("Reaction:N"), |
| 202 | + alt.Tooltip("Variant:N"), |
| 203 | + alt.Tooltip("log_target:Q", title="log₁₀(target)", format=".3f"), |
| 204 | + alt.Tooltip("log_flux:Q", title="log₁₀(flux)", format=".3f"), |
| 205 | + ], |
| 206 | + ) |
| 207 | + ) |
| 208 | + |
| 209 | + annotation = ( |
| 210 | + alt.Chart() |
| 211 | + .mark_text( |
| 212 | + lineBreak="\n", |
| 213 | + align="left", |
| 214 | + baseline="top", |
| 215 | + dx=5, |
| 216 | + dy=5, |
| 217 | + fontSize=10, |
| 218 | + ) |
| 219 | + .transform_filter("!datum.is_ref") |
| 220 | + .transform_aggregate( |
| 221 | + pearson_r2="mean(pearson_r2)", |
| 222 | + r2_to_yx="mean(r2_to_yx)", |
| 223 | + groupby=["Variant"], |
| 224 | + ) |
| 225 | + .transform_calculate( |
| 226 | + annotation_label=( |
| 227 | + "'Pearson R\u00b2 = ' + format(datum.pearson_r2, '.2f') + '\\n'" |
| 228 | + "+ 'R\u00b2 to y=x = ' + format(datum.r2_to_yx, '.2f')" |
| 229 | + ) |
| 230 | + ) |
| 231 | + .encode( |
| 232 | + x=alt.value(5), |
| 233 | + y=alt.value(5), |
| 234 | + text="annotation_label:N", |
| 235 | + ) |
| 236 | + ) |
| 237 | + |
| 238 | + num_cols = min(len(unique_variants), 4) |
| 239 | + |
| 240 | + scatter_faceted = ( |
| 241 | + alt.layer(ref_line, scatter_pts, annotation, data=scatter_df) |
| 242 | + .properties(width=280, height=280) |
| 243 | + .facet( |
| 244 | + facet=alt.Facet("Variant:N", title="Variant"), |
| 245 | + columns=num_cols, |
| 246 | + ) |
| 247 | + .resolve_scale(x="independent", y="independent") |
| 248 | + .properties( |
| 249 | + title=f"log₁₀(Avg Kinetic Target + ε) vs log₁₀(Avg Estimated Flux + ε) [ε={LOG_EPS}]" |
| 250 | + ) |
| 251 | + ) |
| 252 | + |
| 253 | + # ── Line-plot DataFrame ──────────────────────────────────────────────────── |
| 254 | + variant_label_col = [variant_label_map[v] for v in raw["variant"].to_list()] |
| 255 | + line_df = ( |
| 256 | + raw.select(["Time (min)", "generation", "lineage_seed", "kinetics_term"]) |
| 257 | + .with_columns(pl.Series("Variant", variant_label_col)) |
| 258 | + .to_pandas() |
| 259 | + ) |
| 260 | + |
| 261 | + line_faceted = ( |
| 262 | + alt.Chart(line_df) |
| 263 | + .mark_line(strokeWidth=1.3, opacity=0.85) |
| 264 | + .encode( |
| 265 | + x=alt.X("Time (min):Q", title="Time (min)"), |
| 266 | + y=alt.Y("mean(kinetics_term):Q", title="Unweighted Kinetic Term"), |
| 267 | + color=alt.Color("Variant:N", scale=color_scale, legend=None), |
| 268 | + detail=alt.Detail("generation:N"), |
| 269 | + ) |
| 270 | + .properties(width=280, height=200) |
| 271 | + .facet( |
| 272 | + facet=alt.Facet("Variant:N", title="Variant"), |
| 273 | + columns=num_cols, |
| 274 | + ) |
| 275 | + .resolve_scale(x="independent", y="independent") |
| 276 | + .properties(title="Kinetic Objective Term Over Time") |
| 277 | + ) |
| 278 | + |
| 279 | + # ── Combine into faceted 2-row layout ───────────────────────────────────── |
| 280 | + final = ( |
| 281 | + alt.vconcat(scatter_faceted, line_faceted) |
| 282 | + .resolve_scale(color="shared") |
| 283 | + .properties(title="Kinetic Flux Analysis by Variant") |
| 284 | + ) |
| 285 | + |
| 286 | + out_path = os.path.join(outdir, "kinetic_flux_analysis.html") |
| 287 | + final.save(out_path) |
| 288 | + print(f"Saved kinetic flux analysis to: {out_path}") |
0 commit comments