climateqa/engine/talk_to_data/ipcc/plot_informations.py

from climateqa.engine.talk_to_data.ipcc.config import IPCC_INDICATOR_TO_UNIT

def indicator_evolution_informations(
        indicator: str,
        params: dict[str,str],
) -> str:
    if "location" not in params:
        raise ValueError('"location" must be provided in params')
    location = params["location"]

    unit = IPCC_INDICATOR_TO_UNIT[indicator]
    return f"""
This plot shows how the climate indicator **{indicator}** evolves over time in **{location}**.

It combines both historical (from 1950 to 2015) observations and future (from 2016 to 2100) projections for the different SSP climate scenarios (SSP126, SSP245, SSP370 and SSP585).

The x-axis represents the years (from 1950 to 2100), and the y-axis shows the value of the {indicator} ({unit}).

Each line corresponds to a different scenario, allowing you to compare how {indicator} might change under various future conditions.

**Data source:**  
- The data comes from the CMIP6 IPCC ATLAS data. The data were initially extracted from [this referenced website](https://digital.csic.es/handle/10261/332744) and then preprocessed to a tabular format and uploaded as parquet in this [Hugging Face dataset](https://huggingface.co/datasets/Ekimetrics/ipcc-atlas).
- The underlying data is retrieved by aggregating yearly values of {indicator} for the selected location, across all available scenarios. This means the system collects, for each year, the value of {indicator} in {location}, both for the historical period and for each scenario, to build the time series.
- The coordinates used for {location} correspond to the closest available point in the IPCC database, which uses a regular grid with a spatial resolution of 1 degree.
"""

def choropleth_map_informations(
        indicator: str,
        params: dict[str, str],
) -> str:
    unit = IPCC_INDICATOR_TO_UNIT[indicator]
    if "location" not in params:
        raise ValueError('"location" must be provided in params')
    location = params["location"]
    country_name = params["country_name"]
    year = params["year"]
    if year is None:
        year = 2050

    return f"""
This plot displays a choropleth map showing the spatial distribution of **{indicator}** across all regions of **{location}** country ({country_name}) for the year **{year}** and the chosen scenario.

Each grid point is colored according to the value of the indicator ({unit}), allowing you to visually compare how {indicator} varies geographically within the country for the selected year and scenario.

**Data source:**  
- The data come from the CMIP6 IPCC ATLAS data. The data were initially extracted from [this referenced website](https://digital.csic.es/handle/10261/332744) and then preprocessed to a tabular format and uploaded as parquet in this [Hugging Face dataset](https://huggingface.co/datasets/Ekimetrics/ipcc-atlas).
- For each grid point of {location} country ({country_name}), the value of {indicator} in {year} and for the selected scenario is extracted and mapped to its geographic coordinates.
- The grid points correspond to 1-degree squares centered on the grid points of the IPCC dataset. Each grid point has been mapped to a country using [**reverse_geocoder**](https://github.com/thampiman/reverse-geocoder). 
- The coordinates used for each region are those of the closest available grid point in the IPCC database, which uses a regular grid with a spatial resolution of 1 degree.
"""

def indicator_specific_month_evolution_informations(
        indicator: str,
        params: dict[str, str]
) -> str:
    if "location" not in params:
        raise ValueError('"location" must be provided in params')
    location = params["location"]
    if "month_name" not in params:
        raise ValueError('"month_name" must be provided in params')
    month = params["month_name"]
    unit = IPCC_INDICATOR_TO_UNIT[indicator]
    return f"""
This plot shows how the climate indicator **{indicator}** evolves over time in **{location}** for the month of **{month}**.
It combines both historical (from 1950 to 2015) observations and future (from 2016 to 2100) projections for the different SSP climate scenarios (SSP126, SSP245, SSP370 and SSP585).
The x-axis represents the years (from 1950 to 2100), and the y-axis shows the value of the {indicator} ({unit}) for the selected month.
Each line corresponds to a different scenario, allowing you to compare how {indicator} for month {month} might change under various future conditions.

**Data source:**  
- The data comes from the IPCC climate datasets (Parquet files) for the relevant indicator, location, and month.
- For each year and scenario, the value of {indicator} for month {month} is extracted for the selected location.
- The coordinates used for {location} correspond to the closest available point in the IPCC database, which uses a regular grid with a spatial resolution of 1 degree.
"""