2 What data do you need?

All three functions share the same three core inputs. Before running any function, check that your data meets these requirements.

2.1 `T_mat` — Survival/transition matrix

A square numeric matrix of size s × s, where s is the number of life-history stages (e.g., seedling, juvenile, adult = 3 stages).
Entry in row j, column i is the probability that an individual in stage i this year is found in stage j next year.
Column sums must be ≤ 1 (total annual survival per stage cannot exceed 1).
No negative values, no NA or Inf.

# Example: 3-stage plant (seedling, juvenile, adult)
T_mat <- matrix(c(
  0.30, 0.05, 0.00,   # row 1: transitions INTO stage 1
  0.40, 0.65, 0.10,   # row 2: transitions INTO stage 2
  0.00, 0.20, 0.80    # row 3: transitions INTO stage 3
), nrow = 3, byrow = TRUE)

# Quick check: column sums must all be <= 1
colSums(T_mat)   # should all be <= 1.0

2.2 `F_vec` — Fecundity vector

A numeric vector of length s: the mean number of offspring (or clonal propagules) produced per individual per stage per year.
Must be ≥ 0 for all stages; at least one stage must have F_vec > 0.
For clonal populations: propagules (bulblets, stolons, etc.).
For sexual populations: seeds or juvenile recruits per adult per year.

# Example: only adults (stage 3) reproduce
F_vec <- c(0.0, 0.5, 3.0)

2.3 `D` — Stage frequency distribution

A numeric vector of length s: the proportion of the population in each stage. Must sum to 1.
Use observed field counts: D <- counts / sum(counts)
Or use the stable stage distribution from the transition matrix (see vignette("Ne_Yonezawa2000") for details).

# Example: from field counts
counts <- c(120, 50, 30)
D <- counts / sum(counts)
D        # c(0.60, 0.25, 0.15)
sum(D)   # must equal 1

2.4 `L` — Generation time (optional but recommended)

A single positive number: the mean generation time in years.
If you supply L directly from a published source, it is used as-is (recommended for replicating published results).
If you omit L, it is computed internally from T_mat and F_vec using the Yonezawa (2000) definition (iterates to age 500).

2.5 Quick data checklist

Input	Type	Length / Size	Constraint
`T_mat`	numeric matrix	s × s	col sums ≤ 1, ≥ 0
`F_vec`	numeric vector	s	≥ 0, at least one > 0
`D`	numeric vector	s	sums to 1, ≥ 0
`L`	numeric scalar	1	> 0 (optional)

3 `Ne_clonal_Y2000()` — Purely clonal populations

Use this function when your population reproduces exclusively through clonal means (bulblets, stolons, rhizomes, vegetative fragmentation) and sexual reproduction contributes nothing to recruitment.

It implements Equations 10 and 11 of Yonezawa et al. (2000) and returns Ne/N (generation-time effective size ratio), Ny/N (annual effective size ratio), and the minimum census size Min_N needed to achieve your Ne_target.

library(NeStage)

# --- Your data goes here ---
T_mat <- matrix(c(
  0.789, 0.121, 0.054,
  0.007, 0.621, 0.335,
  0.001, 0.258, 0.611
), nrow = 3, byrow = TRUE)

F_vec <- c(0.055, 1.328, 2.398)   # clonal propagules per stage per year
D     <- c(0.935, 0.038, 0.027)   # observed stage fractions (must sum to 1)
L     <- 13.399                    # generation time (years); omit to compute

# --- Run the function ---
result <- Ne_clonal_Y2000(
  T_mat      = T_mat,
  F_vec      = F_vec,
  D          = D,
  L          = L,
  Ne_target  = 5000,        # minimum Ne for long-term viability (Lande 1995)
  population = "My population"
)

print(result)

