% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/106_yltsurgery_groups.R
\name{yltsurgery_groups}
\alias{yltsurgery_groups}
\title{Adjusts a long YLT to make a new long YLT using the grouped surgery algorithm}
\usage{
yltsurgery_groups(
  longylt1,
  rate_adjustments_by_event,
  groups,
  columns2copy = NULL,
  secunc = FALSE,
  verbose = FALSE,
  randomday = TRUE
)
}
\arguments{
\item{longylt1}{A data frame containing a YLT}

\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{groups}{Specifies which group each event is in.}

\item{columns2copy}{Specifies a list of columns to be copied from the original YLT, such as \code{cat}.}

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

\item{verbose}{A logical.}

\item{randomday}{Do you want the days to be randomized or copied?}
}
\value{
A data frame containing the new long YLTs.
}
\description{
The simulated YLT is copied from the input YLT, with events added and deleted to reflect
the specified rates changes, according to the 'grouped surgery' algorithm.
This algorithm 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.
Within each group, it chooses the number of events to try and hit the target
as closely as possible.
The rates changes are specified by event.
They can be scalar or log-normal distributed, in order to capture adjustment uncertainty.
Adjustment uncertainty is simulated using the 'stochastic parameter' simulation algorithm.
}
\details{
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 rate adjustments are specified for all the events in the YLT, in order.
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.
YLT1 provides the evid for each event, which is used to determine the rate adjustment.
In the second part, events with increasing rates are selected randomly from YLT1 (weighted by the increase),
and added to YLT2.
}
\examples{
#
# create an elt with 3 rows
#
set.seed(2)
evid=seq(1000,1002,1)
mrate=seq(0.1,0.3,0.1)
mloss=seq(100,300,100)
region=c("A","B","C")
nevents=length(mrate)
elt=data.frame(mrate,mloss,evid,region)
#
# simulate ylt1 with 10 years
#
nyears=10
longylt1=yltsim(nyears,elt,columns2copy=c("region"))
# add an evid flag to the ylt just to test that goes through into ylt2
cat("*************************ylt1*************************\n")
print(head(longylt1))
#
# define adjustments
#
nevents_in_ylt1=length(longylt1$evid)
rate_adjustments_by_event=matrix(0,nevents_in_ylt1,2)
rate_adjustments_by_event[,1]=2 #double the rates
rate_adjustments_by_event[,2]=0
groups=matrix(1,nevents_in_ylt1)
#
# simulate ylt2 with those adjustments (but not referring back to the ELT)
#
ylt2=yltsurgery_groups(longylt1,rate_adjustments_by_event,groups,columns2copy="region")
cat("*************************ylt2*************************\n")
print(head(ylt2))

}
\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}
}
