Type: Package
Title: Simulation of Life Reinsurance with Profit Commission
Version: 0.1.0
Description: Simulates and evaluates stochastic scenarios of death and lapse events in life reinsurance contracts with profit commissions. The methodology builds on materials published by the Institute of Actuaries of Japan https://www.actuaries.jp/examin/textbook/pdf/modeling.pdf. A paper describing the detailed algorithms will be published by the author within a few months after the initial release of this package.
License: MIT + file LICENSE
Encoding: UTF-8
RoxygenNote: 7.3.2
Depends: R (≥ 4.1.0)
Imports: dplyr, magrittr, arrow, parallel, doSNOW, foreach, progress, data.table, stringr, rstudioapi
Suggests: testthat
LazyData: true
URL: https://github.com/taku1094/volrisk
BugReports: https://github.com/taku1094/volrisk/issues
NeedsCompilation: no
Packaged: 2025-06-12 00:23:45 UTC; calci
Author: Yoshida Takuji [aut, cre]
Maintainer: Yoshida Takuji <t.yoshida.science.kyoto@gmail.com>
Repository: CRAN
Date/Publication: 2025-06-14 08:30:02 UTC

Pipe operator

Description

See magrittr::%>% for details.

Usage

lhs %>% rhs

Arguments

lhs

A value or the magrittr placeholder.

rhs

A function call using the magrittr semantics.

Value

The result of calling rhs(lhs).

Calculate Profit Commission for Reinsurance

Description

Calculates profit commission payouts for a single set of reinsurance cash flows.

This function supports standard profit commission rules using input cash flows and applies key parameters such as the profit commission rate, administrative expense rate, and loss carryforward logic.

Usage

calc_pc(PREM, CLAIM, pc_rate, me, loss_carry, duration)

Arguments

PREM

Numeric vector of premiums.

CLAIM

Numeric vector of claims.

pc_rate

Profit commission rate (typically between 0 and 1).

me

Administrative expense rate deducted from premium (typically between 0 and 1).

loss_carry

Whether to apply loss carryforward across periods. Must be "Y" (yes) or "N" (no).

duration

Numeric vector of durations. Must match length of PREM and CLAIM and be consecutive integers.

Value

A numeric vector of calculated profit commissions (same length as duration).

Examples

# Simple numeric vectors
PREM <- c(1000, 1000, 1000, 1000, 1000, 1000)
CLAIM <- c(600, 1800, 600, 600, 600, 600)
duration <- 1:6
calc_pc(PREM, CLAIM, pc_rate = 0.9, me = 0.05, loss_carry = "Y", duration = duration)

# Using example_simulation dataset
example_simulation_with_PC <- example_simulation %>%
  dplyr::group_by(split, sim_n) %>%
  dplyr::mutate(
  PC = calc_pc(PREM,
               CLAIM,
               pc_rate = 0.9,
               me = 0.05,
               loss_carry = "N",
               duration = DURATION)) %>%
  dplyr::ungroup()

Example Portfolio

Description

A synthetic insurance portfolio provided for testing and demonstration of package functionality. This dataset illustrates the structure and variables commonly used in life insurance modeling.

Usage

example_portfolio

Format

A data frame with 50 rows and 12 variables:

POL_ID

Policy ID number

CLIENT_ID

Client ID number

ISSUE_AGE

Age of the insured at policy issue

GENDER

Gender of the insured

DURATION

Policy year of coverage

ATT_AGE

Attained age in each duration

qx

Mortality rate based on Japanese standard valuation table

FACE

Face amount of the policy

RATE

Premium rate applied

MORTALITY

Actual assumed mortality rate

LAPSE

Policy lapse rate

NAR

Net amount at risk

Example Simulation Results

Description

A synthetic dataset representing simulated insurance cash flows over time. This dataset is provided for demonstration and validation of key package functions, including risk evaluation (risk()) and profit commission calculation (calc_pc()). It includes premium and claim flows per simulation trial and policy duration, enabling users to test volatility risk metrics and profit commission calculations.