## 
## === NeStage: Clonal population Ne (Yonezawa 2000, Eq. 10-11) ===
##   Population  : My population
##   Model       : clonal_Y2000
## 
##   --- Stage survival ---
##     u_{.stage_1} = 0.7970
##     u_{.stage_2} = 1.0000
##     u_{.stage_3} = 1.0000
##     u2_bar (stage-weighted mean of squared survivals) = 0.658920
## 
##   --- Generation time ---
##     L = 13.399 yr  [source: user]
## 
##   --- Effective size ratios ---
##     Ny/N (annual, Eq. 11)          = 2.932
##     Ne/N (generation-time, Eq. 10) = 0.219
## 
##   --- Conservation threshold ---
##     Ne target                      = 5000
##     Minimum census size N          = 22851
##     (Ne/N = 0.219 => need N >= 22851 for Ne >= 5000)

3.0.1 Key outputs

Output	Meaning
`result$NeN`	Ne/N — how large Ne is relative to census size N
`result$NyN`	Ny/N — annual effective size ratio
`result$Min_N`	Minimum census N to achieve Ne >= `Ne_target`
`result$L`	Generation time used
`result$u2_bar`	Stage-weighted mean of squared survivals (key intermediate)

4 `Ne_sexual_Y2000()` — Purely sexual populations

Use this function when your population reproduces exclusively through sexual means (seeds, spores, offspring) and clonal reproduction plays no role. This applies to most vertebrates, annual plants, and outcrossing trees.

It implements Equation 6 of Yonezawa (2000) with d_i = 0 (no clonal fraction). Note that Ny/N is not computed for sexual populations — it is defined only for the clonal model.

# --- Your data goes here ---
T_mat <- 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_vec <- c(0.0, 0.5, 3.0)      # seeds/offspring per individual per stage
D     <- c(0.60, 0.25, 0.15)   # observed stage fractions (must sum to 1)

# --- Run the function ---
result_sex <- Ne_sexual_Y2000(
  T_mat      = T_mat,
  F_vec      = F_vec,
  D          = D,
  # L omitted: computed internally from T_mat and F_vec
  Ne_target  = 5000,
  population = "My sexual population"
)

print(result_sex)

## 
## === NeStage: Sexual population Ne (Yonezawa 2000, Eq. 6, d=0) ===
##   Population  : My sexual population
##   Model       : sexual_Y2000
## 
##   --- Stage survival ---
##     u_{.stage_1} = 0.7000
##     u_{.stage_2} = 0.9000
##     u_{.stage_3} = 0.9000
##     u_bar  (population mean annual survival)          = 0.780000
##     u2_bar (stage-weighted mean of squared survivals) = 0.618000
## 
##   --- Reproductive parameters ---
##     a (Hardy-Weinberg deviation)                      = 0.0000
##     Vk/k_bar (stage_1) = 1.0000
##     Vk/k_bar (stage_2) = 1.0000
##     Vk/k_bar (stage_3) = 1.0000
##     Avr(S) (recruitment-weighted mean S_i)            = 2.000000
## 
##   --- Variance decomposition ---
##     V component 1 (between-stage survival variance)   = 0.019200
##     V component 2 (reproductive variance)             = 0.440000
##     V total                                           = 0.459200
## 
##   --- Generation time ---
##     L = 5.802 yr  [source: computed]
## 
##   --- Effective size ratio ---
##     Ne/N (generation-time, Eq. 6) = 0.751
##     Note: Ny/N is not defined for purely sexual populations.
## 
##   --- Conservation threshold ---
##     Ne target              = 5000 (minimum Ne for viability)
##     Minimum census size N  = 6661
##     (Ne/N = 0.751 => need N >= 6661 for Ne >= 5000)

4.0.1 Optional: adjust reproductive variance `Vk_over_k`

The parameter Vk_over_k controls how unequal reproductive success is among individuals within each stage. It is the variance-to-mean ratio of sexual reproductive output, written (V_k / k-bar)_i for stage i.

The default is Vk_over_k = 1 for all stages (Poisson variance). This means every individual in a stage has an equal chance of reproducing — no individual is consistently a better or worse reproducer. This is a reasonable starting assumption when you have no data on reproductive inequality.

