Add timePoints attribute to UniformTimeCourse

[luciansmith]

Add a 'timePoints' attribute that would contain a full list of all requested output points. Would optionally replace outputStartTime, outputEndTime, and numberOfSteps.

The following two UniformTimeCourses would be functionally identical:

<uniformTimeCourse id="simulation1" initialTime="0" outputStartTime="0" outputEndTime="10" numberOfSteps="10">

<uniformTimeCourse id="simulation1" initialTime="0" timePoints="0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10">

but of course the power of the attribute would be in defining a series with non-uniform intervals, such as this pseudo-logarithmic series:

<uniformTimeCourse id="simulation1" initialTime="0" timePoints="0, 1, 2, 5, 10, 20, 50, 100, 200, 500">

It additionally would be helpful for recording discontinuities at particular time points. Imagine a time course with an event that fired at time point 5:

<uniformTimeCourse id="simulation1" initialTime="0" timePoints="0, 1, 2, 3, 4, 4.99, 5, 6, 7, 8, 9, 10">

Adding in the '4.99' time point allows a generally sparse series of values, with one exception at the discontinuity.

Repeats would also be allowed, and would simply repeat the same output values. This would be useful when comparing simulated output with sampled outputs that might have had multiple collected values at the same time point in different experiments, as is done in some parameter estimation experiments:

<uniformTimeCourse id="simulation1" initialTime="0" timePoints="0, 1, 2, 3, 4, 5, 5, 5, 7, 8, 8, 10">

The values would be required to proceed in order.

[luciansmith]

As discussed at HARMONY 2025, the editors present all voted to adopt this change (@hsauro, @matthiaskoenig, @nickerso, @eagmon). @WeiweiAi: if you have an opinion, it would be welcome!

[WeiweiAi]

I agree with the change. Will the classname 'UniformTimeCourses' be modified as well, perhaps to 'TimeCourses', since the time interval might not be 'uniform' anymore?

[luciansmith]

Oh, hunh. That's a good point! The main problem would be that it wouldn't be backwards-compatible, but maybe that wouldn't be too problematic? Libsedml could be coded to write out the correct version; the problem would only be code (or users) that edit the SED-ML directly. Pinging the editors here to see if they have an opinion?

[agarny]

Not an editor anymore, but Weiwei is indeed making a good point. I would personally go for that change. Regarding libSEDML, if I recall correctly, its numberOfPoints() method redirects to numberOfSteps(). So, I imagine that something similar could be done for backward compatibility?

[fbergmann]

Also not an editor again, my preference would be to have a new class rather than making this an attribute on the UniformTimeCourse. Since a) it could not be uniform b) it'd be a hassle with using objects independently of SED-ML version and c) would be a huge change for tools not using the library.

[nickerso]

I agree with @fbergmann - makes sense to have a more general TimeCourse class that allows for non-uniform time courses. Although perhaps that can be achieved already with an analysis and some KiSAO terms?

Pragmatically, it might be easier to just add the timePoints attribute and document that the name UniformTimeCourse is just a name, no semantic meaning should be inferred from it ;-)

[hsauro]

Ouch, good point WeiweiAI. Herbert

[luciansmith]

Indeed, this functionality is totally achievable with the current Analysis class and some new KiSAO terms. But putting things into core elements indicates to implementors that these are ways to encode functions that are commonly used, which I think is fair for this particular change.

It would be nice if we could take the pragmatic approach and just say in the spec that 'UniformTimeCourse' is an inherited name that no longer means what it once did. Just adding a couple more attributes would mean that a given SED-ML document is future-compatible just by changing the '5' to a '6', because all the old constructs would still work. It would no longer be backwards-compatible, but that's to be expected, I think.

[matthiaskoenig]

Hi all,

+1 for creating a new class TimeCourse which has the additional attributes.

-1 for allowing the same time point multiple times; this is not needed for anything and will create possible issues. I.e. no duplicates (in parameter optimization this is not an issue. You can have multiple data points at the same time point, but would only request the value of the observable at the timepoint once). I could expect some tools will trip up if there is no montoneously increasing timepoints (see also next point).

Also some restrictions on monotoneity should be added. I.e. the points in the timepoints have to be monotonically increasing (or have to be sorted before running the integration)
Best Matthias

[luciansmith]

We had a specific request to allow repeated time points for parameter estimation (maybe from the Amici folks?) because that's how the data they collect from some experiments appears. So roadrunner already has support for it, and there's a use case already.

If repeated times turned out to be onerous for a particular simulator, it wouldn't be too difficult to put in a layer in the SED-ML interpreter that understood what was needed, asked the simulator for unique time points, then duplicated a few for the requested output.

[luciansmith]

Aha, there it was: @PaulJonasJost requested it to more easily compare results from replicate observations to simulation output.

[matthiaskoenig]

I get the point.

But I think this should be handled via an interpolation which could solve a lot of similar use cases (see for instance #24). I.e. one has a timecourse and could then request an interpolation for additional time points. This would be much more flexible and would not require the data to generate the SED-ML for the time points.
E.g. one wants to run a plot/parameter optimization with another dataset with some other timepoints. An interpolator could easily do this, by hardcoding matching data points one has to update the SED-ML.

The interpolation would then also allow to have minimal timepoints to achieve a given accuracy and the subsequent interpolation would generate the actual timepoints.

In summary: It would be amazing to have the interpolation which would solve a ton of the issues. Generating the duplicate timepoints could be an immediate use case.

[luciansmith]

I feel like interpolation is one potential algorithm a simulator could use if they wanted to; perhaps encoded as a KiSAO term, and perhaps used when necessary. But while SED-ML could record its use, the main thing it should do is declare what form the output should take, which in my mind would include listing the duplicate time points. For roadrunner, we wouldn't bother with interpolation; for another interpreter, perhaps they would use it.