Help for package NeStage

Type:

Package

Title:

Effective Population Size from Stage-Structured Populations

Version:

0.8.1

Date:

2026-10-07

Author:

Raymond L. Tremblay

[aut, cre]

Maintainer:

Raymond L. Tremblay <raymond.tremblay@gmail.com>

Description:

Computes effective population size (Ne) and the Ne/N ratio for stage-structured populations using the matrix population model framework of Yonezawa (2000) <doi:10.1111/j.0014-3820.2000.tb01244.x>. Functions are provided for sexually reproducing, clonally reproducing, and mixed (sexual + clonal) populations. Includes sensitivity and elasticity analyses for Ne/N with respect to vital rates.

License:

GPL-3

Encoding:

UTF-8

Language:

en-US

Depends:

R (≥ 4.1.0)

Imports:

ggplot2

Suggests:

dplyr, tidyr, purrr, expm, gt (≥ 0.9.0), knitr, popbio, popdemo, rmarkdown, testthat (≥ 3.0.0)

VignetteBuilder:

knitr

URL:

https://github.com/RaymondLTremblay/NeStage

BugReports:

https://github.com/RaymondLTremblay/NeStage/issues

Config/roxygen2/version:

8.1.0

NeedsCompilation:

Packaged:

2026-10-07 18:57:49 UTC; rlt

Repository:

CRAN

Date/Publication:

2026-10-07 20:20:02 UTC

Variance effective population size for 100% clonal stage-structured populations

Description

Implements Equations 10 and 11 of Yonezawa et al. (2000) for populations that reproduce exclusively through clonal means (d_i = 1 for all stages) with Poisson-distributed clonal output (V_c / c_bar = 1).

Usage

Ne_clonal_Y2000(
  T_mat,
  F_vec = NULL,
  D,
  L = NULL,
  x_max = 500L,
  Ne_target = 50,
  census_N = NULL,
  population = NULL,
  recruit_row = 1L
)

Arguments

T_mat

Numeric matrix (s x s). The survival/transition matrix. Row j, column i gives the probability that an individual in stage i at year t is in stage j at year t+1. Row/column order: stages 1, 2, ..., s (stage 1 = juvenile/smallest). Column sums must be <= 1 (total annual survival per stage).

F_vec

Numeric vector of length s. Fecundity of each stage: the mean number of clonal propagules produced per individual per year. Used only to compute L (generation time), the mean age of reproduction of a newborn cohort. Set F_vec = NULL if supplying L directly.

D

Numeric vector of length s. The stage frequency distribution: the proportion of the population in each stage. Must sum to 1. Use observed field counts or the stable-stage distribution from eigen analysis (they should be close at equilibrium).

L

Numeric scalar (optional). Generation time in years. If NULL (default), L is computed internally from T_mat and F_vec using the Yonezawa (2000) definition (x_max = 500 yr). Supply L directly to replicate a specific published value (e.g., L = 13.399 for Fritillaria Miz population).

x_max

Integer. Maximum age (years) for the L iteration (default 500). Ignored if L is supplied directly. Increase for very long-lived species (> 100 yr lifespan).

Ne_target

Numeric. Ne conservation threshold. Common choices: 50 (Franklin 1980, avoid inbreeding depression), 500 (long-term quantitative variation), or 5000 (Lande 1995, long-term evolutionary potential). Default 50.

census_N

Numeric or NULL. Actual or expected census population size. If supplied, Ne_at_census = NeN * census_N is added to the output. Default NULL.

population

Character string. Optional label for the population, used in printed output and the returned list.

recruit_row

Integer. The stage (matrix row) that newborns enter, i.e. where the fecundity vector F_vec is placed in F_mat. Default 1 (the first stage is the recruitment stage). Set to a later stage when the first stage is dormancy, e.g. a seed bank: recruit_row = 2 sends newborns to the active recruitment stage instead. Must name exactly one valid stage.

Value

A named list with the following elements:

population: Character label (from population argument)
model: "clonal_Y2000" – identifies the model used
NyN: Ny/N – annual effective size ratio (Eq. 11)
NeN: Ne/N – generation-time effective size ratio (Eq. 10)
L: Generation time used in the calculation (years)
L_source: "user" if L was supplied; "computed" if derived internally
u_dot: Named vector of total annual survival per stage (colSums of T_mat)
u2_bar: Stage-weighted mean of squared survivals (key intermediate)
Min_N: Minimum census size N for Ne >= Ne_target (Lande 1995)
Ne_target: The Ne threshold used for Min_N (default 5000)

