Package 'NeStage' reference manual

Title:	Effective Population Size from Stage-Structured Populations
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.
Authors:	Raymond L. Tremblay [aut, cre]
Maintainer:	Raymond L. Tremblay <[email protected]>
License:	GPL-3
Version:	0.8.0
Built:	2026-05-23 05:18:03 UTC
Source:	https://github.com/raymondltremblay/nestage

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
)
Ne_clonal_Y2000(
  T_mat,
  F_vec = NULL,
  D,
  L = NULL,
  x_max = 500L,
  Ne_target = 50,
  census_N = NULL,
  population = NULL
)

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) via the stable stage distribution of A = T_mat + F_mat. 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.

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

# ---------------------------------------------------------
# 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
)
Ne_clonal_Y2000_both(
  T_mat,
  F_vec,
  D_obs,
  D_exp = NULL,
  L = NULL,
  Ne_target = 50,
  census_N = NULL,
  population = NULL
)

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.

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

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
)
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
)

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.

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)


# ---------------------------------------------------------
# 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
)
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
)

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.

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 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
)
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
)

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.

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

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

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
)
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
)

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.

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

# 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
)
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
)

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.

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

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
)
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
)

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.

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

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

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
)
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
)

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.

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)

# ---------------------------------------------------------
# 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'

Help Index

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 clonal fraction d_i in one stage

Description

Usage

Arguments

Value

Examples

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

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

Description

Usage

Arguments

Value

References

Examples