We create a component composed of a frequency and claims size generator.

1. Create a new Groovy class in the corresponding package (Line 1, 2).
   (Domain classes can be found in src/groovy/org/pillarone/modelling/domain)
   Remark: Composed components have to be defined in a Groovy class as wiring would not work with a Java class in the current implementation.
   
2. The class has to extend org.pillarone.riskanalytics.core.components.ComposedComponent (Line 2)
   
3. The class has two sub components subFrequencyGenerator and subClaimsGenerator. Make sure all sub components name start with sub! If you forget to add sub, they won't be displayed in any of the user interfaces. (Line 3, 4)
4. The class has an output channel outClaims (Line 5) in order to send claims to other components such as claims development or reinsurance contracts.
   
5. Sub components have to be instantiated in the constructor and not in the declaration! (Line 7, 8)
   
6. As this composed component doesn't have any in channels, we have to define which component is executed first in doCalculation() (Line 11).
   Remark: As composed components contain no additional business logic, it is not necessary to implement doCalculation() always as this is the case for components.
   
7. Each composed component has to implement the abstract wire() method. Wiring between the sub components is done similar to the wiring in models. (Line 14-16). As sub components are nested we have to make sure that the information required outside the composed component is replicated. This is done with the so called PortReplicatorCategory (Line 17-19).
   Remark: Using the PortReplicatorCategory the properties on the left and right side have to be either in or out properties, whereas for WireCategory the left side property has to be an in and the right side an out property.
   

 1: package org.pillarone.modelling.domain.generators.claims

    ...

 2: class FrequencyClaimsGenerator extends ComposedComponent {

 3:    FrequencyGenerator subFrequencyGenerator
 4:    SingleClaimsGenerator subClaimsGenerator

 5:    PacketList<Claim> outClaims = new PacketList(Claim)

 6:    FrequencyClaimsGenerator() {
 7:       subFrequencyGenerator = new FrequencyGenerator()
 8:       subClaimsGenerator = new SingleClaimsGenerator()
 9:    }

10:    public void doCalculation() {
11:       subFrequencyGenerator.start()
12:    }

13:    public void wire() {
14:        WiringUtils.use(WireCategory) {
15:            subClaimsGenerator.inClaimCount = subFrequencyGenerator.outFrequency
16:        }
17:        WiringUtils.use(PortReplicatorCategory) {
18:            this.outClaims = subClaimsGenerator.outClaims
19:        }
20:    }
21: }

Calibration of the frequency and claims generator can be done proportional to the number of policies or the premium written. In order to enable this possibility in the composed component too and additional input channel is required.

1. The class has an input channel inUnderwritingInfo (Line 3)
2. If an input channel is wired, the default behaviour can be used by omitting doCalculation() at all or calling super.doCalculation() (Line 13). In this example omitting the method doCalculation() is not recommended as it is not possible to assure that inUnderwritingInfo is connected in all use cases.
   Remark: As it is not mandatory to wire all channels, the method isReceiverWired(inUnderwritingInfo) (Line 12) is implement in Component and returns true if any out channel is connected to inUnderwritingInfo.
   
3. Finally it is necessary to provide the underwriting information to the frequency and claims generator using the closure PortReplicatorCategory to wire them.
   

 1: package org.pillarone.modelling.domain.generators.claims

    ...

 2: class FrequencyClaimsGenerator extends ComposedComponent {

 3:    PacketList<UnderwritingInfo> inUnderwritingInfo = new PacketList(UnderwritingInfo)

 4:    FrequencyGenerator subFrequencyGenerator
 5:    SingleClaimsGenerator subClaimsGenerator

 6:    PacketList<Claim> outClaims = new PacketList(Claim)

 7:    FrequencyClaimsGenerator() {
 8:       subFrequencyGenerator = new FrequencyGenerator()
 9:       subClaimsGenerator = new SingleClaimsGenerator()
10:    }

11:    public void doCalculation() {
12:        if (isReceiverWired(inUnderwritingInfo)) {
13:            super.doCalculation()
14:        } else {
15:            subFrequencyGenerator.start()
16:        }
17:    }

18:    public void wire() {
19:        WiringUtils.use(WireCategory) {
20:            subClaimsGenerator.inClaimCount = subFrequencyGenerator.outFrequency
21:        }
22:        WiringUtils.use(PortReplicatorCategory) {
23:            this.outClaims = subClaimsGenerator.outClaims
24:        }
25:        if (isReceiverWired(inUnderwritingInfo)) {
26:            WiringUtils.use(PortReplicatorCategory) {
27:                subFrequencyGenerator.inUnderwritingInfo = this.inUnderwritingInfo
28:                subClaimsGenerator.inUnderwritingInfo = this.inUnderwritingInfo
29:            }
30:        }
31:    }
32: }

Concept

• A dynamic composed component is similar to a composed component in the sense that it contains components and different in the sense that it contains a flexible number of a component of a specific type. The type of these component has to be defined in the function
  

  abstract Component getDefaultSubComponent()

• Currently all sub components have the same generic name.
• The wire() and doCalculation() methods follow exactly the same concepts as for a composed component.
• The abstract class DynamicComposedComponent handles adding, removing, naming and other checks for all derived class. The components are administered using a list of component called componentList.
• This concepts enables a data driven modelling. The PODRA modell actually contains six void containers (underwriting, claims generators, correlations, event correlations, lines of business and reinsurance program). As the wiring itself is fix such models typically include several filter components for allocation.
  The drawback of such models are the lower performance and the higher risk of parameterization errors.
  

We create a dynamically composed component containing reinsurance contracts.

1. Create a new Groovy class in the corresponding package (Line 1, 2).
   (Domain classes can be found in src/groovy/org/pillarone/modelling/domain)
   Composed components have to be defined in a Groovy class as wiring would not work with a Java class in the current implementation.
   
2. The class has to extend org.pillarone.riskanalytics.core.components.DynamicComposedComponent (Line 2)
   
3. The DynamicReinsuranceProgram has an arbitrary number of ReinsuranceContract. Their default instantiation is defined in getDefaultSubComponent(). The method is called whenever an application user right clicks on the reinsurance program and adds a new contract.
   
4. Finally it is necessary to define the default name (Line 12-14).
   

 1: package org.pillarone.modelling.domain.reinsurance.programs

    ...

 2: class DynamicReinsuranceProgram extends DynamicComposedComponent {

    ...

 3:   public ReinsuranceContract getDefaultSubComponent() {
 4:       ReinsuranceContract newContract = new ReinsuranceContract(
 5:           parmInuringPriority: 0,
 6:           parmContractStrategy: 
 7:               ReinsuranceContractStrategyFactory.getContractStrategy(
 8:                   ReinsuranceContractType.TRIVIAL, [:]))
 9:       newContract.name = getName(newContract)
10:       return newContract
11:   }

12:   protected String getDynamicComponentName() {
13:       "contract"
14:   }

       ...

The wire() method of the DynamicReinsuranceProgram looks rather complicated. The complexity is related with the fact, that the inuring priority parameter of the contracts allows the application user to define any order of the contracts. Furthermore merger components are required to make sure contracts get the correct net information if several contracts have the same inuring priority. The complexity is not related to the concept of dynamic composed components.

Most distributions are taken from the SSJ library. SSJ is a Java library for stochastic simulation, developed in the Département d'Informatique et de Recherche Opérationnelle (DIRO), at the Université de Montréal.

Step by step example

All classes mentioned below can be found in the org.pillarone.modelling.util package.

We distinguish between random variable and probability distributions. Both types are derived from DistributionType. Before starting to implement a new distribution one should have a look at the following classes in the same package as mentioned above: ContinuousRandomDistributionType, DiscreteRandomDistributionType and ContinuousVariateDistributionType, DiscreteVariateDistributionType. Basically these classes act like an enumeration for the available distribution.

In order to add a new distribution it is necessary to add a new public static final variable, it's string representation and the required parameters in one of the four classes mentioned above. Furthermore the new variable has to be added to the "all" variable.

Adding a triangular distribution requires us to add the following line to the class ContinuousRandomDistributionType:

public static final ContinuousRandomDistributionType TRIANGULAR 
            = new ContinuousRandomDistributionType(
            "Triangular", ["a": 0d, "b": 1d, "m": 0.5])

The parameters of this distribution ('a', 'b', 'm') will be displayed on the UI in the same order as they are defined in this Map.

Furthermore we have to add TRIANGULAR to the "all" property in order to display it in the distribution selection lists:

public static final all = [NORMAL, LOGNORMAL, LOGNORMAL_MU_SIGMA, PARETO, 
            CENSOREDPARETO, TRUNCATEDPARETO, UNIFORM, CONSTANT,
            PIECEWISELINEAREMPIRICAL, PIECEWISELINEAR, TRIANGULAR]

In a next step we need to add the distribution to the RandomNumberGeneratorFactory: First we need a private static getter method in order to instantiate the generator:

private static IRandomNumberGenerator getTriangularGenerator(
    double a, double b, double m) {

    TriangularGen generator = new UniformGen(new F2NL607(), 
                                             new TriangularGen(a, b, m))
    return new RandomNumberGenerator(generator: generator)
}

This function is private as we won't allow direct instantiations. Instead the getGenerator method should be used. Therefore we need to add the new case to this function:

static IRandomNumberGenerator getGenerator(DistributionType type, 
    Map parameters) {

    IRandomNumberGenerator generator
    switch (type) {       
        case ContinuousRandomDistributionType.TRIANGULAR:
            generator = getTriangularGenerator(parameters["a"], 
                                               parameters["b"], 
                                               parameters["c"])
            break

The described steps are sufficient in order to add another distribution that is already available in the SSJ library but not yet wrapped into PillarOne. The newly added distribution is now available in attritional or single claims generators (org.pillarone.modelling.domain.generators.claims).

In order to add a more specific distribution an additional step is required: A new class implementing the umontreal.iro.lecuyer.probdist.Distribution interface has to be written. Our  PiecewiseLinearDistribution is an example of this approach.

The implementation is incomplete as we didn't write a test case for our new distribution. It's necessary to complete at least RandomNumberGeneratorFactoryTests.testCreateTypedGenerator() and RandomNumberGeneratorTests.

Caveat: These tests don't test if the generated sample corresponds to the defined distribution.

After completing these steps, the new distribution is part of the list of distributions which appears in the user interface and the parameters are displayed if a user selects the distribution. There is no need to program graphical user interface elements.

Further information

We plan to implement a plugin mechanism to make this process much simpler. The plugin mechanism will avoid the modification of core classes and provide a self registration mechanism. This means that the user may specify a new distribution in one file only. The rest will be done using the plugin infrastructure.