When should you increase it above 1? - A few dominant plants produce most of the seeds while others produce few - Pollinators strongly prefer certain individuals over others - Resource limitation means only the largest or most competitive individuals reproduce successfully in a given year - You have field data showing high variance in seed or offspring counts among individuals of the same stage

What happens to Ne when Vk_over_k > 1? Fewer individuals effectively contribute genes to the next generation, which means the population behaves genetically as if it were smaller than it actually is — Ne decreases. A value of 3 means the variance in reproductive output is three times what you would expect by chance.

In practice: - Vk_over_k = 1 — Poisson default, equal reproductive success - Vk_over_k = 2 — moderate inequality, common in many plant populations - Vk_over_k = 5+ — high inequality, e.g. wind-pollinated trees or highly clumped resources

# Stage 3 adults have high reproductive variance (pollinator-limited)
# Stages 1 and 2 kept at Poisson default (= 1)
result_highvar <- Ne_sexual_Y2000(
  T_mat     = T_mat,
  F_vec     = F_vec,
  D         = D,
  Vk_over_k = c(1, 1, 3),   # stage 3: Vk/k_bar = 3
  Ne_target = 5000
)
print(result_highvar)
# Ne/N will be lower than the Poisson default above

4.0.2 Key outputs

Output	Meaning
`result$NeN`	Ne/N — generation-time effective size ratio
`result$Min_N`	Minimum census N for Ne >= `Ne_target`
`result$V`	Full variance term from Eq. 6
`result$V_component1`	Between-stage survival variance
`result$V_component2`	Reproductive variance component

5 `Ne_mixed_Y2000()` — Mixed sexual + clonal populations

Use this function when your population reproduces through both sexual and clonal means, with each stage potentially having a different mix. Examples include perennial herbs with both seeds and vegetative propagules, grasses producing seeds and tillers, and corals that spawn and fragment.

It implements the full general Equation 6 of Yonezawa (2000). One additional required input compared to the other two functions is d — the per-stage clonal fraction.

# --- Your data goes here ---
T_mat <- 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_vec <- c(0.0, 0.5, 3.0)      # total fecundity per stage (sexual + clonal)
D     <- c(0.60, 0.25, 0.15)   # observed stage fractions (must sum to 1)

# d: clonal fraction per stage
#   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
d <- c(0.0, 0.0, 0.7)   # only adults (stage 3) reproduce clonally

# --- Run the function ---
result_mix <- Ne_mixed_Y2000(
  T_mat      = T_mat,
  F_vec      = F_vec,
  D          = D,
  d          = d,
  # Vk_over_k and Vc_over_c default to rep(1, s) -- Poisson variance
  Ne_target  = 5000,
  population = "My mixed population"
)

print(result_mix)

## 
## === NeStage: Mixed sexual/clonal Ne (Yonezawa 2000, Eq. 6) ===
##   Population  : My mixed population
##   Model       : mixed_Y2000
## 
##   --- Clonal fractions per stage (d_i) ---
##     d_stage_1 = 0.0000  (0% clonal, 100% sexual)
##     d_stage_2 = 0.0000  (0% clonal, 100% sexual)
##     d_stage_3 = 0.7000  (70% clonal, 30% sexual)
## 
##   --- Stage survival ---
##     u_{.stage_1} = 0.7000
##     u_{.stage_2} = 0.9000
##     u_{.stage_3} = 0.9000
##     u_bar  (population mean annual survival)          = 0.780000
##     u2_bar (stage-weighted mean of squared survivals) = 0.618000
## 
##   --- Reproductive parameters ---
##     a (Hardy-Weinberg deviation)                      = 0.0000
##     Vk/k_bar (stage_1) = 1.0000
##     Vk/k_bar (stage_2) = 1.0000
##     Vk/k_bar (stage_3) = 1.0000
##     Vc/c_bar (stage_1) = 1.0000
##     Vc/c_bar (stage_2) = 1.0000
##     Vc/c_bar (stage_3) = 1.0000
##     Avr(S)  (sexual reproductive variance term)       = 2.000000
##     Avr(Ad) (clonal reproductive variance term)       = 0.000000
## 
##   --- Variance decomposition ---
##     V term 1 (between-stage survival variance)        = 0.019200
##     V term 2 (sexual reproductive variance)           = 0.440000
##     V term 3 (clonal reproductive variance)           = 0.000000
##     Note: V term 3 = 0 because Vc/c_bar == Vk/k_bar and a == 0.
##            Supply Vc_over_c != 1 to model unequal clonal variance.
##     V total                                           = 0.459200
## 
##   --- Generation time ---
##     L = 5.802 yr  [source: computed]
## 
##   --- Effective size ratios ---
##     Ne/N (generation-time, Eq. 6)  = 0.751
##     Ny/N                           = not requested (set show_Ny = TRUE)
## 
##   --- Conservation threshold ---
##     Ne target              = 5000
##     Minimum census size N  = 6661
##     (Ne/N = 0.751 => need N >= 6661 for Ne >= 5000)