Usage

data(example_simulation)

Format

A tibble with 10 rows and 5 variables:

split

Repetition number of the simulation

sim_n

Simulation trial number

DURATION

Duration year of the policy

PREM

Premium

CLAIM

Claim

Create Insurance Portfolio for Simulation

Description

This function standardizes and validates raw insurance portfolio data to prepare it for simulation. It ensures all necessary fields are correctly mapped and conform to required formats. If no column mapping is provided, the user will be prompted interactively.

Usage

make_portfolio(data, cols = NULL)

Arguments

data

A data.frame containing raw insurance portfolio data.

cols

A named list with column mappings. The list should include: unique_id, client_id, duration, mortality, lapse, nar, rate.

Value

A cleaned data.frame with standardized column names: unique_id, client_id, duration, mortality, lapse, nar, rate.

Examples

make_portfolio(example_portfolio, cols = list(
  unique_id = "POL_ID",
  client_id = "CLIENT_ID",
  duration = "DURATION",
  mortality = "MORTALITY",
  lapse = "LAPSE",
  nar = "NAR",
  rate = "RATE"
))

Compute Risk Measures

Description

Computes Value-at-Risk (VaR) and Tail Value-at-Risk (TVaR) based on simulated insurance cash flows. The function supports discounting for multi-year horizons and can evaluate loss ratio (LR) or balance (BAL).

Usage

risk(
  cf,
  time_horizon = c(1),
  level = c(0.005, 0.01, 0.1, 0.2, 0.5, 0.8, 0.9, 0.99, 0.995),
  discount = 0,
  output = "LR"
)

Arguments

cf

A data.frame containing simulated cash flow results. Must include columns: split, sim_n, PREM, CLAIM, DURATION.

time_horizon

A numeric vector specifying time horizons (e.g., c(1, 5, 10)).

level

A numeric vector of confidence levels for risk quantification (e.g., c(0.01, 0.1, 0.99)).

discount

Annual discount rate to convert future cash flows to present value. Default is 0 (no discount).

output

The metric to be analyzed: "LR" for loss ratio or "BAL" for balance. Default is "LR".

Value

A data.frame summarizing VaR and TVaR values across the specified horizons and confidence levels.

Examples

# Using example_simulation dataset (assumes data is loaded)
result <- risk(example_simulation,
               time_horizon = c(1, 10),
               level = c(0.01, 0.99),
               discount = 0.02,
               output = "BAL")
print(result)

Run Simulation of Death and Lapse Scenarios

Description

This function simulates death and lapse events over the insurance period using the portfolio created by make_portfolio(). The total number of simulations is n_sim * split, and results are saved in CSV or Parquet format in the specified path.

Usage

simulation(
  df,
  n_sim = NULL,
  split = NULL,
  seed = NULL,
  sync_seed = TRUE,
  output_format = "csv",
  output_path = NULL
)

Arguments

df

A data.frame returned by make_portfolio()

n_sim

Number of simulations per split

split

Number of splits (simulation repetitions)

seed

Random seed (optional)

sync_seed

Logical flag (default = TRUE). If TRUE, ensures that all policies belonging to the same insured person use synchronized random seeds for death simulation, thereby ensuring consistent timing of death events across policies. This is critical for accurately capturing volatility risk arising from common mortality shocks.

output_format

Output file format: "csv" or "parquet"

output_path

Path to save the simulation results and logs

Value

No return value. Files are saved to output_path.

Examples

# Prepare portfolio
port <- make_portfolio(example_portfolio, cols = list(
  unique_id = "POL_ID",
  client_id = "CLIENT_ID",
  duration = "DURATION",
  mortality = "MORTALITY",
  lapse = "LAPSE",
  nar = "NAR",
  rate = "RATE"
))

# Run simulation (output_path = tempdir() for demonstration)
simulation(port,
           n_sim = 10,
           split = 100,
           seed = 12345,
           output_format = "csv",
           output_path = tempdir()
           )