Function guide and demographic meaning

Question answered

For a given pair of Weibull parameters, what survivorship value is predicted at each age class?

Role in the package

weibull_survival() is the low-level mathematical function used by the higher level reconstruction routes. It evaluates

\[ l_x = \exp\left[-\left(\frac{x}{\alpha}\right)^\beta\right]. \]

lx_candidate <- weibull_survival(
  alpha = 4.5,
  beta = 1.2,
  age = age
)

knitr::kable(
  data.frame(age = age, lx_candidate = lx_candidate),
  digits = 4
)

Interpretation

This function does not use fertility and does not impose R0 = 1. It simply returns a survivorship curve for supplied values of alpha and beta.

Question answered

Given alpha, beta, and fertility, what survivorship profile and total births are implied?

Role in the package

This historical helper returns the Weibull survivorship vector under the name population and the resulting sum births = sum(population * fertility_rates).

calculated <- calculate_population(
  alpha = 4.5,
  beta = 1.2,
  fertility_rates = mx
)

calculated$births
#> [1] 0.9272999

Interpretation

The returned population is cumulative survivorship lx, not the normalized stable age structure R. Use derive_demographic_profile() when R, D, and B are needed.

Question answered

For one selected beta, which alpha makes the fertility schedule satisfy sum(lx * mx) = 1?

alpha_for_beta <- find_alphas(
  beta = 1.2,
  fertility_rates = mx
)

alpha_for_beta
#> [1] 4.971506

Interpretation

This is a root-finding step. It is useful for understanding the historical algorithm, but ordinary analyses should usually use reconstruct_population(), scan_beta(), or select_beta(), because those functions also return clearer diagnostics and output tables.

Question answered

If beta is fixed in advance, what constrained Weibull profile is obtained?

reconstruction <- reconstruct_population(
  fertility_rates = mx,
  beta = 1.20
)

reconstruction
#> Stable Population Reconstruction (Weibull, R0 = 1)
#> ---------------------------------------------------
#>   alpha: 4.97151 
#>   beta:      1.2 
#>   R0:            1 
#>   Stable: TRUE 
#>   Age classes: 6 
#> 
#> Use $table for the full age-specific profile.
knitr::kable(reconstruction$table, digits = 4)

Interpretation

This is the fixed-beta route. It should be used when beta is already justified by an external argument or when a particular value is being examined as an explicit scenario. The function solves alpha under R0 = 1 and returns the reconstructed lx.

Question answered

Which constrained candidate profiles are possible across a grid of beta values?

scan <- scan_beta(
  fertility_rates = mx,
  beta_values = seq(0.50, 1.80, by = 0.10)
)

scan
#> Stable Population Scan (Weibull, R0 = 1)
#> -----------------------------------------
#>   Beta values scanned: 14 
#>   Numerically stable:  14 
#>   Admissible:          14 
#>   Age classes: 6 
#> 
#> Use $summary for all candidates, $admissible_summary for retained ones.
knitr::kable(head(scan$summary), digits = 4)

Interpretation

scan_beta() is the scenario route. It does not select a single empirical optimum. It returns a family of profiles, all solved under R0 = 1 when the solver converges.

A terminal survivorship window can be used when the analysis is framed around a final-class criterion.

terminal_scan <- scan_beta(
  fertility_rates = mx,
  beta_values = seq(0.50, 1.80, by = 0.10),
  terminal_window = c(0.10, 0.40)
)

knitr::kable(terminal_scan$admissible_summary, digits = 4)

The terminal window filters scenarios. It does not estimate a true beta and it does not create a central result.

Question answered

When observed survivorship is available, which constrained candidate profile is closest to it?

selection <- select_beta(
  fertility_rates = mx,
  lx_observed = lx_observed,
  beta_values = seq(0.50, 1.80, by = 0.05)
)