References

Yonezawa K., Kinoshita E., Watano Y., and Zentoh H. (2000). Formulation and estimation of the effective size of stage-structured populations in Fritillaria camtschatcensis, a perennial herb with a complex life history. Evolution 54(6): 2007-2013. doi:10.1111/j.0014-3820.2000.tb01244.x

Lande R. (1995). Mutation and conservation. Conservation Biology 9: 728-791.

Examples

# ---------------------------------------------------------
# Example 1: Replicate Yonezawa Table 4 for population Miz
# ---------------------------------------------------------
# Transition matrix from Table 2 of Yonezawa et al. (2000)
T_Miz <- matrix(c(
  0.789, 0.121, 0.054,
  0.007, 0.621, 0.335,
  0.001, 0.258, 0.611
), nrow = 3, byrow = TRUE)

# Observed stage fractions (Table 2)
D_Miz <- c(0.935, 0.038, 0.027)

# Fecundity vector (Table 2) -- clonal propagules per plant per year
F_Miz <- c(0.055, 1.328, 2.398)

# Using L from Table 4 directly (recommended for exact replication)
result <- Ne_clonal_Y2000(
  T_mat      = T_Miz,
  F_vec      = F_Miz,
  D          = D_Miz,
  L          = 13.399,
  population = "Miz"
)
print(result)
# Expected: Ny/N = 2.932, Ne/N = 0.219, Min_N = 22,831

# ---------------------------------------------------------
# Example 2: Let the function compute L internally
# ---------------------------------------------------------
result2 <- Ne_clonal_Y2000(
  T_mat      = T_Miz,
  F_vec      = F_Miz,
  D          = D_Miz,
  population = "Miz (computed L)"
)
print(result2)

# ---------------------------------------------------------
# Example 3: Replicate Table 4 for population Nan
# ---------------------------------------------------------
T_Nan <- matrix(c(
  0.748, 0.137, 0.138,
  0.006, 0.669, 0.374,
  0.001, 0.194, 0.488
), nrow = 3, byrow = TRUE)

D_Nan <- c(0.958, 0.027, 0.015)
F_Nan <- c(0.138, 2.773, 5.016)

result3 <- Ne_clonal_Y2000(
  T_mat      = T_Nan,
  F_vec      = F_Nan,
  D          = D_Nan,
  L          = 8.353,
  population = "Nan"
)
print(result3)
# Expected: Ny/N = 2.428, Ne/N = 0.291, Min_N = 17,183

Run Ne_clonal_Y2000 with both observed and expected stage fractions

Description

Run Ne_clonal_Y2000 with both observed and expected stage fractions

Usage

Ne_clonal_Y2000_both(
  T_mat,
  F_vec,
  D_obs,
  D_exp = NULL,
  L = NULL,
  Ne_target = 50,
  census_N = NULL,
  population = NULL,
  recruit_row = 1L
)

Arguments

T_mat

Survival/transition matrix (s x s).

F_vec

Fecundity vector (length s). Used for L and D_exp.

D_obs

Observed stage fractions from field counts.

D_exp

Expected (equilibrium) stage fractions. If NULL, derived from the dominant eigenvector of A = T_mat + F_mat.

L

Generation time (years). If NULL, computed internally.

Ne_target

census_N

Numeric or NULL. Actual or expected census population size. If supplied, Ne_at_census = NeN * census_N is added to the output. Default NULL.

population

Character label for the population.

recruit_row

Integer. Stage (matrix row) that newborns enter; where F_vec is placed in F_mat. Default 1. Set to a later stage when the first stage is dormancy (e.g. a seed bank).

Value

A list with two Ne_clonal_Y2000 result objects:

observed: Results using D_obs
expected: Results using D_exp

Examples

T_Miz <- matrix(c(
  0.789, 0.121, 0.054,
  0.007, 0.621, 0.335,
  0.001, 0.258, 0.611
), nrow = 3, byrow = TRUE)

