================================== Samplicity Quick Start Guide ================================== -------------- Introduction -------------- As mentioned previously *samplicity* is a python library to calculate the SAM SCR for a non-life insurer. Importantly the package allows for a multiple SCR calculations to be performed simultaneously. This allows for the easy calcualtion of diversification benefits across various business lines, divisions, insurance classes, etc. The package has succesfully performed more than 60 000 SCR calculations in test environments - in matter of minutes. This efficiency is obtained through the use of Einstein summation in numpy. This prevents slow looping in Python and leverages off fast parallel matrix multiplication in numpy. This guide will provide users with a quick guide on how to isntall and run samplicity. -------------- Installation -------------- To try make the installation as easy as possible we ahve allowed for a various installation methods. Ideally the package should be installed in a virtual environment. The 'two' methods of installing the package are: **Download** This is the simplest method to install the package and is recommended for 'beginner' users. Download the package, unzip the files, and run the file 'create_virtual.bat'. This will create the virtual environment in the folder 'c:\venv\samplicity' and then attempt to install to samplicity package. It is possible that the installation could fail. This is likely because users need to authenticate their bitbucket access. **PIP** The requirements for the virtual environment can be found in the requirements.txt file. However, one can use a 'blank' virtual environment and the package will install all of the necessary dependencies - these are detailed in the pyproject.toml file. To install the package using PIP one must use the code. .. code-block:: console pip install git+https://https://github.com/clive-africa/samplicity.git -------------- Data Inputs -------------- Data can be provided in either a SQL databased (preferred) or in an Excel worksheet. The SQL database is preferred as an input tool as: * We can ensure proper referential integrity of all inputs. * A full version controlled history of all changes to the underlyign data can be kept. * SQL is more suited to the volume fo output that can be generated by the package. * SQL allows for multipe calcaultiosn to be stored in a single location. An example fo how inputs should be structed can be found within the the folder '.inputs.' There are a couple files of interest: * **sam_input.xlsm:** Provides an example of how an Excel workbook should be structured. * **create_db.py:** Contaisn a draft database structure that can be used for the project. * **input_database.accdb:** Is still in developmetn but provides an example of how an MS Access databse can be used as a frontend for the tool. ------------------ Running the Tool ------------------ The code can be run, very simply, from Python. One can further automate the process by calling Python from the command line. To see examples of how the code should be run, you can refer to the files *sample_excel_use.py* and *sample_odbc_use.py* in the folder *tests* within *Samplicity*. The tools allows for (user selected) results to be export to a databse - or Excel. A user cna further save the entire scr class - with all the data - as a pickle file. All the input data, calculations and outpu can then be retrieved from the pickle file. A (very brief) exmaple of how the package can be run is included below: .. code-block:: python # Import the package import samplicity as sam # The files where our data is stored import_file="c:/git_hub/sam_scr/.input/sam_input.xlsm" risk_free_rates="c:/git_hub/sam_scr/.input/12 SAM - Risk Free Rates (30 December 2022).xlsx" symmetric_adjustment="c:/git_hub/sam_scr/.input/12 SAM - Equity Symmetric Adjustment (30 December 2022).xlsx" #Create an instance of the SAM SCR class sam_scr=sam.scr.SCR() # Import our data sam_scr.f_import_data( risk_free_rates=risk_free_rates, symmetric_adjustment=symmetric_adjustment, data_file=import_file, ) # Peform the actual SCR calculation sam_scr.f_calculate() # Calcualte Shapely diversification values sam_scr.f_shapely() # Save all the results to a pickle file sam_scr.f_save_pickle() # Export our results to the sam Excel file sam_scr.f_export_results(import_file) ## Data Extraction *Samplicity* stoes a lot of very detailed data - and the supporting calculations to the SCR calculation. In the default example, very little of this information is extracted. In the Excel example, the information that is extracted is controlled by the *result_exports* range. To get a better idea of the information that can be extracted a user can run the code below: .. code-block:: python df = sam_scr.f_info() The code is not perfect but it will give a very good idea of the data that can be extracted from each child class - and the strcuture fo the data. ------------------ Data Extraction ------------------ It is recognised that some users may be nervous and apprehensive to make use of *Samplicity*. It can be seen a blackbox. Although the code for *Samplicity* can be downloaded and interegated, some of the code is complex and requires knowledge of Einstein Notation - this is done for the significant performance improvements. To encourage users to make use of *Samplicity* and promote their learning and comfort of the tool, a series of *proofs* are being developed. These proofs exactly replciate the *Samplicity* calculations in Excel. You can view the proofs in the supporting folder *.proofs*.