selection
#> Stable Population Selection (Weibull, R0 = 1, best RMSE)
#> ---------------------------------------------------------
#>   Best beta:      1.1 
#>   Best alpha: 5.15055 
#>   R0:                 1 
#>   RMSE:       2.902e-08 
#>   Age classes: 6 
#>   Candidates evaluated: 27 
#> 
#> Use $best_profile for the selected profile, $results for all candidates.
selection$best_beta
#> [1] 1.1
selection$best_alpha
#> [1] 5.150545
selection$best_RMSE
#> [1] 2.901736e-08

knitr::kable(selection$best_profile, digits = 4)

Interpretation

select_beta() scans a grid of beta values. For each beta, alpha is derived from the stability condition. The selected profile is the grid candidate with the lowest RMSE against lx_observed. This is therefore not a free two-parameter Weibull fit.

If the selected beta is exactly at the lower or upper boundary of the scanned range, the result should be treated as a diagnostic cue to extend the beta grid before interpreting the selected value.

selection$beta_at_boundary
#> [1] FALSE
selection$beta_boundary_note
#> [1] NA

Question answered

How should a fertility schedule be rescaled if the analysis is deliberately expressed relative to R0 = 1 for a reference survivorship profile?

normalised <- normalize_fertility(
  fertility_rates = mx,
  lx_reference = lx_observed
)

normalised
#> Normalized Fertility Schedule
#> -----------------------------
#>   R0 (reference):       1 
#>   Scaling factor:       1 
#>   Check R0 (after normalization):         1 
#>   Age classes: 6 
#> 
#> Use $fertility_rates_normalized for the adjusted schedule.

Interpretation

Normalisation is explicit. It multiplies every fertility value by the same factor and preserves the age pattern of fertility. Neither select_beta() nor run_reconstruction_excel() normalises fertility silently.

Question answered

Once lx has been reconstructed, what stable age structure and mortality profiles follow from it?

demographic_profile <- derive_demographic_profile(
  lx = selection$best_lx,
  fertility_rates = mx
)

demographic_profile
#> Stable Population Demographic Profile
#> --------------------------------------
#>   Age classes: 6 
#>   R0:         1 
#>   Stable R0: TRUE 
#>   sum(R):         1 
#>   sum(D): 0.25155938  (expected: 0.25155938 )
#>   sum(D_relative):         1 
#> 
#> Use $table for the full profile with R, D, D_relative and B.
knitr::kable(demographic_profile$table, digits = 4)

Interpretation

This function creates the demographic bridge from survivorship to downstream eco-demographic quantities:

• R or stable_structure: normalized stable age structure;
• D or mortality_profile: raw exit-by-death profile;
• D_relative: separately normalized death profile;
• B or conditional_survival: survival between consecutive classes.

The raw D and the relative D are not the same object. This distinction is important when later ecological layers combine mortality with body mass or species abundance.

Question answered

What two-parameter Weibull curve best describes the observed survivorship, without imposing the stable-population constraint?

free_fit <- fit_weibull_free(
  lx_observed = lx_observed,
  fertility_rates = mx
)

free_fit
#> Free Weibull Fit (unconstrained, descriptive reference)
#> -------------------------------------------------------
#>   alpha:     5.15055 
#>   beta:          1.1 
#>   RMSE:      8.666e-08 
#>   Converged: TRUE 
#>   R0 (implied):       1 
#>   Optimization starts: 12 ( 12 converged )
#> 
#> Use $profile for the fitted profile, $attempts for all starts.
free_fit$R0_fitted
#> [1] 1

Interpretation

This is a descriptive reference fit. Both alpha and beta are estimated freely. If fertility is supplied, the implied R0 is reported after the fit. It should not be confused with the constrained route used by select_beta().

Question answered

How can the same reconstruction routes be applied to Excel workbooks?

run_reconstruction_excel() is the recommended external-workbook interface. In mode = "auto", each sheet is routed according to the available columns:

run_analysis() is the historical source-tree workflow retained for compatibility with version 1.0.3. New analyses should normally use run_reconstruction_excel().