Explain Density Dependence Settings

A diagnostic function that takes life cycle parameters and optional habitat capacity data and generates a human-readable explanation of what density dependence will be applied in the population model.

This function helps users understand:

Whether s0.1.det (fry survival) will be optimized or use original values
Which compensation ratio stages have active density dependence (cr > 1)
Which Beverton-Holt or Hockey-stick stages are enabled
What carrying capacity (K) values will be used for each life stage
Any potential configuration warnings

Usage

explain_dd_settings(
  life_cycles,
  habitat_dd_k = NULL,
  HUC_ID = NULL,
  verbose = TRUE
)

Arguments

life_cycles: A data frame with life cycle parameters. Must have columns Name and Value (case-insensitive). This is the same format as used by pop_model_setup.
habitat_dd_k: Optional data frame with habitat capacity values by location. Should have a HUC_ID column and columns like k_stage_0_mean, k_stage_1_mean, etc. This is the same format as used by build_k_for_proj_dd.
HUC_ID: Character. The location identifier to look up in habitat_dd_k. Required if habitat_dd_k is provided.
verbose: Logical. If TRUE (default), prints the explanation to the console. Set to FALSE to suppress output and only return the list.

Value

Invisibly returns a list with the following components:

explanation: Character string with the full human-readable explanation
summary: List with population_type, n_stages, adult_k, dd_methods, s0_adjusted
s0_details: List with original_s0, s0_1_det, behavior ("ORIGINAL" or "OPTIMIZED"), reason, and note (explains why s0 values differ, or NULL if unchanged)
compensation_ratios: List with enabled, values, stages_with_effect
bh_dd_stages: List with enabled, all_stages, beverton_holt, hockey_stick, and note (identifies missing K columns or stable-stage-derived K used with location-specific DD, or NULL if no issues)
k_values: List with stages (named list of K values by stage, each with value and source) and note (identifies K columns without corresponding DD flags, or NULL if all K columns are used)
warnings: Character vector of any configuration warnings

Details

The function analyzes the life cycle parameters to determine:

s0.1.det Optimization:

OPTIMIZED: When k is set AND no BH/HS stages are enabled. The fry survival rate is adjusted to give lambda = 1.0 at equilibrium.
ORIGINAL: When k is NA, OR when any BH/HS stage is enabled. The original S0 value from the life cycle file is used.

Compensation Ratio DD: Applied via the D.mx matrix during projection when k is set. Only stages with cr > 1 have active density dependence.

Beverton-Holt / Hockey-Stick DD: Applied in dd.N.bh() after matrix projection when any of these parameters are set to TRUE/1: bh_stage_0, bh_stage_1, hs_stage_0, dd_hs_0, bh_spawners, hs_spawners, etc.

Examples

# Create a simple resident life cycle with compensation ratios
life_cycles <- data.frame(
  Name = c("Nstage", "anadromous", "k", "S0", "SE",
           "surv_1", "surv_2", "surv_3", "surv_4",
           "cr_E", "cr_0", "cr_1", "cr_2", "cr_3", "cr_4",
           "mat_1", "mat_2", "mat_3", "mat_4",
           "year_1", "year_2", "year_3", "year_4",
           "events", "eps", "int", "SR",
           "eps_sd", "egg_rho", "M.cv", "M.rho"),
  Value = c(4, FALSE, 500, 0.3, 0.1,
            0.5, 0.6, 0.8, 0.9,
            1, 3.5, 2.8, 2.0, 1.5, 1,
            0, 0, 0, 1,
            1, 1, 1, 1,
            1, 3000, 1, 0.5,
            100, 0.1, 0.1, 0.1),
  stringsAsFactors = FALSE
)

# Explain what DD will be applied
result <- explain_dd_settings(life_cycles)
#> ============================================================
#>        DENSITY DEPENDENCE CONFIGURATION SUMMARY
#> ============================================================
#> 
#> POPULATION TYPE: Resident
#> NUMBER OF STAGES: 4
#> ADULT CAPACITY (k): 500
#> 
#> ------------------------------------------------------------
#> 1. FRY SURVIVAL (s0.1.det) ADJUSTMENT
#> ------------------------------------------------------------
#>    Original S0 value: 0.3
#>    s0.1.det will be: OPTIMIZED
#>    Reason: s0.1.det will be optimized to give lambda = 1.0 at equilibrium
#> 
#>    Note: The actual s0.1.det value is calculated by finding the S0
#>    that makes the dominant eigenvalue (lambda) = 1.0 when the
#>    population is at carrying capacity.
#> 
#> ------------------------------------------------------------
#> 2. COMPENSATION RATIO DENSITY DEPENDENCE
#> ------------------------------------------------------------
#>    Status: ENABLED (applied via D.mx matrix during projection)
#>    Applied when: Each time step, survival rates are multiplied by
#>                  density-dependent factors based on N/K ratio.
#> 
#>    Compensation ratios by stage:
#>      - cr_E: 1 (no DD effect)
#>      - cr_0: 3.5 (DD effect active)
#>      - cr_1: 2.8 (DD effect active)
#>      - cr_2: 2 (DD effect active)
#>      - cr_3: 1.5 (DD effect active)
#>      - cr_4: 1 (no DD effect)
#> 
#>    Stages with active DD: cr_0, cr_1, cr_2, cr_3
#> 
#> ------------------------------------------------------------
#> 3. BEVERTON-HOLT / HOCKEY-STICK DENSITY DEPENDENCE
#> ------------------------------------------------------------
#>    Status: DISABLED (no bh_stage_X or hs_stage_X flags set to TRUE)
#> 
#>    To enable, set any of these to TRUE/1 in life_cycles:
#>      - bh_stage_0, bh_stage_1, ... (Beverton-Holt)
#>      - hs_stage_0, dd_hs_0, ... (Hockey-stick)
#>      - bh_spawners, hs_spawners (spawner constraints)
#> 
#> ------------------------------------------------------------
#> 4. CARRYING CAPACITY (K) VALUES BY STAGE
#> ------------------------------------------------------------
#>    K0: Derived via stable stage distribution
#>       Source: stable_stage_from_adult_k
#>    K1: Derived via stable stage distribution
#>       Source: stable_stage_from_adult_k
#>    K2: Derived via stable stage distribution
#>       Source: stable_stage_from_adult_k
#>    K3: Derived via stable stage distribution
#>       Source: stable_stage_from_adult_k
#>    K4: Derived via stable stage distribution
#>       Source: stable_stage_from_adult_k
#> 
#> ------------------------------------------------------------
#> 6. CONFIGURATION NOTES
#> ------------------------------------------------------------
#>    [s0 Optimization]
#>    The original fry survival (S0 = 0.3) will be replaced with an optimized value (s0.1.det) calculated to achieve population equilibrium (lambda = 1.0) when the population is at carrying capacity. This ensures the population stabilizes at K under deterministic conditions with compensation ratio density dependence.
#> 
#> ------------------------------------------------------------
#> SUMMARY
#> ------------------------------------------------------------
#>    Active DD methods: Compensation Ratios (via D.mx)
#>    s0.1.det: OPTIMIZED
#> 
#> ============================================================ 