both <- Ne_clonal_Y2000_both(
  T_mat      = T_Miz,
  F_vec      = c(0.055, 1.328, 2.398),
  D_obs      = c(0.935, 0.038, 0.027),
  D_exp      = c(0.921, 0.046, 0.033),
  L          = 13.399,
  population = "Miz"
)
print(both$observed)   # main values in Table 4
print(both$expected)   # parenthetical values in Table 4

Variance effective population size for mixed sexual/clonal stage-structured populations

Description

Implements the full general Equation 6 of Yonezawa et al. (2000) for populations with both sexual and clonal reproduction. Each stage can have a different mix of the two reproductive modes via the per-stage clonal fraction vector d.

Usage

Ne_mixed_Y2000(
  T_mat,
  F_vec,
  D,
  d,
  Vk_over_k = NULL,
  Vc_over_c = NULL,
  a = 0,
  L = NULL,
  x_max = 500L,
  Ne_target = 50,
  census_N = NULL,
  show_Ny = FALSE,
  population = NULL,
  recruit_row = 1L
)

Arguments

T_mat

Numeric matrix (s x s). Survival/transition matrix. Row j, column i gives the probability that an individual in stage i

F_vec

Numeric vector (length s). Total fecundity per stage per year: mean number of propagules (sexual + clonal combined) produced per individual. Used for L and r_i = F_i * D_i.

D

Numeric vector (length s). Stage frequency distribution. Must sum to 1.

d

Numeric vector (length s). Per-stage clonal reproduction fraction. MUST be supplied – there is no default. d_i = 0 : stage i reproduces entirely sexually. d_i = 1 : stage i reproduces entirely clonally. d_i = 0.7 : 70% of stage i reproduction is clonal. Example: d = c(0, 0, 0.8) for a 3-stage population where stages 1 and 2 are sexual only and stage 3 is mostly clonal.

Vk_over_k

Numeric vector (length s). Variance-to-mean ratio of SEXUAL reproductive output per stage (Vk/k_bar)_i. Default rep(1, s) = Poisson: reproductive success is equally distributed among individuals within each stage. Values > 1 reduce Ne (unequal sexual reproductive success).

Vc_over_c

Numeric vector (length s). Variance-to-mean ratio of CLONAL reproductive output per stage (Vc/c_bar)_i. Default rep(1, s) = Poisson: clonal output is equally distributed among individuals within each stage. Values > 1 reduce Ne (some individuals produce many more clonal propagules than others).

a

Numeric scalar. Hardy-Weinberg deviation. Default 0 = random mating. Supply a positive value for inbreeding. Must be between -1 and 1.

L

Numeric scalar (optional). Generation time in years. If NULL, computed internally via T^x iteration (x_max = 500).

x_max

Integer. Maximum age for L iteration (default 500). Ignored if L is supplied directly.

Ne_target

census_N

Numeric or NULL. Actual or expected census population size. If supplied, Ne_at_census = NeN * census_N is added to the output. Default NULL.

show_Ny

Logical. Whether to compute and return Ny/N (annual effective size, Eq. 11). Default FALSE. Note that Ny/N is defined here using the clonal component of the model and is most meaningful when clonal reproduction dominates.

population

Character string. Optional population label.

recruit_row

Integer. The stage (matrix row) that newborns enter, i.e. where F_vec is placed in F_mat. Default 1. Set to a later stage when the first stage is dormancy (e.g. a seed bank). Must name exactly one valid stage.

Details

Note on relationship to the other two functions: When d = rep(0, s), Ne_mixed_Y2000() reproduces Ne_sexual_Y2000() exactly, because Avr(Ad) vanishes. However, Ne_mixed_Y2000() with d = rep(1, s) does NOT reproduce Ne_clonal_Y2000(), because Ne_clonal_Y2000() implements the simplified Equations 10-11 via a different algebraic path (V = 2(1-u2_bar)) that is not the same as the general Eq. 6 with d=1. For purely clonal populations always use Ne_clonal_Y2000() directly.

Value

A named list with elements:

