% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/101_yltsim_inc.R
\name{yltsim_inc}
\alias{yltsim_inc}
\title{Simulates an Adjusted long YLT using Incremental Simulation,
based on an input ELT and long YLT}
\usage{
yltsim_inc(
  elt,
  longylt1,
  rate_adjustments_by_event,
  verbose = FALSE,
  secuncb = FALSE,
  randomday = TRUE
)
}
\arguments{
\item{elt}{A data frame containing the ELT.
Must contain \code{mrate} and \code{mloss} columns.}

\item{longylt1}{A data frame containing a longylt in the format produced by the routine \code{yltsim()}.}

\item{rate_adjustments_by_event}{A matrix of multiplicative adjustments for the Poisson rate.
The first column gives the mean rate adjustment and the second column gives the standard deviation of the rate adjustment. Both columns must be of same length as the columns in \code{elt}.}

\item{verbose}{A logical.}

\item{secuncb}{A logical to indicate whether secondary uncertainty should be simulated
(requires \code{sloss} column). Not implemented yet.}

\item{randomday}{A logical. \code{TRUE} means days are randomized, \code{FALSE} means they are copied.}
}
\value{
A data frame containing the new long YLTs.
}
\description{
You have an ELT. And you have a long YLT that you have previously simulated from the ELT using
Poisson simulation (perhaps using the \code{longyltsim}).
Now you want to simulate an adjusted version of the long YLT, based on multiplicative
adjustments which are specified for each event in the ELT, as a mean and a sd for each event.
}
\details{
The simulated long YLT is copied from the input long YLT, and events are then added and deleted to reflect
the specified rates changes, according to the 'incremental simulation' algorithm.
This algorithm is relevant for the workflow situation in which the base long YLT was simulated from the ELT.
If you have a long YLT that wasn't simulated from an ELT, or you've lost the ELT, use \code{yltsurgery} instead.
Incremental simulation attempts to minimize differences due to random noise between the two YLTs
and gives more accurate estimates of change than just simulating the second YLT using independent simulation.
The rates changes are specified by event.
They can be scalar or log-normal distributed, or other distributed, in order to capture adjustment uncertainty.
Adjustment uncertainty is simulated using the 'stochastic parameter' simulation algorithm.
Changes within years are perfectly correlated.

The input mean and standard deviation rate adjustments are used to define a log-normal distribution for each event.
The log-normal is used to simulate different rate adjustments for each year.
The log-normal adjustments are perfectly correlated between different events.

The assumption is that YLT1 was sampled from the ELT, using the rates in the ELT.
The rate adjustments are specified for all the events in the ELT
(some of which may not even occur in YLT1).
The eltrow in the longylt in YLT1 must correspond to the events in the ELT and in the specified rate adjustments
(which it will if the longylt was created by \code{longyltsim}.
The algorithm consists of two parts.
In the first part, events may or may not be copied from YLT1 to YLT2, depending on a coin flip,
based on a probability derived from the rate adjustment.
If there is no adjustment, an event will be copied. If there is a large reduction in the rate,
it may well not be copied.
The longylt part of YLT1 provides the eltrow for each event, which is used to determine the rate adjustment.
In the second part, events with increasing rates are selected randomly from the ELT (weighted by the increase),
and added to the YLT.

The whole issue of event ids is complicated. Here's what I do:
\itemize{
\item \code{evid: } 	An event id. This will have
whatever numbers it had in the ELT. They don't have to start from one.
This might end up
repeated in the YLT, if the simulations end up repeating that event.
\item \code{eltrow: } 	I number the events in the ELT from 1. This is that number.
This might end up
repeated in the YLT, if the simulations end up repeating that event.
\item \code{oldyltrow: } 	For new events, there is no \code{oldyltrow}, because new events are selected
from the ELT, not the old YLT, and so the value is not uniquely defined.
\item \code{yltrow: } 	The row in the new YLT. Might well not be the same as the
row in the old YLT, because of new events being added.
This doesn't repeat in the new YLT.
}
}
\examples{
#
# create an elt with 3 rows
#
set.seed(1)
evid=seq(1000,1002,1)
mrate=seq(0.1,0.3,0.1)
mloss=seq(100,300,100)
elt=data.frame(evid,mrate,mloss)
nevents=length(mrate)
message("*************************elt*************************")
print(elt)
#
# simulate longylt1 with 15 years
#
nyears=15
longylt1=yltsim(nyears,elt)
message("*************************ylt1*************************")
print(longylt1)
#
# define adjustments
#
rate_adjustments_by_event=matrix(0,nevents,2)
rate_adjustments_by_event[,1]=2 #double the rates
rate_adjustments_by_event[,2]=0
#
# simulate longylt2 with those adjustments
#
longylt2=yltsim_inc(elt,longylt1,rate_adjustments_by_event)
message("*************************ylt2*************************")
print(longylt2)

}
\references{
For the stochastic parameter simulation algorithm see: https://doi.org/10.1007/s00477-023-02409-0

and: https://en.wikipedia.org/wiki/Year_loss_table#Incremental_Simulation

For the incremental simulation algorithm see: https://doi.org/10.1007/s00477-022-02198-y

and: https://en.wikipedia.org/wiki/Year_loss_table#Stochastic_Parameter_YLTs
}
\author{
Stephen Jewson \email{stephen.jewson@gmail.com}
}
