New API in upcoming version

[apriljunge]

Because of some discussions in #56, #55 and #54 I thought of maybe changing or providing an alternative API to use trainruns.
As this would be a big refactoring and a breaking change should discuss this if this is really needed and what are benefits and downsides and how this would work out with #43 and #41.

One proposal would be to separate the calculation of POIs from the trainruns method. POIs, as they are implemented now, have no influence on the travel time of the train. Therefore my suggestion would be to have a new method like timing_at() or similar. The code could then look like this:

drivingCourse = trainrun(train, path); # returns data like in :driving_course setting

# Without DataFrames
timing = driving_data_at!(drivingCourse, 10000, :measure=:front) # returns calculated values at 10.0km

# With DataFrames
points_of_interest = DataFrame(position=10000, measure="front")
driving_data_at!(drivingCourse, points_of_interest) # extends DataFrame with calculated values

Maybe theres not need passing the drivingCourse variable and reduce it to driving_data_at!(10000, :measure=:front) like Makie.jl does it. But I have no idea how 😄

Pros:

• reduce parameters of trainrun method
• reduce complexity in calcultation part
• be more flexible after calculation
• smaller settings

Cons:

• could be complicated to correctly interpolate on breaking, accelerating etc.

Maybe one could get something similar for :running_path setting?

[apriljunge]

Maybe theres not need passing the drivingCourse variable and reduce it to driving_data_at!(10000, :measure=:front) like Makie.jl does it. But I have no idea how 😄

They seem to do it with global variables

https://github.com/MakieOrg/Makie.jl/blob/c62e09d833b285619ebda9a75db9409845fe39c9/src/figures.jl#L34-L50

[kaat0]

I also always wondered how they did it. But I do not really like the approach that there is an implicit variable. The strength of code is that you (almost) can read what will happen. Especially, if you want to compare more than one trainrun.

[apriljunge]

Yes I'm also a little bit disappointed. But you can do both with makie. Depend on the global variable or define it directly
.

[apriljunge]

What do you think what the data you get could be called?
I cant get a good name for the function

[apriljunge]

Maybe one could get something similar for running_path setting?

With driving_data_at! function the :running_path setting could be replaced just by passing a StepRange driving_data_at!(drivingCourse, 0:10:10000, :unit=:distance)

:unit could be :distance, :time, :velocity

[kaat0]

we need a better name for driving_data_at.
Please note that the ! in function names does mean that the object in the function call will be modified.

[apriljunge]

Ah yes. Maybe then there would be two functions needed. One with one without !.

[kaat0]

Suggestions:

• run_parameters_at(run::DataFrame, (mileage::Real, line::String)) #returns a DataFrameRow
• estimates_at(run::DataFrame, (mileage::Real, line::String)) #returns a DataFrameRow
• estimate!(run::DataFrame, range::StepRange) #modifies run::DataFrame

estimates_at(run::DataFrame, (mileage::Real, line::String))[:s] will give you the :unit

better ideas?

[apriljunge]

Ah pretty neat!
What is the parameter line::String?

Your proposal only allows you to calculate estimates at a specific location, right? In the current implementation it is also possible to query a specific point in time.
Would you write a separate function for this or extend estimates_at?

[kaat0]

After some thought:

The function should be called interpolate_at() and interpolate!().

Parameters:

• run::DataFrame
• interpolation_type=:linear or other supported types
• base_unit=:distance or :time
• range::StepRange (optional for interpolate_at())

The idea of the tuple (mileage::Real, line::String) relates to the difference a distance or a track with mileage changes from different lines. See #43.

[apriljunge]

:running_time setting could be replaced by a new function.

running_time!(drivingCourse) # return the running time as a _number_

[kaat0]

see #59

[kaat0]

The idea of including the Point of Interest (POI) in the calculation is to explicitly calculate at that specific point and not interpolate. This is needed when a stepsize would overstep the POI.

However, I do see the advantage of including both methods for calculating the data at a POI.

[apriljunge]

Is it be possible to explicitly calculate a specific point in a breaking section without the approximation via the stepsize?
Like x meters from the start of breaking?

[kaat0]

Unfortunately, this is a complex question. It would be best to open a separate Discussion on all the options to calculate running time with their advantages and disadvantages. See #53. I would need time for this...