population: Character label
model: "mixed_Y2000"
NeN: Ne/N – generation-time effective size ratio (Eq. 6)
NyN: Ny/N – annual effective size ratio (Eq. 11), or NA if show_Ny = FALSE
L: Generation time used (years)
L_source: "user" or "computed"
d: Per-stage clonal fractions supplied
u_dot: Total annual survival per stage
u_bar: Population mean annual survival
u2_bar: Stage-weighted mean of squared survivals
r_i: Newborn contributions per stage
S_i: Per-stage S values
A_i: Per-stage A values
Avr_S: Recruitment-weighted mean of S_i
Avr_Ad: Recruitment-weighted mean of A_i * d_i
V: Full variance term
V_term1: Between-stage survival variance component
V_term2: Sexual reproductive variance component
V_term3: Clonal reproductive variance component
Vk_over_k: Sexual variance ratio used
Vc_over_c: Clonal variance ratio used
a: Hardy-Weinberg deviation used
Min_N: Minimum census N for Ne >= Ne_target
Ne_target: Ne threshold used

References

Lande R. (1995). Mutation and conservation. Conservation Biology 9: 728-791.

Examples

# ---------------------------------------------------------
# Example 1: 3-stage perennial herb, stage 3 reproduces both
# sexually (seeds) and clonally (rhizomes). Stages 1 and 2
# reproduce sexually only.
# ---------------------------------------------------------
T_herb <- matrix(c(
  0.30, 0.05, 0.00,
  0.40, 0.65, 0.10,
  0.00, 0.20, 0.80
), nrow = 3, byrow = TRUE)

result <- Ne_mixed_Y2000(
  T_mat      = T_herb,
  F_vec      = c(0.0, 0.5, 3.0),
  D          = c(0.60, 0.25, 0.15),
  d          = c(0.0, 0.0, 0.7),   # stage 3 is 70% clonal
  population = "mixed herb"
)
print(result)

# ---------------------------------------------------------
# Example 2: Show Ny/N for a predominantly clonal population
# ---------------------------------------------------------
result_Ny <- Ne_mixed_Y2000(
  T_mat      = T_herb,
  F_vec      = c(0.0, 0.5, 3.0),
  D          = c(0.60, 0.25, 0.15),
  d          = c(0.5, 0.8, 0.9),
  show_Ny    = TRUE,
  population = "predominantly clonal herb"
)
print(result_Ny)

Run Ne_mixed_Y2000 with both observed and expected stage fractions

Description

Run Ne_mixed_Y2000 with both observed and expected stage fractions

Usage

Ne_mixed_Y2000_both(
  T_mat,
  F_vec,
  D_obs,
  d,
  D_exp = NULL,
  Vk_over_k = NULL,
  Vc_over_c = NULL,
  a = 0,
  L = NULL,
  Ne_target = 50,
  census_N = NULL,
  show_Ny = FALSE,
  population = NULL,
  recruit_row = 1L
)

Arguments

T_mat

Survival/transition matrix (s x s).

F_vec

Fecundity vector (length s).

D_obs

Observed stage fractions from field counts.

d

Per-stage clonal fraction vector (length s).

D_exp

Expected (equilibrium) stage fractions. If NULL, derived from stable stage distribution of A.

Vk_over_k

Sexual variance ratio (default Poisson).

Vc_over_c

Clonal variance ratio (default Poisson).

a

Hardy-Weinberg deviation (default 0).

L

Generation time. If NULL, computed internally.

Ne_target

census_N

Numeric or NULL. Actual or expected census population size. If supplied, Ne_at_census = NeN * census_N is added to the output. Default NULL.

show_Ny

Logical. Compute Ny/N? (default FALSE).

population

Character label for the population.

recruit_row

Integer. Stage (matrix row) that newborns enter; where F_vec is placed in F_mat. Default 1. Set to a later stage when the first stage is dormancy (e.g. a seed bank).

Value

A list with two Ne_mixed_Y2000 result objects:

observed: Results using D_obs
expected: Results using D_exp

Sensitivity of Ne/N to generation time L

Description

Sweeps generation time L across a user-defined range for any of the three NeStage model functions. All other inputs are held constant.

Usage

Ne_sensitivity_L(
  model_fn,
  T_mat,
  F_vec,
  D,
  d = NULL,
  L_range = seq(2, 30, by = 2),
  L_ref = NULL,
  Vk_over_k = NULL,
  Vc_over_c = NULL,
  a = 0,
  Ne_target = 5000,
  population = NULL,
  recruit_row = 1L
)

Arguments

model_fn

The model function: Ne_clonal_Y2000, Ne_sexual_Y2000, or Ne_mixed_Y2000.

T_mat

Survival/transition matrix (s x s).

F_vec

Fecundity vector (length s).

D

