Sensitivity and stochastic platforms

Manual contents | Tutorial | Model logic | Dashboard configuration | Where NuML runs

Alongside the ordinary Run platform, DynSS apps provide two analytical platforms that re-run the model many times: Sensitivity sweeps one parameter across a range and overlays the results; Stochastic repeats a random model and aggregates outcomes into histograms and statistics. Both are configured from NuML with #= statements — the part of the language the wiki reference does not document. Sources: directive.js, initSens.js, initStoc.js, numlTransformer.js.

Both platforms are optional: a program that omits SensPlatform / StocPlatform simply leaves those pages unconfigured.

1. What the platforms do

The platforms replay the same NuML program; batch in the integration configuration is strongly recommended so each replicate runs at full speed.

2. Sensitivity analysis: SensPlatform

SensPlatform #= [
    title("Sensitivity to Harvest Rate"),
    sensTarget(N),                    // the quantity to observe
    sensParam("Harvest Rate (h)"),    // the slider to sweep, by legend
    sensRuns(11),                     // number of values to test
    sensLo(0.0),                      // low end of the sweep
    sensHi(0.3)                       // high end of the sweep
]

The platform's main graph overlays the target's trajectory for every swept value; its statistics graph plots the across-run mean and mean ± standard deviation at each time. Older presets spell the last three directives statRuns, statLo, statHi (and statParam/statDat for the parameter/target); the engine accepts both vocabularies — write the sens* forms in new code.

3. Repeated stochastic runs: StocPlatform

For models with randomness (binomial/poisson draws in next equations under Euler — see model logic):

StocPlatform #= [
    stocHist("TotNewInf"),                       // histogram datum
    binSize(10),
    stocHistTitle("Histogram of Total Infections"),
    stocRuns(500),                               // number of replicates
    stocStats(TimeGraph00, "Infected Untreated"), // optional statistics series
    stocStatsTitle("Infectious Count Statistics")
]

Multiple histograms. Flat stocHist… directives describe the first histogram; each nested bracket group adds another, with its own datum, bins, and slot:

StocPlatform #= [stocRuns(500),
    [stocHist("Harvested"), stocHistTitle("Harvested"), binSize(5)],
    [stocHist(quitTime), stocHistTitle("Extinction Time"), site("01")]
]

The directive names FreqGraph, FreqGraphTitle, FreqGraphRange and HistGraph, HistGraphTitle, HistGraphRange are accepted aliases of the stocHist family found in some presets.

4. Recording variables without a graph

Both platforms can observe a quantity that no visible display shows. The synthetic display target TimeSeries("name") records a series without occupying a dashboard quadrant:

update(TotNewInf) @= TimeSeries("TotNewInf")
…
StocPlatform #= [stocHist("TotNewInf"), …]

When sensTarget names an unquoted model variable, or stocHist names a quoted variable that no update routes and no legend matches, the code normalizer inserts this statement for you (numlTransformer.js); writing it explicitly keeps the program self-documenting.

5. quitWhen and quitTime

quitWhen @= condition ends a run early (model logic); quitTime is the time at which that happened. Together they turn the stochastic platform into a first-passage-time analyzer — the Population Viability preset records an extinction-time distribution:

next(N) @= Math.max(0, Total_Pre_Harvest - Harvested)
…
quitWhen @= (N <= 0)

StocPlatform #= [
    stocHist(quitTime),
    stocHistTitle("Extinction Time Histogram"),
    stocRuns(1000)
]

Runs that never satisfy quitWhen end at maxTime, so the histogram's last bin collects the non-extinct replicates. quitTime is only meaningful to stocHist; it is not a model value and cannot be a sensitivity target.

6. Worked configurations

Complete, runnable programs combining these pieces ship as presets:

Each preset also carries its generated documentation, visible in the app's RAM documentation window when the preset is selected.