---
title: "Package Ecosystem: Reliability Analysis with Masked Failure Data"
output:
    rmarkdown::html_vignette:
        toc: true
vignette: >
  %\VignetteIndexEntry{Package Ecosystem: Reliability Analysis with Masked Failure Data}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

## The Problem

In reliability engineering, a **series system** fails when any of its $m$
components fails. When the system is observed in the field, we often know
*when* it failed but not *which component* caused the failure. Instead, we
observe a **candidate set** — a subset of components that plausibly contains
the true cause. This is **masked failure data**.

The statistical challenge is to estimate component-level lifetime parameters
from system-level observations where the failure cause is partially or fully
masked and the failure time may be censored (right, left, or interval).

This vignette describes a family of R packages that address this problem at
different levels of generality, from foundational distribution algebra through
closed-form maximum likelihood estimation to fully general numerical inference.

## Package Ecosystem

The packages form a layered dependency graph. Solid arrows indicate
`Imports` dependencies; the dashed arrow indicates a `Suggests` dependency
used for cross-validation testing.

```
    algebraic.dist ─────────────────────────┐
         │                                  │
         ▼                                  │
    algebraic.mle                           │
         │                                  │
         ├──────────────┐                   │
         ▼              ▼                   ▼
  compositional.mle  likelihood.model   generics
                        │       │          │
                   ┌────┘       └────┐     │
                   ▼                 ▼     │
                flexhaz        maskedcauses
                   │                 │
                   ▼                 │
                serieshaz            │
                   │                 │
                   └──────┐  ┌──────┘
                          ▼  ▼
                        maskedhaz
```

