| Type: | Package |
| Title: | Effective Population Size from Stage-Structured Populations |
| Version: | 0.8.0 |
| Date: | 2026-03-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 |
| RoxygenNote: | 7.3.3 |
| 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 |
| NeedsCompilation: | no |
| Packaged: | 2026-03-12 14:34:38 UTC; raymondtremblay |
| Repository: | CRAN |
| Date/Publication: | 2026-03-17 18:20:15 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
)
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
populationargument)- 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
)
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 |
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 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
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
)
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 |
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. |
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
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.tb01243.x
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
)
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 |
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. |
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 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
)
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
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
)
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
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
)
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
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
)
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
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
)
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 |
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 match a specific published value. |
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
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.tb01243.x
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)