Stage frequency distribution (length s, sums to 1).

d

Per-stage clonal fraction vector. Required for Ne_mixed_Y2000; ignored otherwise.

L_range

Numeric vector of L values (years) to test. Default seq(2, 30, by = 2).

L_ref

Numeric. Reference L value to mark on the plot (e.g., the computed or published L). If NULL, computed internally from T_mat and F_vec.

Vk_over_k

Sexual variance vector. Default rep(1, s).

Vc_over_c

Clonal variance vector (mixed model only).

a

Hardy-Weinberg deviation. Default 0.

Ne_target

Ne conservation threshold. Default 5000.

population

Character label.

recruit_row

Integer. Stage (matrix row) that newborns enter; where F_vec is placed in F_mat. Default 1. Set to a later stage when the first stage is dormancy (e.g. a seed bank).

Value

A list with:

data: Data frame: L, NeN, Min_N, V, V_term1, V_term2, and V_term3 (for mixed model)
plot: ggplot2 object showing Ne/N vs L
call: Matched call

Examples

# Clonal model -- how sensitive is Ne/N to L for Fritillaria Miz?
T_Miz <- matrix(c(
  0.789, 0.121, 0.054,
  0.007, 0.621, 0.335,
  0.001, 0.258, 0.611
), nrow = 3, byrow = TRUE)

sens <- Ne_sensitivity_L(
  model_fn   = Ne_clonal_Y2000,
  T_mat      = T_Miz,
  F_vec      = c(0.055, 1.328, 2.398),
  D          = c(0.935, 0.038, 0.027),
  L_range    = seq(5, 25, by = 1),
  L_ref      = 13.399,
  population = "Fritillaria Miz"
)
print(sens$data)
sens$plot

Sensitivity of Ne/N to clonal reproductive variance in one stage

Description

Sweeps (Vc/c_bar)_i across a range for a single focal stage. Mixed model only. Under Poisson defaults (Vc/c_bar = 1 = Vk/k_bar), clonal fraction d_i has no effect on Ne. Non-Poisson clonal variance (Vc/c_bar > 1) is required for d_i to influence Ne.

Usage

Ne_sensitivity_Vc(
  T_mat,
  F_vec,
  D,
  d,
  stage_index = NULL,
  stage_name = NULL,
  Vc_range = seq(0.5, 5, by = 0.5),
  Vc_fixed = 1,
  Vk_over_k = NULL,
  a = 0,
  L = NULL,
  Ne_target = 5000,
  population = NULL,
  recruit_row = 1L
)

Arguments

T_mat

Survival/transition matrix (s x s).

F_vec

Fecundity vector (length s).

D

Stage frequency distribution (length s, sums to 1).

d

Per-stage clonal fraction vector (length s). Required.

stage_index

Integer. Which stage to vary. Takes priority over stage_name if both are supplied.

stage_name

Character. Column name of the focal stage in T_mat.

Vc_range

Numeric vector of (Vc/c_bar) values to test. Default seq(0.5, 5, by = 0.5).

Vc_fixed

Numeric. (Vc/c_bar) for all OTHER stages. Default 1.

Vk_over_k

Sexual variance vector. Default rep(1, s).

a

Hardy-Weinberg deviation. Default 0.

L

Generation time. If NULL, computed internally.

Ne_target

Ne conservation threshold. Default 5000.

population

Character label.

recruit_row

Integer. Stage (matrix row) that newborns enter; where F_vec is placed in F_mat. Default 1. Set to a later stage when the first stage is dormancy (e.g. a seed bank).

Value

A list with:

data: Data frame: Vc_over_c, NeN, Min_N, L, V, V_term1, V_term2, V_term3
plot: ggplot2 object showing Ne/N vs Vc/c_bar
call: Matched call

Examples

T_herb <- matrix(c(
  0.30, 0.05, 0.00,
  0.40, 0.65, 0.10,
  0.00, 0.20, 0.80
), nrow = 3, byrow = TRUE)

sens <- Ne_sensitivity_Vc(
  T_mat       = T_herb,
  F_vec       = c(0.0, 0.5, 3.0),
  D           = c(0.60, 0.25, 0.15),
  d           = c(0.0, 0.0, 0.7),
  stage_index = 3,
  Vc_range    = seq(0.5, 6, by = 0.5),
  population  = "mixed herb"
)
print(sens$data)
sens$plot

