Implement residual sensitivity aggregation for PEtab v2

[FFroehlich]

Summary

This PR implements aggregation of residual sensitivities for PEtab v2 simulations and improves handling of edge cases like non-Gaussian noise models and experiments without measurements.

Key Changes

• Implement residual sensitivity aggregation: Added _aggregate_sres() method to compute sensitivities of concatenated residuals w.r.t. estimated PEtab parameters. The PetabSimulationResult.sres field now contains the aggregated residual sensitivities instead of None.

• Extract parameter mapping logic: Created _get_plist_to_problem_par_ix() helper method to map simulation result parameter indices to problem parameter indices. This handles both regular parameters and output parameter placeholders, and is now reused by both _aggregate_s2llh() and _aggregate_sres().

• Improve edge case handling:

  • Experiments without measurements (no timepoints) are now correctly skipped when aggregating residuals and their sensitivities
  • Non-Gaussian noise models now gracefully return None for unavailable results instead of raising errors
  • Residual-only reporting mode (RDataReporting.residuals) is now properly supported
  • Added _has_timepoints() helper to distinguish between experiments without measurements and missing computed results

• Enhanced documentation: Updated docstrings for PetabSimulationResult.sres and res() property to clarify the structure and ordering of aggregated results.

Implementation Details

• Residual sensitivities are aggregated by concatenating sensitivities from individual experiments in order, matching the row order of concatenated residuals
• Multiple model parameters mapping to the same problem parameter (e.g., output parameter placeholders) are correctly handled using np.add.at() to sum their contributions
• The implementation validates that all experiments have consistent availability of sensitivities before aggregation
• Least-squares identities (FIM == sres.T @ sres and sllh == -res @ sres) are verified to hold for parameter-independent noise models in the test suite

https://claude.ai/code/session_01F52fCqHwmLeAm1TDNUYCCc

[Copilot]

Pull request overview

This PR extends the PEtab v2 SUNDIALS simulator to aggregate residual sensitivities across experiments, aligning PetabSimulationResult.sres with the concatenated residuals returned by res(), and improving behavior for edge cases (e.g., non-Gaussian noise models and experiments without measurements).

Changes:

• Implement aggregated residual sensitivity computation (PetabSimulationResult.sres) across experiments.
• Factor out reusable parameter-index mapping logic via _get_plist_to_problem_par_ix().
• Improve edge-case handling for residual-only reporting mode, non-Gaussian noise models, and experiments without measurements; update docs/changelog accordingly.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

File	Description
python/tests/petab_/test_petab_v2.py	Adds coverage for aggregated residual sensitivities, reporting modes, and non-Gaussian noise behavior.
python/sdist/amici/sim/sundials/petab/_v2.py	Implements residual sensitivity aggregation and refactors parameter mapping; adjusts residual aggregation behavior for edge cases.
doc/examples/example_petab/petab_v2.ipynb	Documents availability of aggregated residuals and residual sensitivities for least-squares problems.
CHANGELOG.md	Announces new residual-sensitivity aggregation feature and related edge-case fixes.

Suppressed comments (1)

python/sdist/amici/sim/sundials/petab/_v2.py:782

• The placeholder and plist index mapping uses repeated list.index(...) lookups (model_par_ids.index(...) and plist.index(...)). This is O(n^2) and can be avoided by building dict-based index maps once. It also makes the intent clearer.

        # still needs experiment-specific parameter mapping for placeholders
        experiment = self._petab_problem[rdata.id]
        placeholder_mappings = self._exp_man._get_placeholder_mapping(
            experiment
        )
        for model_pid, problem_pid in placeholder_mappings.items():
            try:
                ix_map[model_par_ids.index(model_pid)] = x_free_ids.index(
                    problem_pid
                )
            except ValueError:
                # mapped-to parameter is not estimated
                pass

        # translate model parameter index to plist index
        plist = tuple(rdata.plist)
        return {
            plist.index(model_par_ix): problem_par_ix
            for model_par_ix, problem_par_ix in ix_map.items()
        }

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[dweindl]

Thanks

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 77.96%. Comparing base (cd38627) to head (2250723).

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3218      +/-   ##
==========================================
- Coverage   78.49%   77.96%   -0.54%     
==========================================
  Files         318      318              
  Lines       21013    21090      +77     
  Branches     1487     1487              
==========================================
- Hits        16494    16442      -52     
- Misses       4511     4640     +129     
  Partials        8        8              

Flag	Coverage Δ
cpp	71.97% <7.14%> (-0.16%)	⬇️
cpp_python	36.59% <7.14%> (-0.06%)	⬇️
petab	48.27% <100.00%> (+1.12%)	⬆️
petab_sciml	16.22% <7.14%> (-0.02%)	⬇️
petab_sciml_benchmarks	14.78% <7.14%> (-0.02%)	⬇️
python	70.34% <75.00%> (-0.03%)	⬇️
sbmlsuite-jax	?

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
python/sdist/amici/sim/sundials/petab/_v2.py	96.23% <100.00%> (+2.63%)	⬆️
python/tests/petab_/test_petab_v2.py	100.00% <100.00%> (ø)

... and 6 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.