Notes: OptimizationResults initials vs parameters; CSV refresh; label truncation

[SHMAKI]

First of all, thank you for maintaining biomass and the sample models.

Summary

• Initial values labeled init_XXX appear alongside parameters and can be confused with constants (e.g., C.init_EGFR in pan_rtk).
• to_csv() allocates with dtype='<U21' → long labels get truncated.
• savefig() reuses an existing CSV → plots can be stale unless to_csv() is called first.
• Docstring says two CSVs, but implementation writes one.
• I’m not requesting changes; I’m sharing these observations in case they’re useful.

Details (env, context, repro, proposals)

Module: biomass.result.OptimizationResults
Version: biomass==0.14.0
Environment: Python 3.12, OS macOS, matplotlib 3.10.5, seaborn 0.13.2

Context
While visualizing estimated parameter sets with OptimizationResults, I ran into two classes of issues:

UX/consistency

• to_csv() writes initial values with the init_ prefix (e.g., init_EGFR) and parameters side-by-side in the same CSV.
• When plotted via savefig(), initials appear alongside parameters and can be mistaken for constants defined in the base model (e.g., parameter name C.init_EGFR vs initial-value label init_EGFR). They are conceptually different but look very similar in the figure.
• Example: the sample model pan_rtk (https://github.com/biomass-dev/biomass/tree/master/biomass/models/pan_rtk) includes a constant/parameter named C.init_EGFR, which can easily be confused with init_EGFR produced by to_csv() for the species initial value.

Technical

• to_csv() allocates the CSV buffer with dtype='<U21', so long labels are truncated (including init_... names).
• savefig() reuses an existing CSV if present. If the model or indices changed, it’s easy to get stale plots unless users remember to call to_csv() manually.
• The to_csv() docstring mentions two files:

optimization_results/optimized_params.csv
optimization_results/optimized_initials.csv

but the current implementation writes a single CSV mixing both.
None of these are critical bugs, but together they create confusion and friction in day-to-day use.

Minimal Repro

1. Use a model that has a constant/parameter named like C.init_EGFR and also an initial value for species EGFR (so idx_initials contains that species index); for example, the pan_rtk sample model:
2. Run:

from biomass.result import OptimizationResults
# optimization required
res = OptimizationResults(model)
res.to_csv()
res.savefig(figsize=(16, 5), boxplot_kws={"orient": "v"})

3. Observe that labels like init_EGFR may appear together with parameters in the plot.
4. Try a label longer than 21 chars and check the CSV for truncation.
5. Modify the model or indices, then call only savefig() (without to_csv()); observe potential stale results if the old CSV remains.

What I would expect

• A clear way to exclude initials from the figure by default, or at least make them visually distinct.
• No label truncation in the CSV.
• An explicit refresh option so savefig() can regenerate the CSV when desired.
• Docs aligned with actual outputs (one CSV vs two CSVs), or else implement the documented split.

Proposed (backward-compatible) changes

1. Avoid label truncation in to_csv()
   Change the buffer dtype to object:

- optimized_params = np.empty((rows, cols), dtype="<U21")
+ optimized_params = np.empty((rows, cols), dtype=object)

This prevents cutting long names and keeps existing behavior otherwise intact.

2. Add savefig options

• include_initials: bool = False (default False)
  → filter out rows starting with init_ unless the user explicitly opts in.

• pretty_labels: bool = True (default True)
  → when initials are included, render init_XXX as Init: XXX to reduce confusion with parameters like C.init_XXX.

• refresh: bool = True (or False if you prefer strict backward compatibility)
  → when True, call to_csv() before plotting to avoid stale outputs.
  Sketch:

- def savefig(self, *, figsize=None, config=None, boxplot_kws=None) -> None:
+ def savefig(self, *, figsize=None, config=None, boxplot_kws=None,
+             include_initials: bool = False,
+             refresh: bool = True,
+             pretty_labels: bool = True) -> None:

+     if refresh:
+         self.to_csv()

      df = pd.read_csv(csv_path, index_col=0)
      df.drop("*Error*", inplace=True, errors="ignore")
+     if not include_initials:
+         df = df[~df.index.str.startswith("init_", na=False)]
+     if pretty_labels:
+         df.index = df.index.str.replace(r"^init_", "Init: ", regex=True)

3. Documentation alignment

• Option A: Implement the docstring as written and actually split CSVs into optimized_params.csv and optimized_initials.csv, or
• Option B: Keep a single CSV but update docs to match reality, and explicitly document the init_ prefix plus the new savefig options.

Questions for maintainers (seeking guidance)

• For figures, would you prefer excluding initials by default (parameters only), or keeping the current behavior and documenting it more clearly?
• If initials are included, is a label like “Init: XXX” acceptable, or should labels remain as init_XXX?
• For CSV regeneration, would you lean toward adding a refresh option (opt-in) or keeping the current behavior and documenting that users should run to_csv() before plotting?
• On the docs vs implementation mismatch (one CSV vs two): would you rather adjust the docs to match current behavior, or split the CSVs as the docstring suggests?
• I’m not requesting changes; I’m sharing these observations in case they’re useful. If you decide to pursue any direction, I’m happy to provide additional details or share a minimal repro—otherwise please feel free to treat this as feedback.

Why this might help

• Avoids confusion between parameters (e.g., C.init_EGFR) and initial values (init_EGFR).
• Reduces the chance of plotting from a stale CSV.
• Prevents silent label truncation in CSVs with long names.
• Keeps existing workflows intact while clarifying defaults.

(Optional) Compatibility notes

• Using dtype=object in to_csv() prevents truncation without changing CSV semantics.
• Any new savefig options could be opt-in, preserving current behavior unless explicitly enabled.
• If a docs-only fix is preferred, a short note about initials (init_ prefix) and CSV refresh would likely suffice.

Note: This write-up was drafted with assistance from ChatGPT; I reviewed and validated all observations and code snippets. Thanks again for maintaining biomass and the sample models.

[himoto]

Thanks for the report.
Regarding to_csv() allocates with dtype='<U21' → long labels get truncated., I agree with this concern, and it has been addressed in #282.

[SHMAKI]

Thanks for the quick reply and update!