Sensitivity of Ne/N to sexual reproductive variance in one stage

Description

Sweeps (Vk/k_bar)_i across a range for a single focal stage, holding all other inputs constant. Works with Ne_sexual_Y2000 and Ne_mixed_Y2000.

Usage

Ne_sensitivity_Vk(
  model_fn,
  T_mat,
  F_vec,
  D,
  d = NULL,
  stage_index = NULL,
  stage_name = NULL,
  Vk_range = seq(0.5, 5, by = 0.5),
  Vk_fixed = 1,
  Vc_over_c = NULL,
  a = 0,
  L = NULL,
  Ne_target = 5000,
  population = NULL,
  recruit_row = 1L
)

Arguments

model_fn

The model function to use: Ne_sexual_Y2000 or Ne_mixed_Y2000. Do NOT supply Ne_clonal_Y2000 – sexual reproductive variance does not enter that model.

T_mat

Survival/transition matrix (s x s).

F_vec

Fecundity vector (length s).

D

Stage frequency distribution (length s, sums to 1).

d

Per-stage clonal fraction vector. Required if model_fn = Ne_mixed_Y2000; ignored otherwise.

stage_index

Integer. Which stage to vary. Takes priority over stage_name if both are supplied.

stage_name

Character. Column name of the focal stage in T_mat. Used only if stage_index is NULL.

Vk_range

Numeric vector of (Vk/k_bar) values to test. Default seq(0.5, 5, by = 0.5).

Vk_fixed

Numeric. (Vk/k_bar) for all OTHER stages. Default 1.

Vc_over_c

Clonal variance vector (for Ne_mixed_Y2000 only). Default rep(1, s).

a

Hardy-Weinberg deviation. Default 0.

L

Generation time. If NULL, computed internally.

Ne_target

Ne conservation threshold. Default 5000.

population

Character label.

recruit_row

Integer. Stage (matrix row) that newborns enter; where F_vec is placed in F_mat. Default 1. Set to a later stage when the first stage is dormancy (e.g. a seed bank).

Value

A list with:

data: Data frame: Vk_over_k, NeN, Min_N, L, V, V_term1, V_term2, and V_term3 (for mixed model)
plot: ggplot2 object showing Ne/N vs Vk/k_bar
call: Matched call

Examples

T_herb <- matrix(c(
  0.30, 0.05, 0.00,
  0.40, 0.65, 0.10,
  0.00, 0.20, 0.80
), nrow = 3, byrow = TRUE)

sens <- Ne_sensitivity_Vk(
  model_fn    = Ne_sexual_Y2000,
  T_mat       = T_herb,
  F_vec       = c(0.0, 0.5, 3.0),
  D           = c(0.60, 0.25, 0.15),
  stage_index = 3,
  Vk_range    = seq(0.5, 6, by = 0.5),
  population  = "hypothetical herb"
)
print(sens$data)
sens$plot

Sensitivity of Ne/N to clonal fraction d_i in one stage

Description

Sweeps d_i from 0 to 1 for a single focal stage, holding all other inputs constant. Under Poisson defaults (Vc/c_bar = Vk/k_bar = 1), Ne/N is constant across all d values. Supply Vc_over_c != 1 to see a meaningful sensitivity curve.

Usage

Ne_sensitivity_d(
  T_mat,
  F_vec,
  D,
  d_fixed,
  stage_index = NULL,
  stage_name = NULL,
  d_range = seq(0, 1, by = 0.1),
  Vk_over_k = NULL,
  Vc_over_c = NULL,
  a = 0,
  L = NULL,
  Ne_target = 5000,
  population = NULL,
  recruit_row = 1L
)

Arguments

T_mat

Survival/transition matrix (s x s).

F_vec

Fecundity vector (length s).

D

Stage frequency distribution (length s, sums to 1).

d_fixed

Numeric vector (length s). Clonal fractions for ALL stages. The focal stage value will be overwritten by the sweep. Must be length s.

stage_index

Integer. Which stage to vary. Takes priority over stage_name if both are supplied.

stage_name

Character. Column name of the focal stage in T_mat.

d_range

Numeric vector of d values to test for focal stage. Default seq(0, 1, by = 0.1).

Vk_over_k

Sexual variance vector. Default rep(1, s).

Vc_over_c

