Author: Raymond L. Tremblay

# NeStage: Quick Start Guide

#### Raymond L. Tremblay

# 1 Overview

This vignette shows the minimum code needed to run each of the three core NeStage functions. If you have your demographic data ready, you should be able to get results in under five minutes.

For full mathematical background and replication of Yonezawa et al. (2000) Table 4, see `vignette("Ne_Yonezawa2000")`.

# 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