5.0.1 The `d` vector — most common source of confusion

# All stages reproduce sexually only (equivalent to Ne_sexual_Y2000)
d <- c(0, 0, 0)

# All stages reproduce clonally only
d <- c(1, 1, 1)

# Only the largest stage (stage 3) has clonal reproduction
d <- c(0, 0, 1)

# Gradual increase in clonal fraction across stages
d <- c(0.1, 0.4, 0.8)

5.0.2 Key outputs

Output	Meaning
`result$NeN`	Ne/N — generation-time effective size ratio
`result$Min_N`	Minimum census N for Ne >= `Ne_target`
`result$V`	Full variance term from Eq. 6
`result$V_term1`	Between-stage survival variance
`result$V_term2`	Sexual reproductive variance
`result$V_term3`	Clonal reproductive variance (0 under Poisson defaults)

6 Which function should I use?

My population reproduces via…	Function to use
Clonal only (no sexual)	`Ne_clonal_Y2000()`
Sexual only (no clonal)	`Ne_sexual_Y2000()`
Both sexual and clonal	`Ne_mixed_Y2000()`
Unsure / want to compare	Run all three and compare `Ne/N`

7 Interpreting the results

A few benchmarks to help you interpret Ne/N:

Ne/N ~ 0.10 is the empirical median across 102 wildlife species (Frankham 1995). Values below this suggest higher-than-average genetic vulnerability.
Ne >= 50 is the short-term threshold to avoid inbreeding depression (Franklin 1980).
Ne >= 500 maintains quantitative genetic variation (Franklin 1980).
Ne >= 5000 is the long-term evolutionary viability threshold (Lande 1995) — the default Ne_target in all NeStage functions.

The Min_N output tells you directly: “Your population needs at least this many individuals to achieve your Ne target.”

8 Next steps

For full mathematical derivations and replication of Yonezawa (2000) Table 4, see vignette("Ne_Yonezawa2000").
For sensitivity analysis (sweeping Vk, Vc, d, or L), see vignette("NeStage_sensitivity").
For full function documentation: ?Ne_clonal_Y2000, ?Ne_sexual_Y2000, ?Ne_mixed_Y2000.

9 References

Frankham R. (1995). Effective population size/adult population size ratios in wildlife: a review. Genetical Research 66: 95–107.

Franklin I.R. (1980). Evolutionary change in small populations. In: Soule M.E. & Wilcox B.A. (eds) Conservation Biology: An Evolutionary-Ecological Perspective. Sinauer Associates, pp. 135–149.

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

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. https://doi.org/10.1111/j.0014-3820.2000.tb01244.x

sessionInfo()

