Plot the current parameter set against a candidate, for review

Both trajectories are drawn over the same references, with the fitting window shaded. This is the figure to look at when deciding whether a sweep result is worth promoting: it shows what actually changes, over the part of the curve the objective responds to.

Usage

plot_growth_candidate(
  species,
  current_curve,
  candidate_curve,
  reference,
  binned = NULL,
  smooth = NULL,
  current_label = "current parameters",
  candidate_label = "best candidate",
  x_max = NULL,
  mature_window = c(100L, Inf),
  subtitle = NULL,
  density = FALSE,
  density_bins = 34L,
  density_points_max = 150L
)

Arguments

species

Character. Modelled species code.

current_curve, candidate_curve

Tibbles with age and aboveground_c_mg_ha. candidate_curve may be NULL.

reference

A data frame of reference observations, with columns source ("SORTIE", "TIPSY", "VDYP" or "Ground plots"), age and aboveground_c_mg_ha.

binned

Optional tibble from growth_bin_observations(). An n column, when present, sizes the points.

smooth

Optional tibble from growth_smooth_observations(), drawn as a fitted line and confidence band. Display only; nothing is scored against it.

current_label, candidate_label

Character legend labels.

x_max

Numeric or NULL. Upper age limit. NULL (the default) extends to the last age present in the data, so a longer run is never silently clipped.

mature_window

Numeric length-2. Fitting window to shade.

subtitle

Character. Overrides the default subtitle.

density

Logical. Draw the ground-plot cloud as a WEIGHTED hexagonal density instead of one point per plot, keeping the best-matched plots drawn over it. Weighted via the plot_weight column if present, so the shading reads as evidence rather than as sampling effort; without that column it falls back to counts.

density_bins

Integer. Bins across the x range of the hex grid.

density_points_max

Integer. How many of the best-matched plots stay drawn individually over the density. A COUNT rather than a fraction of the maximum weight, because a fraction does not control the number drawn: the weight distribution differs by species, and at 60% of maximum one species keeps 989 plots where another keeps 65.

Value

A ggplot.

Details

The age-binned plot series is drawn as well, in blue. That series – not the scatter behind it – is what the ground-plot term of the score is computed against, so a candidate that looks wrong against the cloud but right against the binned points is behaving exactly as scored.

Each binned point is sized by the number of plots behind it, because they routinely differ by more than an order of magnitude and an equal-sized point hides that completely. A bin holding a single plot is not a median of anything, and the sharp reversals in the series are usually those bins.

The points are NOT joined by line segments. Connecting them asserts a trajectory across ages where nothing was measured, and most of the movement that line described came from the one-plot bins.

Passing smooth overlays a fit through the whole cloud with a confidence band, for comparison only – see growth_smooth_observations(). It is not scored, and the legend says so. It shares the binned points' colour because it summarizes the same observations; glyph, not hue, is what tells them apart.

See also

Other growth calibration helpers: extract_landscape_cohort_structures(), growth_add_objective(), growth_auto_window(), growth_best_candidates(), growth_bin_observations(), growth_calibration_design(), growth_calibration_partition(), growth_calibration_work_root(), growth_climatic_distance(), growth_climatic_weight(), growth_expand_over_pseudo_species(), growth_factorial_ratio_grid(), growth_fitting_windows(), growth_identifiability(), growth_inflation_factor(), growth_mortality_onset_frac(), growth_plot_palette(), growth_pseudo_species_name(), growth_reference_curves(), growth_reference_inflection(), growth_score_fit(), growth_scoring_for(), growth_smooth_observations(), growth_structure_cell_curves(), growth_structure_cohort_table(), growth_structure_design(), growth_structure_summary(), growth_window_for(), plot_growth_calibration(), plot_growth_factorial_sensitivity(), plot_growth_structures(), read_growth_scoring(), read_landscape_cohort_structures(), scale_linetype_growth_reference(), write_growth_review_bundle()