# FirstPassageTools

`FirstPassageTools`

is a Julia package for setting up first-passage time distributions for
continuous-time, discrete-state Markov processes. The first-passage time distributions can
then be fit to empirical first-passage time data using Turing.jl.

# Installation

FirstPassageTools.jl can be installed from Juila's central package repository:

julia> ]
pkg> add FirstPassageTools

FirstPassageTools.jl can also be installed directly from Github in the Julia REPL:

julia> ]
pkg> add https://github.com/smith-garrett/FirstPassageTools.jl

# Usage

To set up a first-passage time distribution, one needs to provide two transition rate
matrices and a vector with the initial probability distribution over the transient states
(`p0`

in the example below). The first matrix (`T`

below) determines the transition rates
between transient states of the system. The second determines the transition rates from the
transient states to one or more absorbing states (`A`

below). The rows of the transient
matrix T should sum to the values given in the absorbing matrix. For both matrices, the
$i,j$-th entry should provide the transition rate from state $j$ to state $i$.

Currently, the most complete functionality is available for the first-passage time to *any*
absorbing state by time t. When a system has more than one absorbing state, one might be
interested in the conditional first-passage time to reach a particular absorbing state
before all others. Some methods are implemented for this, but not everything.

For a single transient state and a single absorbing state, the first-passage time distribution is equivalent to the exponential distribution:

julia> using FirstPassageTools
julia> T = [-1.0;;] # transition rate matrices need to be 2-dimensional
julia> A = [1.0;;]
julia> p0 = [1.0]
julia> fp = fpdistribution(T, A, p0)

Available methods for first-passage time distributions include `mean()`

, `var()`

, `rand()`

,
`pdf()`

, `logpdf()`

, `cdf()`

, and `quantile()`

. From here, the transition rates of the
distribution can be fit to data. See the notebooks directory for additional tutorials and
parameter recovery exercises.

Because the first-passage time distributions here are sub-types of the continuous univariate
distribution from`Distributions.jl`

,
plotting functions from `StatsPlots.jl`

work out of the box. For example, to plot the probability density function and the
cumulative distribution function from the above sample, you can run:

julia> using Plots, StatsPlots
julia> plot(fp, label="PDF")
julia> plot!(fp, func=cdf, label="CDF")

Additional examples are provided in the notebooks directory. Verification of correct
sampling, at least for certain statistical models, is provided in the
`SimulationBasedCalibration.jl`

script in the `notebooks`

directory.