# Access the structured results
result$summary$dd_methods
#> [1] "Compensation Ratios (via D.mx)"
result$s0_details$behavior
#> [1] "OPTIMIZED"
result$compensation_ratios$stages_with_effect
#> [1] "cr_0" "cr_1" "cr_2" "cr_3"

# With habitat capacity data
habitat_k <- data.frame(
  HUC_ID = c("1", "2", "3"),
  k_stage_0_mean = c(10000, 20000, 15000),
  k_stage_1_mean = c(5000, 10000, 7500)
)

# Add BH stage to life cycle
life_cycles_bh <- rbind(life_cycles,
  data.frame(Name = "bh_stage_0", Value = "TRUE", stringsAsFactors = FALSE)
)

result2 <- explain_dd_settings(
  life_cycles = life_cycles_bh,
  habitat_dd_k = habitat_k,
  HUC_ID = "1"
)
#> ============================================================
#>        DENSITY DEPENDENCE CONFIGURATION SUMMARY
#> ============================================================
#> 
#> POPULATION TYPE: Resident
#> NUMBER OF STAGES: 4
#> ADULT CAPACITY (k): 500
#> 
#> ------------------------------------------------------------
#> 1. FRY SURVIVAL (s0.1.det) ADJUSTMENT
#> ------------------------------------------------------------
#>    Original S0 value: 0.3
#>    s0.1.det will be: ORIGINAL
#>    Reason: BH/HS stages are defined - s0 optimization skipped
#> 
#> ------------------------------------------------------------
#> 2. COMPENSATION RATIO DENSITY DEPENDENCE
#> ------------------------------------------------------------
#>    Status: ENABLED (applied via D.mx matrix during projection)
#>    Applied when: Each time step, survival rates are multiplied by
#>                  density-dependent factors based on N/K ratio.
#> 
#>    Compensation ratios by stage:
#>      - cr_E: 1 (no DD effect)
#>      - cr_0: 3.5 (DD effect active)
#>      - cr_1: 2.8 (DD effect active)
#>      - cr_2: 2 (DD effect active)
#>      - cr_3: 1.5 (DD effect active)
#>      - cr_4: 1 (no DD effect)
#> 
#>    Stages with active DD: cr_0, cr_1, cr_2, cr_3
#> 
#> ------------------------------------------------------------
#> 3. BEVERTON-HOLT / HOCKEY-STICK DENSITY DEPENDENCE
#> ------------------------------------------------------------
#>    Status: ENABLED (applied in dd.N.bh() AFTER matrix projection)
#> 
#>    Active BH/HS stages:
#>      - bh_stage_0 (Beverton-Holt)
#> 
#>    What dd.N.bh() will do after each projection step:
#>      - Apply Beverton-Holt to egg->fry transition
#> 
#> ------------------------------------------------------------
#> 4. CARRYING CAPACITY (K) VALUES BY STAGE
#> ------------------------------------------------------------
#>    K0: 10,000
#>       Source: habitat_dd_k
#>    K1: 5,000
#>       Source: habitat_dd_k
#>    K2: Derived via stable stage distribution
#>       Source: stable_stage_from_adult_k
#>    K3: Derived via stable stage distribution
#>       Source: stable_stage_from_adult_k
#>    K4: Derived via stable stage distribution
#>       Source: stable_stage_from_adult_k
#> 
#> ------------------------------------------------------------
#> 6. CONFIGURATION NOTES
#> ------------------------------------------------------------
#>    [Habitat Capacity Configuration]
#>    Habitat capacities specified for 'k_stage_1_mean', but there are no corresponding density-dependent bottlenecks for those stages defined in the life cycle input file. Either add stage-specific density-dependent bottlenecks to the life cycle file (e.g., 'bh_stage_1') or remove those columns from the habitat capacities file if they are not needed.
#> 
#> ------------------------------------------------------------
#> SUMMARY
#> ------------------------------------------------------------
#>    Active DD methods: Compensation Ratios (via D.mx), Beverton-Holt (1 stages)
#>    s0.1.det: ORIGINAL
#> 
#> ============================================================

Usage

Arguments

Value

Details

See also

Examples