Remarks about docs [JuliaCon Proceedings review]

[gdalle]

Hey there!
I'm reviewing the package and associated paper for the JuliaCon Proceedings, so I'll put some remarks about the documentation here. This issue will be updated as I make my way through the docs.

JuliaCon/proceedings-review#133

Home page

• I think a few sentences might be warranted about what a jump / point process is and to whom it is useful ("statement of need" section of the review). I know people landing on this page will probably know already, but it doesn't cost much to make it accessible for people who don't.

Simple Poisson Processes in JumpProcesses

• I don't understand the specific roles of the aggregator and the stepper
• For the process with varying birth rate, you state that "death does not change u[1]", which seems weird to me. Isn't it rather birth that doesn't change u[2]?

Continuous-Time Jump Processes and Gillespie Methods

• Is there a way to implement the variable rate case of time-dependent infection rate without a global variable H? Same question for other models on the page
• When it comes to controlling saving behavior, what exactly is saved by the callback mechanism? During the first read it was unclear to me that the saving referred to the solution values.

Piecewise Deterministic Markov Processes and Jump Diffusion Equations

• The jump diffusion equation may be a bit unclear for those who (like me) don't know SDEs. I assume $dW$ is a Brownian motion?
• Why does the SDE version look so different from the PDMPs on the last plot?

Spatial SSAs with JumpProcesses.jl

(nothing)

Mathematical Specification of a problem with jumps

• I would put the blurb at the beginning much earlier in the docs, perhaps even before the tutorials
• An example of DiscreteProblem definition would be welcome before stating that JumpProblem must wrap it

Jump solvers

• The distinct roles of the aggregator and stepper are still unclear to me

Small typos

• Fix typos in docs #366

[ChrisRackauckas]

I don't understand the specific roles of the aggregator and the stepper

Everyone likes to talk about the jumps as being a stochastic process. They are not. The stochastic process is only defined by knowing all of the jumps together and choosing some method to aggregate them. The aggregator generates the representation of the stochastic process from the jump descriptions. But then you have to say how you're going to step: do you step directly to the jumps? Constant dt? Etc. This matters more in the context of connecting to ODEs.

[isaacsas]

Thanks for the comments! We will try to make some updates to clarify these questions.

[ChrisRackauckas]

Is there a way to implement the variable rate case of time-dependent infection rate without a global variable H? Same question for other models on the page

Use a parameter.

When it comes to controlling saving behavior, what exactly is saved by the callback mechanism? During the first read it was unclear to me that the saving referred to the solution values.

The state vector.

[gzagatti]

Thanks for your feedback. I will work on the documentation to clarify the issues you raised.

Coming from the point process side, I was also a bit confused about the roles of aggregators and steppers. I think the nomenclature is quite different from what we see in the point process literature. This is in part what our paper tries to do, that is, to bridge the gap between the treatment of jumps in biochemistry and point process in statistics.

Everyone likes to talk about the jumps as being a stochastic process. They are not. The stochastic process is only defined by knowing all of the jumps together and choosing some method to aggregate them. The aggregator generates the representation of the stochastic process from the jump descriptions. [...]

Just to make sure I understand this part. When you say that jumps are not a stochastic process, are you talking about the rates which determine the time of the jumps? In simple terms, my understanding is that the aggregators are algorithms that take a bunch of independent rates (aka the jumps) and outputs the time of the next jump. Is that the gist of the first part of your statement?