wolfhece.hydrometry.rain_SPW

Author: HECE - University of Liege, Pierre Archambeau Date: 2024

Copyright (c) 2024 University of Liege. All rights reserved.

This script and its content are protected by copyright law. Unauthorized copying or distribution of this file, via any medium, is strictly prohibited.

Module Contents

class wolfhece.hydrometry.rain_SPW.GlobalStats

mean: float

median: float

std: float

min: float

max: float

q25: float

q75: float

skewness: float

kurtosis: float

num_of_values: int

total_num_of_values: int

coverage: float

class wolfhece.hydrometry.rain_SPW.MissingValues

number: int

percentage: float

class wolfhece.hydrometry.rain_SPW.DateRange

start: pandas.Timestamp

end: pandas.Timestamp

all_ranges: list[tuple[pandas.Timestamp, pandas.Timestamp]]

class wolfhece.hydrometry.rain_SPW.YearlyStats

mean: float

median: float

std: float

min: float

max: float

q25: float

q75: float

skewness: float

kurtosis: float

class wolfhece.hydrometry.rain_SPW.MonthlyStats

mean: float

median: float

std: float

min: float

max: float

q25: float

q75: float

skewness: float

kurtosis: float

class wolfhece.hydrometry.rain_SPW.YearsStats

number_of_years: int

number_of_complete_years: int

class wolfhece.hydrometry.rain_SPW.StatisticsSeries

name: str

time_step: datetime.timedelta = None

global_stats: GlobalStats = None

missing_values: MissingValues = None

date_range: DateRange = None

years: YearsStats = None

monthly_statistics: dict[int, MonthlyStats] = None

yearly_statistics: dict[int, YearlyStats] = None

wolfhece.hydrometry.rain_SPW.STATS_HOURS_IRM

wolfhece.hydrometry.rain_SPW.STATS_MINUTES_IRM

class wolfhece.hydrometry.rain_SPW.SPW_pluviographs(variable: str, timestep: str, credential: str = None, store_dir: str | pathlib.Path = None)

Management of the rain data from the SPW-MI website through its data download interface The data are stored in a local directory in csv or parquet format, and can be loaded in memory as pandas Series for analysis and plotting.

_timestep_dl = None

_data

_store_dir

_format = None

_variable

_timestep

_stations = None

_get_inactive_stations() → pandas.DataFrame

All the stations available in the SPW-MI website for the given variable and timestep, but not present in self._stations, which are the active stations for the given variable and timestep.

This can be useful to identify stations that have data available but are not currently active for the given variable and timestep, for example to check if there are new stations that have been added since the last update of the hydrometry structure, or if there are stations that have been deactivated for some reason.

force_update_hydrometry_structure()

Force the update of the hydrometry structure to get the latest available stations and timeseries from the SPW-MI website.

This can be useful if new stations or timeseries have been added since the last update, or if there have been changes in the station metadata (e.g., name, code, location, etc.) that are not yet reflected in the local structure.

get_all_series(key: Literal['tsid', 'name'] = 'name', to_sort: bool = True) → dict[str, pandas.Series]

Get all the series currently loaded in memory, with station names as keys and pandas Series as values

get_station_names_inside_polygon(polygon: wolfhece.PyVertexvectors.vector | shapely.geometry.Polygon) → list[str]

Get the names of the stations inside a given polygon

Parameters:

polygon – a shapely Polygon or a vector of vertices defining the polygon

get_nearest_station_name(point: wolfhece.PyVertexvectors.wolfvertex | shapely.geometry.Point | list[float, float]) → str

Get the name of the nearest station to a given point

Parameters:

point – a shapely Point, a vector of coordinates, or a list of coordinates [x, y]

resample(rain: pandas.Series, new_timestep: datetime.timedelta, method: str = 'sum')

get_names()

_get_names_lower()

get_codes()

get_tsid_from_name(name: str)

get_tsid_from_code(code: str)

get_tsid(name: str = '', code: str = '')

get_name_from_tsid(ts_id: str)

get_code_from_tsid(ts_id: str)

get_data(fromyear: int, toyear: int, code: str = '', name: str = '', filterna: bool = True, timezone: str = 'GMT+1')

Get the rain data from the SPW-MI website for a given station code or name, and for a given period of years If filterna is True, the NaN values are replaced by 0. Otherwise, they are kept as NaN.

Parameters:

• fromyear – the starting year of the period (inclusive)

• toyear – the ending year of the period (inclusive)

• code – the station code (if name is not provided)

• name – the station name (if code is not provided)

