Skip to contents

Getting started with kofn

Source: vignettes/getting-started.Rmd
getting-started.Rmd

What kofn does

kofn is a maximum likelihood estimation toolkit for k-out-of-n systems: reliability systems that fail when k of m components have failed. k = 1 is a series system (first failure ends it), k = m is a parallel system (all must fail), and intermediate values interpolate between them.

The package focuses exclusively on inference: log-likelihood, score, Hessian, fit, observation schemes (right/left/interval/periodic), masked cause-of-failure, and Fisher information comparison. The underlying data-generating process (DGP) and topology queries are delegated to dist.structure, which kofn imports.

Your first fit 

# A 2-of-3 exponential system: system fails when 2 of 3 components fail.
model <- kofn(k = 2, m = 3, component = dfr_exponential())

# Generate 200 complete (Scheme 0) observations.
gen <- rdata(model)
df <- gen(theta = c(1, 2, 3), n = 100)

# Fit via maximum likelihood.
fitter <- fit(model)
result <- fitter(df, n_starts = 1)
result$converged
#> [1] TRUE
coef(result)
#> [1] 1.684274 1.684549 1.682958

For exponential parallel systems (k = m), only the sum of rates is identifiable from system-level data alone; individual rates are not. The sum typically recovers well:

sum(coef(result))
#> [1] 5.051782
sum(c(1, 2, 3))
#> [1] 6

Convention

kofn uses the :F convention: k counts component failures that trigger system failure.

  • kofn(k = 1, m) = series (first failure ends the system).
  • kofn(k = m, m) = parallel (system survives until the m-th failure).
  • kofn(k, m) for intermediate k = k-out-of-m systems.

(dist.structure internally uses the :G convention, which is the dual. kofn handles the conversion for you; you never need to think about :G.)

Observation schemes

Real experiments rarely observe system failure exactly. kofn provides composable observation functors for censoring and periodic inspection:

# Right-censored: systems that fail after tau = 2 get recorded at t = 2
df_cens <- gen(c(1, 2, 3), n = 100,
               observe = observe_right_censor(tau = 2))
table(df_cens$omega)
#> 
#> exact 
#>   100

The log-likelihood handles mixed observation types automatically:

ll <- loglik(model)
ll(df_cens, c(1, 2, 3))  # finite; right-censored obs contribute log S(t)
#> [1] -26.65438

Other functors: observe_left_censor, observe_interval_censor, observe_periodic, observe_mixture. See the observation-schemes vignette.

Weibull components

Weibull component lifetimes work analogously, with parameters interleaved as (shape_1, scale_1, shape_2, scale_2, ...):

model_wei <- kofn(k = 2, m = 2, component = dfr_weibull(), method = "em")
gen_wei <- rdata(model_wei)
df_wei <- gen_wei(theta = c(1.5, 2.0, 2.0, 3.0), n = 100)
result_wei <- fit(model_wei)(df_wei, n_starts = 1)
result_wei$shapes
#> [1] 1.892926 2.470886
result_wei$scales
#> [1] 1.485970 3.640238

For parallel Weibull systems (k = m), method = "em" uses an EM algorithm treating the identity of the last-failing component as latent. For general k, use method = "mle" (direct L-BFGS-B).

Periodic inspection (Scheme 1)

When only periodic snapshots are available, use loglik_scheme1/fit_scheme1:

s1gen <- rdata_scheme1(model)
df_s1 <- s1gen(theta = c(1, 2, 3), n = 200, delta = 0.5)
ll_s1 <- loglik_scheme1(model)
ll_s1(df_s1, c(1, 2, 3))
#> [1] -731.7861

Masked cause-of-failure

When you observe system failure and a candidate set (superset of the truly-failed components) rather than knowing which components failed:

rgen <- rdata_masked(model)
df_masked <- rgen(theta = c(1, 2, 3), n = 100, p_mask = 0.3)
ll_masked <- loglik_masked(model)
ll_masked(df_masked, c(1, 2, 3))
#> [1] -58.58316

Fisher information comparison

How much precision do you gain from each observation scheme? kofn provides a built-in comparison:

res <- compare_fisher_info(
  rates = c(0.5, 0.3), n = 50, delta = 1.0, n_rep = 10,
  component = dfr_exponential()
)
res$median_det

This runs n_rep replications of each scheme and reports the median determinant of the observed information matrix per scheme.

What’s next

See the other vignettes for deeper coverage: