3.1. Underwriter Module

3.1.1. Underwriter Class

class aggregate.underwriter.Underwriter(name='Rory', databases=None, update=False, log2=10, debug=False)

The Underwriter class manages the creation of Aggregate and Portfolio objects, and maintains a database of standard Severity (curves) and Aggregate (unit or line level) objects called the knowledge base.

• Handles persistence to and from agg files

• Is interface into program parser

• Handles safe lookup from the knowledge for parser

Objects have a kind and a name. The kind is one of ‘sev’, ‘agg’ or ‘port’. The name is a string. They have a representation as a program. When the program is interpreted it produces a dictionary spec that can be used to create the object. The static method factory can create any object from the (kind, name, spec, program) quartet, though, strictly, program is not needed.

The underwriter knowledge is stored in a dataframe indexed by kind and name with columns spec and program.

__init__(name='Rory', databases=None, update=False, log2=10, debug=False)

Create an underwriter object. The underwriter is the interface to the knowledge base of the aggregate system. It is the interface to the parser and the interpreter, and to the database of curves, portfolios and aggregates.

Parameters

• name – name of underwriter. Defaults to Rory, after Rory Cline, the best underwriter I know and a supporter of an analytic approach to underwriting.

• databases – name or list of database files to read in on creation. if None: nothing loaded; if ‘default’ (installed) or ‘site’ (user, in ~/aggregate/databases) database *.agg files in default or site directory are loaded. If ‘all’ both default and site databases loaded. A string refers to a single database; an interable of strings is also valid. See read_database for search path.

• update – if True, update database files with new objects.

• log2 – log2 of number of buckets in discrete representation. 10 is 1024 buckets.

• debug – if True, print debug messages.

_interpreter_work(iterable, debug=False)

Do all the work for the test, allows input to be marshalled into the tester in different ways. Unlike production interpret_program, runs one line at a time. Each line is preprocessed and then run through a clean parser, and the output analyzed.

Last column, program as input is only changed if the preprocessor changes the program

Returns

DataFrame

build(program, update=None, log2=0, bs=0, recommend_p=0.99999, logger_level=None, **kwargs)

Convenience function to make work easy for the user. Intelligent auto updating. Detects discrete distributions and sets bs = 1.

build method sets loger level to 30 by default.

__call__ is set equal to build.

Parameters

• program –

• update – build’s update

• log2 – 0 is default: Estimate log2 for discrete and self.log2 for all others. Inupt value over-rides and cancels discrete computation (good for large discrete outcomes where bucket happens to be 1.)

• bs –

• logger_level – temporary log(ger) level for this build

• recommend_p – passed to recommend bucket functions. Increase (closer to 1) for thick tailed distributions.

• kwargs – passed to update, e.g., padding. Note force_severity=True is applied automatically

Returns

created object(s)

dir(pattern='')

List all agg databases in site and default directories. If entries is True then read them and return named objects.

Parameters

pattern – glob pattern for filename; .agg is added

factory(answer)

Create object of kind from spec, a dictionary. Creating from uw obviously needs the uw, so this is NOT a staticmethod!

Parameters

answer – an Answer class with members kind, name, spec, and program

Returns

creates answer.object

interpret_program(portfolio_program)

Preprocess and then parse a program one line at a time. Each output is stored in the Underwriter’s knowledge database. No objects are created.

Error handling through parser.

Parameters

portfolio_program –

Returns

interpreter_file(*, filename='', where='')

Run a suite of test programs. For detailed analysis, run_one. filename is a string or Path. If a csv it is read into a dataframe, with the first column used as index. If it is an agg file (e.g. an agg database), it is preprocessed to remove comments and replace nt agg with a space, then split on new lines and converted to a dataframe. Other file formats are rejected.

These methods are called interpreter_… rather than interpret_… because they are for testing and debugging the interpreter, not for actually interpreting anything!

interpreter_line(program, name='one off', debug=True)

Interpret single line of code in debug mode. name is index of output

interpreter_list(program_list)

Interpret elements in a list in debug mode.

static logger_level(level)

Convenience function.

Parameters

level –

Returns

more(regex)

More information about methods and properties matching regex

qlist(regex)

Wrapper for show to just list elements in knowledge that match regex. Returns a dataframe.

qshow(regex, tacit=True)

Wrapper for show to just show (display) elements in knowledge that match regex. No reutrn value if tacit, else returns a dataframe.

read_database(fn)

read database of curves, aggs and portfolios. These can live in the default directory that is part of the instalation or ~/aggregate/

fn can be a string filename, with or without extension. A .agg extension is added if there is no suffix. Search path:

• in the current dir

• in site_dir (user)

• in default_dir (installation)

Parameters

fn – database file name

run_test_suite()

Run interpreter on the test suite

safe_lookup(buildinid)

Lookup buildinid=kind.name in uw to find expected kind and merge safely into self.arg_dict.

Different from getitem because it splits the item into kind and name and double checks you get the expected kind.

Parameters

buildinid – a string in kind.name format

Returns

show(regex, kind='', plot=True, describe=True, logger_level=30, verbose=False, **kwargs)

Create from knowledge by name or match to name. Optionally plot. Returns the created object plus dataframe with more detailed information. Allows exploration of preloaded databases.

Eg regex = "A.*[234] to run examples named A…2, 3 and 4.

See qshow for a wrapper that just returns the matches, with no object creation or plotting.

Examples.

from aggregate.utilities import pprint
# pretty print all prgrams starting A; no object creation
build.show('^A.*', 'agg', False, False).program.apply(pprint);

# build and plot A..234
ans, df = build.show('^A.*')

Parameters

• regex – for filtering name

• kind – the kind of object, port, agg, etc.

• plot – if True, plot (default True)

• describe – if True, print the describe dataframe

• logger_level – work silently!

• verbose – if True, return the dataframe and objects; else no return value

• kwargs – passed to build for calculation instructions

Returns

dictionary of created objects and DataFrame with info about each.

property test_suite_file

Return the test_suite filename, or None if it does not exist

write(portfolio_program, log2=0, bs=0, update=None, **kwargs)

Write a natural language program. Write carries out the following steps.

1. Read in the program and cleans it (e.g. punctuation, parens etc. are removed and ignored, replace ; with new line etc.)

2. Parse line by line to create a dictionary definition of sev, agg or port objects.

3. Replace sev.name, agg.name and port.name references with their objects.

4. If update set, update all created objects.

Sample input:

port MY_PORTFOLIO
    agg Line1 20  loss 3 x 2 sev gamma 5 cv 0.30 mixed gamma 0.4
    agg Line2 10  claims 3 x 2 sevgamma 12 cv 0.30 mixed gamma 1.2
    agg Line 3100  premium at 0.4 3 x 2 sev 4 @ lognormal 3 cv 0.8 fixed 1

The indents are required if each agg item appears on a new line.

See parser for full language spec! See Aggregate class for many examples.

Parameters

• log2 –

• bs –

• portfolio_program –

• update – override class default

• kwargs – passed to object’s update method if update==True

Returns

single created object or dictionary name: object

write_from_file(file_name, log2=0, bs=0, update=False, **kwargs)

Read program from file. Delegates to write.

Parameters

• file_name –

• log2 –

• bs –

• update –

• kwargs –

Returns

3.1.2. Other Underwriter functions