simulate_function: Simulate insurance claims with reinsurance structures
In NetSimR: Actuarial Functions for Non-Life Insurance Modelling

simulate_function

R Documentation

Simulate insurance claims with reinsurance structures

Description

A function to simulate frequency - severity of insurance claims using chunked vectorisation. The function applies severity cap, reinsurance structure for each and every loss claim, reinsurance structure for aggregate claims, and allows for piecewise pareto slices

Usage

simulate_function(
  numOfSimulations,
  freq_params,
  sev_params,
  seedSetBinary = FALSE,
  seedValue = NULL,
  freqDistr,
  sevDistr,
  paretoSlice = FALSE,
  pareto_slice_times = NULL,
  slice_pareto_alphas = NULL,
  slice_pareto_x_ms = NULL,
  sevCapBinary = FALSE,
  sev_cap_amount = NULL,
  reinsuranceStructureEEL = "No Reinsurance Structure",
  reinsurance_structure_eel_dedctible_amount = NULL,
  reinsurance_structure_eel_limit_amount = NULL,
  reinsuranceStructureAL = "No Reinsurance Structure",
  reinsurance_structure_al_dedctible_amount = NULL,
  reinsurance_structure_al_limit_amount = NULL,
  reinsuranceStructureLimitedReinstatements = FALSE,
  reinsuranceStructureReinstatementLimit = NULL,
  multiprocessing = FALSE,
  sevTruncateAtZero = FALSE,
  chunk_size = NULL,
  gross = TRUE,
  shortcuts = TRUE,
  progress = NULL
)

Arguments

`numOfSimulations`	The number of simulations to run.
`freq_params`	A vector of the frequency distribution parameters.
`sev_params`	A vector of the severity distribution parameters.
`seedSetBinary`	True if there is a fixed seed, otherwise false.
`seedValue`	The seed value, a whole number between `-.Machine$integer.max` and `.Machine$integer.max`.
`freqDistr`	The frequency distribution. Options are as per the freq_dist_options.
`sevDistr`	The severity distribution. Options are as per the sev_dist_options.
`paretoSlice`	True if there is Pareto slicing.
`pareto_slice_times`	The number of Pareto slices.
`slice_pareto_alphas`	A vector of Pareto slices' alpha parameters.
`slice_pareto_x_ms`	A vector of Pareto slices' x_m parameters.
`sevCapBinary`	True if there is a severity cap.
`sev_cap_amount`	The severity cap amount.
`reinsuranceStructureEEL`	The chosen reinsurance structure for each and every loss claim.
`reinsurance_structure_eel_dedctible_amount`	The deductible for each and every loss reinsurance structure.
`reinsurance_structure_eel_limit_amount`	The limit for each and every loss reinsurance structure.
`reinsuranceStructureAL`	The chosen reinsurance structure for aggregate claims.
`reinsurance_structure_al_dedctible_amount`	The deductible for aggregate reinsurance structure.
`reinsurance_structure_al_limit_amount`	The limit for aggregate reinsurance structure.
`reinsuranceStructureLimitedReinstatements`	True if there is a limit in reinstatements, otherwise false.
`reinsuranceStructureReinstatementLimit`	The reinstatement limit.
`multiprocessing`	True to run the chunks in parallel with the future package, otherwise false. A future plan with more than one worker that the caller has already set is reused and left running. Otherwise the call starts a multisession plan with one worker per available core (`parallelly::availableCores()`), shuts those workers down when it finishes and restores the caller's plan, so every such call pays the start-up cost again. To choose the number of workers and reuse them across calls, set a plan first, e.g. `future::plan(future::multisession, workers = 4)`.
`sevTruncateAtZero`	True to draw Normal severities from the Normal distribution truncated at zero, so that no claim is negative. Ignored for other severity distributions. Defaults to FALSE.
`chunk_size`	The number of simulations processed per vectorised batch. By default (NULL) it is chosen from the expected number of claims per simulation, so that a batch holds about a million claims (between 100 and 10,000 simulations).
`gross`	True (the default) to return the gross total claims before reinsurance. Set it to FALSE when only the totals after the structures are needed: with an each-and-every-loss layer this allows drawing only the claims that reach the layer, which is much faster.
`shortcuts`	True (the default) to use exact shortcuts where the settings allow: when no layer, cap, Pareto slice or truncation acts on individual claims, each simulation's total is drawn in one step for the Normal, Gamma, Exponential and fixed severities; with `gross = FALSE` and a layer, only the claims above the deductible are drawn. The results follow the same distribution as without shortcuts. Set it to FALSE to simulate every claim.
`progress`	An optional function called after each chunk of a sequential run with the fraction done and a short description, e.g. to update a progress bar.

Details

Random numbers: each chunk of simulations uses its own L'Ecuyer-CMRG random stream, derived from one seed, so a run gives the same results whether or not it runs in parallel. With seedSetBinary = TRUE the run is reproducible from seedValue and the caller's random number stream is left unchanged; otherwise the seed is drawn from the caller's stream, so set.seed() before the call also makes it reproducible. The streams always use Inversion for normal draws and Rejection sampling, so a seed gives the same results whatever the caller's RNGkind(), which is restored afterwards. Results depend on the chunk size, which by default adapts to the expected number of claims per simulation.

Value

A data frame with one row per simulation: the claim count, the total claims after the reinsurance structures, the gross total claims before them (unless gross = FALSE), and the number of reinstatements used (when reinstatements are limited). Stops with an error that names any required setting that is missing or invalid.

Examples

# 1,000 simulated years of Poisson claim counts with Normal claim sizes, no reinsurance
results <- simulate_function(
  numOfSimulations = 1000, freq_params = 3, sev_params = c(1000, 200),
  seedSetBinary = TRUE, seedValue = 1, freqDistr = "Poisson", sevDistr = "Normal"
)
summary(results$total_claims)

# the same claims ceded to a layer of 1,500 excess of 800 on each claim
layer <- simulate_function(
  numOfSimulations = 1000, freq_params = 3, sev_params = c(1000, 200),
  seedSetBinary = TRUE, seedValue = 1, freqDistr = "Poisson", sevDistr = "Normal",
  reinsuranceStructureEEL = "Limited Layer",
  reinsurance_structure_eel_dedctible_amount = 800,
  reinsurance_structure_eel_limit_amount = 1500
)
mean(layer$total_claims)

NetSimR documentation built on Sept. 14, 2026, 1:07 a.m.