x-aci 0.0.1a4

This package provides a way to calculate Actuarial Climate Indices based on meteorological data.

Actuarial Climate Indices Package

This package was used to compute the results presented in the paper defining the 'French Actuarial Climate Index' [1]. This work builds upon the initial publication by the American Academy of Actuaries [2].

Currently, the package is organized into different classes, with each class dedicated to a specific component required for index calculation. Further optimization will be done later. The source files implementing these classes are located in the aci/ directory. The aci.py file is used to calculate the Actuarial Climate Indices. Refer to the notebooks for detailed usage instructions.

Installation

pip install x_aci

Usage

Downloading the data

To download the data, we used the Climate Data Store from Copernicus [3]. You can create an account and manually request the data, or follow their documentation to create an API key and automate the data extraction. Note that it may take several days to complete the data download depending on the platform's traffic and the amount of data requested.

The sealevel data was extracted on the Permanent Service for Mean Sea Level [4].

Calculating the index for a country

Once you have downloaded the data, you can start calculating the Actuarial Climate Index for your geographical zone by specifying the paths to your datasets. You also need to provide the three-letter code of your country to extract the tide gauge data for the sea component.

from aci.aci import ActuarialClimateIndex

aci = ActuarialClimateIndex(
    temperature_data_path='data/required_data/temperature_1960-1970.nc',
    precipitation_data_path='data/required_data/precipitation_1960-1970.nc',
    wind_u10_data_path='data/required_data/wind_u10_1960-1970.nc',
    wind_v10_data_path='data/required_data/wind_v10_1960-1970.nc',
    country_abbrev='FRA',
    study_period=('1980-01-01', '2020-12-31'),
    reference_period=('1961-01-01', '1990-12-31')
)
aci_index = aci.calculate_aci()

print(f"Actuarial Climate Index: {aci_index}")

You can also calculate specific components of the ACI by following the documentation PDF inside the docs folder of the repository.

Development

Since the project requires certain dependencies to execute correctly, it is recommended to create a virtual environment using Poetry for testing purposes.

poetry install

Once the environment is created and activated, you can open the notebook files to test the code if you have the required data to calculate an index.

We have also included a Makefile that allows you to remove files generated by the code by running:

poetry run make clean

You can run the current tests implemented by executing:

poetry run make test

References

[1] José Garrido, Xavier Milhaud, Anani Olympio. The definition of a French actuarial climate index; one more step towards a European index. 2023. ⟨hal-04491982⟩

[2] ACI: Actuaries Climate Index Development and Design. American Academy of Actuaries, Canadian Institute of Actuaries, Casualty Actuarial Society, Society of Actuaries. (for Version 1.1, April 2019 see https://actuariesclimateindex.org/wp-content/uploads/2019/05/ACI.DevDes.2.20.pdf)

[3] Hersbach, H., Bell, B., Berrisford, P., Biavati, G., Horányi, A., Muñoz Sabater, J., Nicolas, J., Peubey, C., Radu, R., Rozum, I., Schepers, D., Simmons, A., Soci, C., Dee, D., Thépaut, J-N. (2023): ERA5 hourly data on single levels from 1940 to present. Copernicus Climate Change Service (C3S) Climate Data Store (CDS), DOI: 10.24381/cds.adbb2d47

[4] Permanent Service for Mean Sea Level (PSMSL): Tide Gauge Data (2023). http://www.psmsl.org/data/obtaining/