CensoredDistributions.jl

Additional censored event tools for Distributions.jl

Websites: Organization Website | Documentation

CensoredDistributions.jl Stats:

Why CensoredDistributions.jl?

• Primary event censoring: Model delay distributions where the initial event occurs within a time window (e.g., exposure periods in epidemiology).
• Interval censoring: Bin continuous distributions into discrete intervals (e.g., daily reporting) when exact values are not observed.
• Double interval censoring: Combines both primary event and interval censoring for complex observation processes.
• Distribution fitting: Extends Distributions.jl's fit support with MLE fitting for primary censored and interval censored distributions (potentially truncated), plus Turing.jl integration for Bayesian inference.
• Analytical solutions: Provides analytical solutions where possible with numerical fallbacks for efficiency.

What can I do with CensoredDistributions.jl?

• Create distributions that are modified to account for primary event censoring and interval censoring.
• Apply interval censoring to continuous distributions (both regular and arbitrary intervals).
• Generate random samples from censored distributions.
• Calculate the probability density function (PDF) and cumulative distribution function (CDF) of censored event distributions.
• Calculate the PDF of interval-censored distributions.
• Calculate the mean, variance, and other moments of censored event distributions.
• Fit censored event distributions using Turing.jl for both Bayesian inference and MLE methods.

Getting Started

For comprehensive tutorials and guides, see our Getting Started documentation.

The following example demonstrates how to create a double interval censored distribution (combines primary event, interval censoring, and right truncation (using Distributions.truncated)):

using CensoredDistributions, Distributions, Plots

# Create a censored distribution accounting for primary and secondary censoring
original = Gamma(2, 3)
censored = double_interval_censored(original; upper = 15, interval = 1)

# Compare the distributions
x = 0:0.01:20
plot(x, pdf.(original, x), label = "Original Gamma", lw = 2)
plot!(x, pdf.(censored, x), label="Double Censored and right truncated", lw = 2)

You can fit censored distributions to data using Turing.jl for both Bayesian inference and MLE methods, as well as other optimization-based approaches:

using Turing

# Generate synthetic data from the censored distribution
data = rand(censored, 1000)

# Get counts of unique values for weighted likelihood
values = unique(data)
weights = [count(==(val), data) for val in values]

# Define a Turing model for fitting with weighted likelihood
@model function double_censored_model(values, weights)
    # Priors for Gamma parameters - weakly informative, not centered on true values
    α ~ truncated(Normal(1, 2), 0, Inf)
    θ ~ truncated(Normal(1, 2), 0, Inf)

    # Create the censored distribution
    censored_dist = double_interval_censored(Gamma(α, θ); upper = 15, interval = 1)

    # Vectorized weighted likelihood
    values ~ weight(censored_dist, weights)
end

# Fit using MLE or other methods
model = double_censored_model(values, weights)

# Fit using MCMC for Bayesian inference
chain = sample(model, NUTS(), MCMCThreads(), 1000, 2; progress = false)
summarize(chain)

  parameters      mean       std      mcse   ess_bulk   ess_tail      rhat   e ⋯
      Symbol   Float64   Float64   Float64    Float64    Float64   Float64     ⋯

           α    1.7816    0.0977    0.0041   568.4673   634.9968    0.9998     ⋯
           θ    3.6753    0.3052    0.0128   580.0904   579.5359    1.0004     ⋯
                                                                1 column omitted

Relationship to Distributions.jl

Both CensoredDistributions.jl and Distributions.jl's built-in censored() function handle censoring, but they address different types of uncertainty:

These approaches complement each other - you can apply observation limits to distributions with event timing uncertainty when both types of censoring affect your data.

CensoredDistributions.jl also works well with truncated() from Distributions.jl and supports both primary event censoring (initial event timing uncertainty) and secondary event censoring (observation window effects).

What packages work well with CensoredDistributions.jl?

• Distributions.jl provides the base functionality for working with distributions as well as tools for frequentist inference of distributions.
• Turing.jl for Bayesian inference of censored distributions. CensoredDistributions.jl is designed (and tested) to work well with Turing.jl.

Where to learn more

• Want to get started running code? Check out the Getting Started Tutorials.
• Want to understand the API? Check out our API Reference.
• Want to chat with someone about CensoredDistributions? Post on our GitHub Discussions.
• Want to contribute to CensoredDistributions? Check out our Developer Documentation.
• Want to see our code? Check out our GitHub Repository.

Contributing

We welcome contributions and new contributors! We particularly appreciate help on identifying and identified issues. Please check and add to the issues, and/or add a pull request and see our developer documentation for more information.

Code of Conduct

Please note that the CensoredDistributions project is released with a Contributor Code of Conduct. By contributing to this project, you agree to abide by its terms.