LoweredDistributions.jl

Appearance

1

LoweredDistributions ​

A distribution-lowering hub: lower maps a Distributions.Distribution onto a backend-agnostic dynamical-systems representation.

Why LoweredDistributions? ​

  • A delay distribution and a compartmental model are two views of the same thing; lower gives you the compartmental view without hand-deriving the generator each time.

  • Exact phase-type matches are used where they exist (Erlang chains, two-state CTMCs, Coxian and general phase-type), with moment-matching as a documented fallback when no exact chain exists.

  • Every lowering converges on one canonical PhaseType(α, S) shape, so a new backend only has to consume that single interface.

  • Four backend extensions (Catalyst, SciMLBase, JumpProcesses, AlgebraicPetri) share the same lowering, so switching simulation or inference backend does not mean re-deriving the dynamical system.

  • A composed chain (ComposedDistributions.jl) or a convolved series (ConvolvedDistributions.jl) lowers as a whole, not leaf by leaf, so a multi-step delay collapses to one dynamical system too.

  • Lowering is exact where the maths allows it and explicit about the rest: a shape with no meaningful lowering raises a clear error rather than a silent approximation.

See the lowering tutorial for the full hierarchy, the fitting criterion, and a worked example across all four backends.

Getting started ​

A Gamma(3, 1.5) delay is exactly three exponential compartments in series, each left at rate 1/1.5, so it lowers to an ErlangChain.

julia
using LoweredDistributions, Distributions

lower(Gamma(3.0, 1.5))
ErlangChain(3 compartments)

Every phase-type lowering converts to the canonical PhaseType(α, S) view, the sub-generator shape the backends consume.

julia
PhaseType(lower(Gamma(3.0, 1.5))).S
3×3 Matrix{Float64}:
 -0.666667   0.666667   0.0
  0.0       -0.666667   0.666667
  0.0        0.0       -0.666667

The tutorial takes one delay through all four backends and checks each against the distribution it came from. See the documentation for the full walkthrough.

Where to learn more ​

  • ComposedDistributions.jl composes distributions into event-tree chains; loading it alongside this package lowers a whole Sequential/Resolve/Compete/Parallel/Choose chain to one dynamical system, not leaf by leaf.

  • ConvolvedDistributions.jl sums independent delays; a lowering extension here lets a convolved series lower as a whole too.

  • ModifiedDistributions.jl wraps a distribution with one behaviour change at a time; the modifiers that carry dynamics (an affine rescale, a hazard modify on an Exponential) lower, and the observation-only ones (a shift, a weight, a forward transform) are refused rather than silently approximated.

  • CensoredDistributions.jl adds primary-event and interval censoring on top of a delay distribution, upstream of any lowering.

  • DistributionsInference.jl is the emerging home for probabilistic-programming integrations across the EpiAware distribution packages.

Getting help ​

For usage questions, ask on the Julia Discourse (the SciML or usage categories) or the epinowcast community forum, our home for epidemiological modelling questions. Please use GitHub issues for bug reports and feature requests only.

<!– standard-sections:start –> <!– MANAGED by EpiAwarePackageTools.scaffold — do not edit between the markers. These standard sections are re-rendered on every scaffold_update; edit the package-owned sections outside them, or CITATION.cff. –>

Contributing ​

We welcome contributions and new contributors! Please open an issue or pull request on GitHub. This package follows ColPrac and the SciML style.

How to cite ​

If you use LoweredDistributions in your work, please cite it. Citation metadata lives in CITATION.cff, which GitHub renders as a "Cite this repository" button on the repository page.

Code of conduct ​

Please note that the LoweredDistributions project is released with a Contributor Code of Conduct. By contributing, you agree to abide by its terms. <!– standard-sections:end –>