## R version 4.5.2 (2025-10-31)
## Platform: x86_64-apple-darwin20
## Running under: macOS Monterey 12.7.6
## 
## Matrix products: default
## BLAS:   /Library/Frameworks/R.framework/Versions/4.5-x86_64/Resources/lib/libRblas.0.dylib 
## LAPACK: /Library/Frameworks/R.framework/Versions/4.5-x86_64/Resources/lib/libRlapack.dylib;  LAPACK version 3.12.1
## 
## locale:
## [1] C/en_US.UTF-8/en_US.UTF-8/C/en_US.UTF-8/en_US.UTF-8
## 
## time zone: America/Puerto_Rico
## tzcode source: internal
## 
## attached base packages:
## [1] stats     graphics  grDevices utils     datasets  methods   base     
## 
## other attached packages:
## [1] knitr_1.51    purrr_1.2.1   tidyr_1.3.2   dplyr_1.2.0   ggplot2_4.0.2
## [6] expm_1.0-0    Matrix_1.7-4  NeStage_0.8.0
## 
## loaded via a namespace (and not attached):
##  [1] vctrs_0.7.1        cli_3.6.5          rlang_1.1.7        xfun_0.56         
##  [5] otel_0.2.0         generics_0.1.4     S7_0.2.1           jsonlite_2.0.0    
##  [9] labeling_0.4.3     glue_1.8.0         htmltools_0.5.9    sass_0.4.10       
## [13] scales_1.4.0       rmarkdown_2.30     grid_4.5.2         tibble_3.3.1      
## [17] evaluate_1.0.5     jquerylib_0.1.4    fastmap_1.2.0      yaml_2.3.12       
## [21] lifecycle_1.0.5    compiler_4.5.2     RColorBrewer_1.1-3 pkgconfig_2.0.3   
## [25] rstudioapi_0.18.0  farver_2.1.2       lattice_0.22-9     digest_0.6.39     
## [29] R6_2.6.1           tidyselect_1.2.1   pillar_1.11.1      magrittr_2.0.4    
## [33] bslib_0.10.0       withr_3.0.2        tools_4.5.2        gtable_0.3.6      
## [37] cachem_1.1.0

NeStage: Quick Start Guide

Raymond L. Tremblay

1 Overview

2 What data do you need?

2.1 `T_mat` — Survival/transition matrix

2.2 `F_vec` — Fecundity vector

2.3 `D` — Stage frequency distribution

2.4 `L` — Generation time (optional but recommended)

2.5 Quick data checklist

3 `Ne_clonal_Y2000()` — Purely clonal populations

3.0.1 Key outputs

4 `Ne_sexual_Y2000()` — Purely sexual populations

4.0.1 Optional: adjust reproductive variance `Vk_over_k`

4.0.2 Key outputs

5 `Ne_mixed_Y2000()` — Mixed sexual + clonal populations

5.0.1 The `d` vector — most common source of confusion

5.0.2 Key outputs

6 Which function should I use?

7 Interpreting the results

8 Next steps

9 References

NeStage: Quick Start Guide

Raymond L. Tremblay

1 Overview

2 What data do you need?

2.1 T_mat — Survival/transition matrix

2.2 F_vec — Fecundity vector

2.3 D — Stage frequency distribution

2.4 L — Generation time (optional but recommended)

2.5 Quick data checklist

3 Ne_clonal_Y2000() — Purely clonal populations

3.0.1 Key outputs

4 Ne_sexual_Y2000() — Purely sexual populations

4.0.1 Optional: adjust reproductive variance Vk_over_k

4.0.2 Key outputs

5 Ne_mixed_Y2000() — Mixed sexual + clonal populations

5.0.1 The d vector — most common source of confusion

5.0.2 Key outputs

6 Which function should I use?

7 Interpreting the results

8 Next steps

9 References

2.1 `T_mat` — Survival/transition matrix

2.2 `F_vec` — Fecundity vector

2.3 `D` — Stage frequency distribution

2.4 `L` — Generation time (optional but recommended)

3 `Ne_clonal_Y2000()` — Purely clonal populations

4 `Ne_sexual_Y2000()` — Purely sexual populations

4.0.1 Optional: adjust reproductive variance `Vk_over_k`

5 `Ne_mixed_Y2000()` — Mixed sexual + clonal populations

5.0.1 The `d` vector — most common source of confusion