environmentaltools.graphics.era5_time_series_plot

environmentaltools.graphics.era5_time_series_plot(data, variable_name: str = 'swh', variable_label: str = 'Significant Wave Height', variable_units: str = 'm', start_year: int = None, end_year: int = None, output_path: str = None, file_name: str = None) → str[source]

Create a comprehensive time series plot of ERA5 data.

Creates a multi-panel visualization including: - Complete time series - Monthly statistics (mean, IQR, max) - Distribution histogram with mean and 95th percentile

Parameters:

  • data (pd.DataFrame) – Data with datetime index and variable column.

  • variable_name (str, optional) – Column name in dataframe. Defaults to ‘swh’.

  • variable_label (str, optional) – Label for plots. Defaults to ‘Significant Wave Height’.

  • variable_units (str, optional) – Units for axis labels. Defaults to ‘m’.

  • start_year (int, optional) – Start year for plot title. If None, extracted from data.

  • end_year (int, optional) – End year for plot title. If None, extracted from data.

  • output_path (str, optional) – Directory to save plot. If None, uses current directory.

  • file_name (str, optional) – Custom filename. If None, auto-generated.

Returns:

Path to the saved plot file.

Return type:

str

Raises:

ValueError – If plot creation fails.

Example

>>> import pandas as pd
>>> from environmentaltools.graphics.spatiotemporal import era5_time_series_plot
>>>
>>> # For wave height
>>> plot_path = era5_time_series_plot(
...     data,
...     variable_name='swh',
...     variable_label='Significant Wave Height',
...     variable_units='m',
...     output_path='./plots'
... )
>>>
>>> # For wind speed
>>> plot_path = era5_time_series_plot(
...     data,
...     variable_name='u10',
...     variable_label='10m U Wind',
...     variable_units='m/s'
... )