Clonal variance vector. Default rep(1, s). Supply values > 1 to see a non-flat sensitivity curve.

a

Hardy-Weinberg deviation. Default 0.

L

Generation time. If NULL, computed internally.

Ne_target

Ne conservation threshold. Default 5000.

population

Character label.

recruit_row

Integer. Stage (matrix row) that newborns enter; where F_vec is placed in F_mat. Default 1. Set to a later stage when the first stage is dormancy (e.g. a seed bank).

Value

A list with:

data: Data frame: d_focal, NeN, Min_N, L, V, V_term1, V_term2, V_term3
plot: ggplot2 object showing Ne/N vs d_i
call: Matched call

Examples

T_herb <- matrix(c(
  0.30, 0.05, 0.00,
  0.40, 0.65, 0.10,
  0.00, 0.20, 0.80
), nrow = 3, byrow = TRUE)

# Under Poisson defaults: flat curve (d_i has no effect)
sens_poisson <- Ne_sensitivity_d(
  T_mat       = T_herb,
  F_vec       = c(0.0, 0.5, 3.0),
  D           = c(0.60, 0.25, 0.15),
  d_fixed     = c(0.0, 0.0, 0.5),
  stage_index = 3,
  population  = "mixed herb (Poisson)"
)
sens_poisson$plot

# With non-Poisson clonal variance: d_i matters
sens_nonpoisson <- Ne_sensitivity_d(
  T_mat       = T_herb,
  F_vec       = c(0.0, 0.5, 3.0),
  D           = c(0.60, 0.25, 0.15),
  d_fixed     = c(0.0, 0.0, 0.5),
  stage_index = 3,
  Vc_over_c   = c(1, 1, 3),
  population  = "mixed herb (Vc/c_bar = 3 in stage 3)"
)
sens_nonpoisson$plot

Variance effective population size for 100% sexual stage-structured populations

Description

Implements Equation 6 of Yonezawa et al. (2000) with d_i = 0 (no clonal reproduction) for populations that reproduce exclusively through sexual means. The annual effective size Ny is not computed as it applies only to clonal populations (Eq. 11).

Usage

Ne_sexual_Y2000(
  T_mat,
  F_vec,
  D,
  Vk_over_k = NULL,
  a = 0,
  L = NULL,
  x_max = 500L,
  Ne_target = 50,
  census_N = NULL,
  population = NULL,
  recruit_row = 1L
)

Arguments

T_mat

Numeric matrix (s x s). The survival/transition matrix. Row j, column i gives the probability that an individual in stage i Column sums must be <= 1 (total annual survival per stage).

F_vec

Numeric vector of length s. Fecundity of each stage: the mean number of offspring (seeds, juveniles) produced per individual per year through sexual reproduction. Used to compute L and r_i = F_i * D_i. Set F_vec = NULL only if supplying L directly AND the function does not need r_i (not recommended).

D

Numeric vector of length s. Stage frequency distribution: the proportion of the population in each stage. Must sum to 1.

Vk_over_k

Numeric vector of length s. The variance-to-mean ratio of sexual reproductive output per stage: (Vk / k_bar)_i. Default is rep(1, s) – Poisson reproductive variance, meaning reproductive success is equally distributed among individuals within each stage. Values > 1 indicate that some individuals reproduce much more than others (common when pollinators show strong preferences, or when resources are limiting), which reduces Ne. Values < 1 indicate more equal than random reproductive success, which increases Ne.

a

Numeric scalar. Deviation from Hardy-Weinberg proportions. Default 0 = random mating (appropriate for most outcrossing species with no selfing). Supply a positive value if the population has known inbreeding (e.g., from FIS estimates). Must be between -1 and 1.

L

x_max

Integer. Maximum age for the L iteration (default 500). Ignored if L is supplied directly.

Ne_target

Numeric. Ne conservation threshold for computing the minimum census size N needed to achieve Ne >= Ne_target. Common choices: 50 (Franklin 1980, avoid inbreeding), 500 (Franklin 1980, maintain quantitative variation), 5000 (Lande 1995, long-term evolutionary potential). Set to the threshold most relevant for your study system. Default 50.

census_N

Numeric or NULL. The actual (or expected) census population size. If supplied, Ne_at_census = NeN * census_N is reported in the output, showing the Ne your population is likely achieving right now. Default NULL (not reported).

population