• filterna – whether to replace NaN values by 0 (default: True)

• timezone – the timezone of the data (default: ‘GMT+1’)

Returns:

a pandas Series containing the rain data for the given station and period, indexed by datetime

get_year_data(year: int = 2021, code: str = '', name: str = '', filterna: bool = True, timezone: str = 'GMT+1')

Get the rain data from the SPW-MI website for a given station code or name, and for a given year

Parameters:

• year – the year of the data to retrieve

• code – the station code (if name is not provided)

• name – the station name (if code is not provided)

• filterna – whether to replace NaN values by 0 (default: True)

• timezone – the timezone of the data (default: ‘GMT+1’)

Returns:

a pandas Series containing the rain data for the given station and year, indexed by datetime

get_month_data(month: int = 7, year: int = 2021, code: str = '', name: str = '', timezone: str = 'GMT+1')

Retrieving hourly data from the SPW website (GMT+1)

Parameters:

• month – the month of the year for which to retrieve data (1-12)

• year – the year for which to retrieve data

• code – the station code (if name is not provided)

• name – the station name (if code is not provided)

• timezone – the timezone of the data (default: ‘GMT+1’) – (‘UTC’, ‘GMT+1’, ‘GMT+2’, etc.)

classmethod compute_stats_Q(rain: pandas.Series, listhours: list[int]) → numpy.ndarray

Computes the maximum cumulative rainfall for different durations based on convolution with a vector of number of hours Unity : mm

Parameters:

• rain – the time series of rainfall to analyze

• listhours – the list of durations in hours for which to calculate the stats (e.g., [1,2,3,6,12,24])

Returns:

a numpy array containing the maximum values for each duration

classmethod compute_stats_i(rain: pandas.Series, listhours: list[int]) → numpy.ndarray

Computes the maximum average intensities for different durations based on convolution with a vector of number of hours Unity : mm/h :param rain: the time series of rainfall to analyze :param listhours: the list of durations in hours for which to calculate the stats (e.g., [1,2,3,6,12,24]) :return: a numpy array containing the maximum values for each duration

classmethod plot(data: pandas.Series, toshow=False, xbounds=None, ticks='M', label: str = None, figax=None)

classmethod plot_periodic(data: pandas.Series, origin: datetime.datetime, length_in_months: int = 12, toshow: bool = False, figax: tuple[matplotlib.pyplot.Figure, matplotlib.pyplot.Axes] = None) → tuple[matplotlib.pyplot.Figure, matplotlib.pyplot.Axes]

Comparison of several years over the same horizon of a total year starting from a given date, for example to compare the summer periods of several years starting from the 1st of July. The x-axis is in days from the origin date, and the y-axis is the rainfall in mm/h.

Parameters:

• data – the time series of rainfall to plot

• origin – the start date of the period to plot (e.g., July 1, 2021)

• offset_in_months – the number of months to plot from the start date (e.g., 3 to plot from July 1 to September 30)

• toshow – if True, displays the plot at the end of the function (default: False)

• figax – a tuple (fig, ax) of matplotlib to plot on an existing figure (default: None)

Returns:

a tuple (fig, ax) of matplotlib containing the created or modified plot

save(data: pandas.Series, filename: str, format: Literal['csv', 'parquet'] = 'csv')

load(name: str = '', code: int = 0, filename: str = '', fromdate: datetime.datetime = None, todate: datetime.datetime = None, format: Literal['csv', 'parquet'] = 'parquet')

_download_one(dirout: pathlib.Path | str = None, name: str = '', fromyear: int = 2002, toyear: int = dt.datetime.now().year, timezone: str = 'GMT+1', format: Literal['csv', 'parquet'] = 'parquet', force: bool = False)

download_all(dirout: pathlib.Path | str = None, fromyear: int = 2002, toyear: int = dt.datetime.now().year, timezone: str = 'GMT+1', format: Literal['csv', 'parquet'] = 'parquet', force: bool = False)

update_all(dirin: pathlib.Path | str = None, format: Literal['csv', 'parquet'] = 'parquet')

update_one(ts_id: str, dirin: pathlib.Path | str = None, format: Literal['csv', 'parquet'] = 'parquet')

load_all(dirin: pathlib.Path | str = None, fromdate: datetime.datetime = None, todate: datetime.datetime = None, timezone: str = 'GMT+1', format: Literal['csv', 'parquet'] = 'parquet')

classmethod analyze(serie: pandas.Series, name: str, volume: bool = True, min_daily_rainfall: float = 0.1, force_unique_timestep: bool = False) → StatisticsSeries

