Metadata-Version: 2.1
Name: x_aci
Version: 0.0.1a3
Summary: This package provides a way to calculate Actuaries Climate Index based on meteorological data.
License: MIT
Author: XavierMilhaud
Requires-Python: >=3.12,<4.0
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Dist: Bottleneck (>=1.4.2,<2.0.0)
Requires-Dist: cdsapi (>=0.7.4,<0.8.0)
Requires-Dist: dask (>=2024.10.0,<2025.0.0)
Requires-Dist: netCDF4 (>=1.7.2,<2.0.0)
Requires-Dist: pandas (>=2.2.3,<3.0.0)
Requires-Dist: psutil (>=6.1.0,<7.0.0)
Requires-Dist: requests (>=2.32.3,<3.0.0)
Requires-Dist: xarray (==2024.02.0)
Description-Content-Type: text/markdown

# Actuaries Climate Index Package

   Currently, the package is organized into different classes, with each class dedicated to a specific component required for the 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 Index. 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). To download data, you can create an account and create request manually to extract the data, or you can follow the documentation they provide to create an API key and use it to extract automatically data. Note that it could take several days to complete the data download depending on the traffic on their platform and the amount of data asked.


### Calculate the index for a country

When you finished to download the data, you can start the calculous of the Actuaries Climated Index for your geographical zone specifying the paths to your datasets. You also need to provide the 3 letters code of your country in order to extract the tide gauge data for the sea component. 

```python
from aci.aci import ActuariesClimateIndex

aci = ActuariesClimateIndex(
    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"Actuaries Climate Index: {aci_index}")
```

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

## Development

Since the project requires certain dependencies to exectue correctly, it is recommended to create a virtual environment using poetry for testing purpose

```bash
poetry install
```
Once the environment is created and activated, you can open the notebook files to test the code if you have data required 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
```
It is possible to run the current tests implemented by processing : 

```bash
poetry run make test
```

## References

<a id="1">[1]</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="2">[2]</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="3">[3]</a>
Permanent Service for Mean Sea Level (PSMSL): Tide Gauge Data (2023). http://www.psmsl.org/data/obtaining/