Character string. Optional label for the population.

recruit_row

Integer. The stage (matrix row) that offspring enter, i.e. where F_vec is placed in F_mat. Default 1. Set to a later stage when the first stage is dormancy (e.g. a seed bank), so recruits enter the active stage instead. Must name exactly one valid stage.

Value

A named list with the following elements:

population: Character label
model: "sexual_Y2000"
NeN: Ne/N – generation-time effective size ratio (Eq. 6)
L: Generation time used (years)
L_source: "user" or "computed"
u_dot: Total annual survival per stage (colSums of T_mat)
u_bar: Population mean annual survival
u2_bar: Stage-weighted mean of squared survivals
r_i: Newborn contributions per stage (F_vec * D)
S_i: Per-stage S values used in Avr(S)
Avr_S: Recruitment-weighted mean of S_i
V: Full variance term from Eq. 6
V_component1: Between-stage survival variance component
V_component2: Reproductive variance component
Vk_over_k: Variance-to-mean ratio of sexual output used
a: Hardy-Weinberg deviation used
Min_N: Minimum census N for Ne >= Ne_target
Ne_target: Ne threshold used
Ne_at_census: Ne at the supplied census_N (NULL if not supplied)
census_N: Census size supplied by user (NULL if not supplied)

References

Lande R. (1995). Mutation and conservation. Conservation Biology 9: 728-791.

Examples

# ---------------------------------------------------------
# Example 1: Simple 3-stage plant, Poisson defaults
# A hypothetical outcrossing perennial herb with three stages:
#   Stage 1: seedling/juvenile (high mortality, no reproduction)
#   Stage 2: vegetative adult  (moderate survival, low reproduction)
#   Stage 3: reproductive adult (high survival, high reproduction)
# ---------------------------------------------------------
T_plant <- matrix(c(
  0.30, 0.05, 0.00,
  0.40, 0.65, 0.10,
  0.00, 0.20, 0.80
), nrow = 3, byrow = TRUE)

F_plant <- c(0.0, 0.5, 3.0)   # seeds per individual per stage per year
D_plant <- c(0.60, 0.25, 0.15) # observed stage fractions

result <- Ne_sexual_Y2000(
  T_mat      = T_plant,
  F_vec      = F_plant,
  D          = D_plant,
  population = "hypothetical herb"
)
print(result)

# ---------------------------------------------------------
# Example 2: Same population, high reproductive variance in stage 3
# Vk/k_bar = 3 for reproductive adults -- pollinator-limited, so only
# a few adults contribute most of the seeds in any given year.
# This should reduce Ne relative to Example 1.
# ---------------------------------------------------------
result_highvar <- Ne_sexual_Y2000(
  T_mat       = T_plant,
  F_vec       = F_plant,
  D           = D_plant,
  Vk_over_k   = c(1, 1, 3),
  population  = "hypothetical herb (high repro variance stage 3)"
)
print(result_highvar)
# Ne/N should be lower than Example 1.

# ---------------------------------------------------------
# Example 3: Supply L directly from a published source
# ---------------------------------------------------------
result_Luser <- Ne_sexual_Y2000(
  T_mat      = T_plant,
  F_vec      = F_plant,
  D          = D_plant,
  L          = 8.5,
  population = "hypothetical herb (published L)"
)
print(result_Luser)

Package {NeStage}

Variance effective population size for 100% clonal stage-structured populations

Description

Usage

Arguments

Value

References

Examples

Run Ne_clonal_Y2000 with both observed and expected stage fractions

Description

Usage

Arguments

Value

Examples

Variance effective population size for mixed sexual/clonal stage-structured populations

Description

Usage

Arguments

Details

Value

References

Examples

Run Ne_mixed_Y2000 with both observed and expected stage fractions

Description

Usage

Arguments

Value

Sensitivity of Ne/N to generation time L

Description

Usage

Arguments

Value

Examples

Sensitivity of Ne/N to clonal reproductive variance in one stage

Description

Usage

Arguments

Value

Examples

Sensitivity of Ne/N to sexual reproductive variance in one stage

Description

Usage

Arguments

Value

Examples

Sensitivity of Ne/N to clonal fraction d_i in one stage

Description

Usage

Arguments

Value

Examples

Variance effective population size for 100% sexual stage-structured populations

Description

Usage

Arguments

Value

References

Examples