Analyze the time serie and return statistics

• Global statistics: mean, median, std, min, max

• Missing values : number and percentage of missing values

• Date range: start and end dates

• Years : number of years, number of complete years

• Yearly statistics : mean, median, std, min, max per year

• Monthly statistics : mean, median, std, min, max per month

Parameters:

• serie – pd.Series, time series to analyze

• name – str, name of the time series

• volume – bool, if True, convert intensity to volume per month/year

• min_daily_rainfall – float, minimum daily rainfall to consider

• force_unique_timestep – bool, if True, enforce unique time step between non-NA values, otherwise, the time step is set to None if inconsistent time steps are found

Returns:

StatisticsSeries, statistics

analyze_all(min_value: float = 0.1, volume: bool = True) → list[StatisticsSeries]

Analyze all the series currently loaded in memory and return a dictionary of statistics with station names as keys and statistics as values

classmethod plot_time_ranges(statistics: list[StatisticsSeries], figax=None)

Create a plot showing the time ranges of the given statistics

Parameters:

• statistics – list of dict, statistics to plot

• figax – tuple of (fig, ax) or None

Returns:

tuple of (fig, ax)

classmethod plot_yearly_statistics(statistics: StatisticsSeries, title: str = 'Yearly Statistics', figax=None)

Plot yearly statistics with error bars (mean +/- std)

Parameters:

• statistics – dict, statistics to plot

• title – str, title of the plot

• figax – tuple of (fig, ax) or None

Returns:

tuple of (fig, ax)

classmethod plot_yearly_boxplots(statistics: StatisticsSeries, title: str = 'Yearly Boxplots', figax=None)

Plot yearly statistics as boxplots

Parameters:

• statistics – dict, statistics to plot

• title – str, title of the plot

• figax – tuple of (fig, ax) or None

Returns:

tuple of (fig, ax)

classmethod plot_monthly_statistics(statistics: StatisticsSeries, title: str = 'Monthly Statistics', figax=None)

Plot monthly statistics with error bars (mean +/- std)

Parameters:

• statistics – dict, statistics to plot

• title – str, title of the plot

• figax – tuple of (fig, ax) or None

Returns:

tuple of (fig, ax)

classmethod plot_monthly_boxplots(statistics: StatisticsSeries, title: str = 'Monthly Boxplots', figax=None, unit_factor: float = 1.0)

Plot monthly statistics as boxplots

Parameters:

• statistics – dict, statistics to plot

• title – str, title of the plot

• figax – tuple of (fig, ax) or None

• unit_factor – float, factor to convert units (e.g. from m3 to 1000 m3)

Returns:

tuple of (fig, ax)

class wolfhece.hydrometry.rain_SPW.SPW_pluviographs_1h(store_dir: str | pathlib.Path = None)

Bases: SPW_pluviographs

Management of the rain data from the SPW-MI website through its data download interface The data are stored in a local directory in csv or parquet format, and can be loaded in memory as pandas Series for analysis and plotting.

_timestep_dl

download_all(fromyear=2002, toyear=dt.datetime.now().year, timezone='GMT+1', format='parquet', force: bool = False)

download_one(name='', fromyear=2002, toyear=dt.datetime.now().year, timezone='GMT+1', format='parquet', force: bool = False)

load_all(fromdate=None, todate=None, timezone='GMT+1', format='parquet')

update_all(format: Literal['csv', 'parquet'] = 'parquet')

update_one(ts_id: str, dirin: pathlib.Path | str = None, format: Literal['csv', 'parquet'] = 'parquet')

class wolfhece.hydrometry.rain_SPW.SPW_pluviographs_5min(store_dir: str | pathlib.Path = None)

Bases: SPW_pluviographs

Management of the rain data from the SPW-MI website through its data download interface The data are stored in a local directory in csv or parquet format, and can be loaded in memory as pandas Series for analysis and plotting.

_timestep_dl

download_all(fromyear=2002, toyear=dt.datetime.now().year, timezone='GMT+1', format='parquet', force: bool = False)

download_one(name='', fromyear=2002, toyear=dt.datetime.now().year, timezone='GMT+1', format='parquet', force: bool = False)

load_all(fromdate=None, todate=None, timezone='GMT+1', format='parquet')

update_all(format: Literal['csv', 'parquet'] = 'parquet')

update_one(ts_id: str, dirin: pathlib.Path | str = None, format: Literal['csv', 'parquet'] = 'parquet')

wolfhece.hydrometry.rain_SPW.my_5min