All packages are available on [r-universe](https://queelius.r-universe.dev).
Packages marked with **[CRAN]** below are published on CRAN; the remainder
are targeting CRAN submission.

## Foundation: Distribution and MLE Infrastructure

Four packages provide the algebraic and inferential foundation that the
reliability-specific packages build on.

**algebraic.dist** [CRAN] — An algebra over probability distributions.
Compose, sample, and auto-simplify distributions (normal, exponential,
multivariate normal, empirical) using S3 generics. Provides the distribution
abstraction used throughout the ecosystem.

**algebraic.mle** [CRAN] — An algebra over maximum likelihood estimators.
Unified interface for `mle`, `mle_numerical`, `mle_boot`, and `rmap_mle`
objects with delta-method and bootstrap inference. The MLE result class used
by fitting functions across the ecosystem.

**likelihood.model** [CRAN] — A Fisherian likelihood framework. Defines the
core generics — `loglik`, `score`, `hess_loglik`, `fim`, `observed_info`,
`rdata`, `assumptions` — that all likelihood models in this ecosystem
implement. Contribution-based models support heterogeneous observation types
(exact, right-censored, left-censored, interval-censored) in a single
likelihood.

**compositional.mle** [CRAN] — Composable MLE solvers as first-class
functions. Sequential chaining (`%>>%`), parallel racing (`%|%`), and random
restarts turn solver construction into an algebra. Useful for building robust
optimization strategies for the multi-modal likelihoods that arise in masked
data problems.

## Hazard-Based Components: flexhaz

**flexhaz** — Define a lifetime distribution by specifying its hazard
function $h(t; \boldsymbol{\theta})$ and get the survival function, density,
CDF, quantiles, random sampling, and MLE automatically. The `dfr_dist` class
("dynamic failure rate distribution") is the building block for
component-level models.

Built-in constructors include `dfr_exponential()`, `dfr_weibull()`,
`dfr_gompertz()`, and `dfr_loglogistic()`, but any user-defined hazard
function works. flexhaz implements the `likelihood_model` interface from
likelihood.model, so every `dfr_dist` object can be used directly with
`loglik()`, `score()`, `fit()`, and friends.

## Series System Topology: serieshaz

**serieshaz** — Compose `dfr_dist` components from flexhaz into a series
system. For a series system of $m$ components, the system hazard is the sum
of component hazards:

$$h_{\text{sys}}(t) = \sum_{j=1}^{m} h_j(t; \boldsymbol{\theta}_j)$$

and the system survival is the product of component survivals:

$$S_{\text{sys}}(t) = \prod_{j=1}^{m} S_j(t; \boldsymbol{\theta}_j).$$

The `dfr_dist_series` class inherits all flexhaz methods (density, survival,
quantiles, sampling, MLE) and adds a parameter layout system that maps a flat
parameter vector to per-component slices — enabling standard optimizers to
work on the full system likelihood.

## This Package: maskedcauses

**maskedcauses** (this package) provides closed-form maximum likelihood
estimation for masked series system data under the standard masking conditions
(C1, C2, C3). Three likelihood models form a natural nesting chain:

| Model | Parameters | Constructor |
|-------|-----------|-------------|
| Exponential series | $m$ rates: $(\lambda_1, \ldots, \lambda_m)$ | `exp_series_md_c1_c2_c3()` |
| Homogeneous Weibull series | $m + 1$: $(k, \beta_1, \ldots, \beta_m)$ | `wei_series_homogeneous_md_c1_c2_c3()` |
| Heterogeneous Weibull series | $2m$: $(k_1, \beta_1, \ldots, k_m, \beta_m)$ | `wei_series_md_c1_c2_c3()` |

Each nesting level is testable via likelihood ratio test (see the
`vignette("model_selection")` for a complete treatment).

The key advantage of maskedcauses is **analytical tractability**: the
exponential model has closed-form log-likelihood, score, and Hessian for all
four observation types (exact, right, left, interval). The Weibull models
have analytical expressions for exact and right-censored observations, with
efficient closed-form or numerical expressions for left and interval
censoring.

maskedcauses also provides the **masked data infrastructure** used across the
ecosystem: composable observation functors (`observe_right_censor`,
`observe_left_censor`, `observe_periodic`, `observe_mixture`), candidate set
generation under C1/C2/C3 conditions, and the `series_md` S3 class hierarchy.

## General Masked Inference: maskedhaz

**maskedhaz** — When component lifetimes follow distributions beyond
exponential and Weibull — Gompertz, log-logistic, or arbitrary user-defined
hazard functions — maskedhaz provides MLE for the masked series system
likelihood using numerical methods.

maskedhaz builds on serieshaz for system construction and maskedcauses for
masked data infrastructure. It uses numerical integration
(`stats::integrate`) for left and interval-censored contributions and
numerical differentiation (`numDeriv::jacobian`) for the Hessian.

The trade-off is clear: maskedhaz handles **any** component lifetime
distribution that flexhaz can represent, at the cost of speed and the
availability of analytical derivatives. For exponential and Weibull
components, maskedcauses is the faster and more precise choice.

Cross-validation tests in maskedhaz verify that its numerical results match
the analytical results from maskedcauses for the exponential special case,
providing confidence in both implementations.

## Choosing the Right Package

| You need... | Use |
|---|---|
| Component lifetimes are exponential | `maskedcauses::exp_series_md_c1_c2_c3()` |
| Component lifetimes are Weibull (shared shape) | `maskedcauses::wei_series_homogeneous_md_c1_c2_c3()` |
| Component lifetimes are Weibull (different shapes) | `maskedcauses::wei_series_md_c1_c2_c3()` |
| Model selection across the Weibull chain | `maskedcauses` — see `vignette("model_selection")` |
| Component lifetimes are Gompertz, log-logistic, or custom | `maskedhaz` with `flexhaz` components |
| Series system distribution (no masking) | `serieshaz` with `flexhaz` components |
| Single-component DFR distribution | `flexhaz` |
| MLE algebra (delta method, bootstrap) | `algebraic.mle` |
| Composing optimization strategies | `compositional.mle` |
