x-aci 0.0.1a4
This package provides a way to calculate Actuarial Climate Indices based on meteorological data.
License: MIT
Requires Python: <4.0,>=3.12

# 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

```bash
pip install x_aci
```

## Usage

### Downloading the data
To download the data, we used the [Climate Data Store from Copernicus](https://cds.climate.copernicus.eu/datasets/reanalysis-era5-single-levels?tab=overview) `[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.

```python
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.

```bash
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:

```bash
poetry run make clean
```
You can run the current tests implemented by executing:

```bash
poetry run make test
```

## References

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

<a id="2">[2]</a>
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)

<a id="3">[3]</a> 
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

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