Add support for experiments (previously named timecourses)

[dilpath]

• functionality
  • read/write
  • OOP
  • methods for tools
    • to_events
    • to_sequence_of_petab
    • to_single_petab_and_sequence_of_metadata
    • optimize_metadata_to_reduce_redundant_simulations
    • optimize_metadata_to_reduce_events_or_unique_petabs_in_sequence_of_petabs
• linter validation checks
• test all functionality
• docs

[m-philipps]

Does it make sense to work on this now? Are there analogous functions for v1, or is all of this specific to the experiments table?
I'd interpret themethods for tools like:

1. to_events: At what time is a change in some model quantity (e.g. species concentration, compartment volume, ...) defined in the experiments table, the output could involve triplets (time, altered entity, new value/change)
2. to_sequence_of_petab: Define each experiment as a sequence of independent PEtab problems? What purpose would that serve?
3. What should be included in the PEtab metadata?

[dilpath]

Does it make sense to work on this now? Are there analogous functions for v1, or is all of this specific to the experiments table?

The "methods for tools" is still relevant, but I think there's nothing important to keep from this PR, and it's easier to implement from scratch based on the current support for experiments implemented in #332.

I'd interpret themethods for tools like:

1. to_events: At what time is a change in some model quantity (e.g. species concentration, compartment volume, ...) defined in the experiments table, the output could involve triplets (time, altered entity, new value/change)

This kind of output triplet data is what I meant by "metadata". The output of to_events would be the SBML model with events. This may involve relative changes, according to the current version of the PEtab v2 draft https://petab--581.org.readthedocs.build/en/581/v2/documentation_data_format.html#conditions-table

2. to_sequence_of_petab: Define each experiment as a sequence of independent PEtab problems? What purpose would that serve?

This is what I'm currently using, because it simplifies writing a wrapper around AMICI. Since each PEtab problem has a dummy measurement at the final timepoint of each period, AMICI knows to stop simulating when the current period ends. I then update the system according to the next period and ask AMICI to simulate the next PEtab problem with the custom initial condition.

3. What should be included in the PEtab metadata?

This metadata could be a sequence of tuples like [(time1, condition1), (time2, condition2), ...]. to_events and to_sequence_of_petab would use this to generate their output. In addition, tools could use this if they only want to load the PEtab problem once, then manually update the system inbetween periods. This would yield the fastest simulations of the full experiment, I think.

I guess there are many ways to implement this, alternative suggestions are welcome.