plans.datasets.core

Primitive classes for handling datasets.

Functions

dataframe_prepro(dataframe)	Utility function for dataframe pre-processing.
get_colors([size, cmap, randomize])	Utility function to get a list of random colors

Classes

QualiHard([name])	A Quali-Hard is a hard-coded qualitative map (that is, the table is pre-set)
QualiRaster([name, dtype])	Basic qualitative raster map dataset.
QualiRasterCollection(name)	The raster collection base dataset.
QualiRasterSeries(name, varname, varalias[, ...])	A RasterSeries where date matters and all maps in collections are expected to be QualiRaster` with the same variable, same projection and same grid.
Raster([name, alias, dtype])	The basic Raster map dataset.
RasterCollection([name])	The raster collection base dataset.
RasterSeries(name, varname, varalias, units)	A RasterCollection` where datetime matters and all maps in collections are expected to be the same variable, same projection and same grid.
SciRaster([name, alias])	Scientific (float32) raster dataset with a configurable nodata value and display range.
SeasonalEnsemble([name, base_object])	Ensemble of the years of a single series, for seasonal plots.
TimeSeries([name, alias])	A time series dataset with a datetime-indexed variable.
TimeSeriesCluster([name, base_object])	Collection of same-variable time series from different sites (e.g., a network of rain gauges).
TimeSeriesCollection([name, base_object])	A collection of time series objects with associated metadata.
TimeSeriesEnsemble([name, base_object])	Collection of same-variable time series as realizations of the same series (same site and time), e.g., stochastic draws or model runs.
Zones([name])	Zones map dataset is a QualiRaster designed to handle large volume of positive integer numbers (ids of zones)

plans.datasets.core.dataframe_prepro(dataframe)

Utility function for dataframe pre-processing.

Parameters:

dataframe (pandas.DataFrame) – incoming dataframe

Returns:

prepared dataframe

Return type:

pandas.DataFrame

plans.datasets.core.get_colors(size=10, cmap='tab20', randomize=True)

Utility function to get a list of random colors

Parameters:

• size (int) – Size of list of colors

• cmap (str) – Name of matplotlib color map (cmap)

Returns:

list of random colors

Return type:

list

class plans.datasets.core.TimeSeries(name='MyTimeSeries', alias='TS0')

Bases: Univar

A time series dataset with a datetime-indexed variable.

Extends Univar with temporal structure: frequency detection, standardization, gap analysis, and scaling.

EPOCHS_ROWS = 14

__init__(name='MyTimeSeries', alias='TS0')

_set_fields()

Set catalog fields names. Expected to increment superior methods.

_set_frequency()

Infer the datetime frequency of the time series from the spacing between consecutive timestamps.

The mode (most common value) of consecutive timestamp deltas is used to determine the frequency, rather than checking which calendar components (seconds, minutes, hours, …) vary across the series. This makes detection robust to a small minority of jittered or missing timestamps: as long as the majority of gaps between consecutive records share the same spacing, that spacing wins, even if a few records are irregular.

Sets self.dtfreq to one of the supported Pandas-like frequency aliases ("1min", "20min", "h", "D", "MS", "YS") based on which boundary the modal delta falls into, and self.dtres to the corresponding resolution label ("second", "minute", "hour", "day", "month", "year").

For "MS" and "YS" frequencies, self.gapsize is also forced to 1, since a single missing month or year is already a meaningful gap at that resolution.

Note

Detection is based on the majority delta, not a strict consistency check. If irregular spacing accounts for more than half of the deltas in the series, the detected frequency will reflect that majority rather than the “intended” sampling rate. Always sanity-check self.dtfreq after loading unfamiliar or untrusted data.

Returns:

None. Updates self.dtfreq, self.dtres, and possibly self.gapsize in place.

Return type:

None

get_metadata()

Get a dictionary with object metadata. Expected to increment superior methods.

Note

Metadata does not necessarily inclue all object attributes.

Returns:

dictionary with all metadata

Return type:

dict

get_range_datetime()

Return the [start, end] datetime extent of the loaded data.

Returns:

Two-element list of [min, max] Timestamps.

Return type:

list

get_seasonal_ensemble(year_start=1)

Get an ensemble with one member per year of the series.

Parameters:

year_start (int) – first month of the year, from 1 to 12. Default is 1.

Returns:

ensemble with members of the same type as this series

Return type:

SeasonalEnsemble

update()

Update internal attributes based on the current data.

Notes

• Calls the set_frequency method to update the datetime frequency attribute.

• Updates the start attribute with the minimum datetime value in the data.

• Updates the end attribute with the maximum datetime value in the data.

• Updates the var_min attribute with the minimum value of the variable field in the data.

• Updates the var_max attribute with the maximum value of the variable field in the data.

• Updates the data_size attribute with the length of the data.

• Refreshes the default view_specs. Specs set by the user are kept.

setter(dict_setter, load_data=True)

Set selected attributes based on an incoming dictionary. Expected to increment superior methods.

Parameters:

• dict_setter (dict) – incoming dictionary with attribute values

• load_data (bool) – option for loading data from incoming file. Default is True.

set_data(input_df, input_dtfield, input_varfield, filter_dates=None, dropnan=False)

Set time series data from an inputs DataFrame.

Parameters:

• input_df (pandas.DataFrame) – Input DataFrame containing time series data.

• input_dtfield (str) – Name of the datetime field in the inputs DataFrame.

• input_varfield (str) – Name of the variable field in the inputs DataFrame.

• filter_dates – List of [Start, End] used for filtering date range.

• dropnan (bool) – If True, drop NaN values from the DataFrame. Default is False.

Notes

• Assumes the inputs DataFrame has a datetime column in the format “YYYY-mm-DD HH:MM:SS”.

• Renames columns to standard format (datetime: self.dtfield, variable: self.varfield).

• Converts the datetime column to standard format.

load_data(file_data, input_dtfield=None, input_varfield=None, in_sep=';', filter_dates=None)

Load data from file. Expected to overwrite superior methods.

Parameters:

• file_data (str) – Absolute Path to the csv inputs file.

• input_varfield (str) – Name of the incoming varfield.

• input_dtfield (str) – Name of the incoming datetime field. Default is “datetime”.

• sep (list) – String separator. Default is ;.

• filter_dates – List of start and end date to filter. Default is None

Notes

• Assumes the inputs file is in csv format.

• Expects a datetime column in the format YYYY-mm-DD HH:MM:SS.

cut_edges(inplace=False)

Cut off initial and final NaN records in a given time series.

Parameters:

inplace (bool) – If True, the operation will be performed in-place, and the original data will be modified. If False, a new DataFrame with cut edges will be returned, and the original data will remain unchanged. Default is False.

Returns:

If inplace is False, a new DataFrame with cut edges. If inplace is True, returns None, and the original data is modified in-place.

Return type:

pandas.DataFrame`` or None

Notes

• This function removes leading and trailing rows with NaN values in the specified variable field.

• The operation is performed on a copy of the original data, and the original data remains unchanged.

_cut_edges(df)

Get a dataframe without its initial and final NaN records.

Parameters:

df (pandas.DataFrame) – dataframe with the variable field

Returns:

copy of the dataframe, unchanged if all records are NaN

Return type:

pandas.DataFrame

standardize()

Force the time series onto a regular datetime grid at its detected frequency.

This builds a full, evenly-spaced date range spanning the series’ start to end (at day resolution) and left-merges the existing data onto it. Any regular-grid slot that has no matching timestamp in the original data becomes a row with a null value in varfield – i.e. standardizing an irregular series (one with missing timestamps) is what turns those missing timestamps into explicit gaps.

If multiple original records fall within the same grid slot (e.g. two readings a few minutes apart, both bucketed into the same hour), they are aggregated using the agg attribute (e.g. "mean") before being placed in that slot.

Notes

• The target frequency is read from self.dtfreq, which is set by _set_frequency() (called automatically on load, based on the mode of consecutive timestamp deltas – robust to a handful of jittered or missing timestamps, but not to a majority of them).

• Bucketing uses .dt.floor() for fixed-frequency grids (1min, 20min, h, D) and calendar-aware period flooring for calendar-variable grids (MS, YS), so each timestamp is always bucketed independently based on its own value, never merged with unrelated timestamps in the same coarser unit.

• Sets self.is_standard = True on completion. Methods that need the regular grid (e.g. get_epochs, interpolate_gaps) work on a regular copy while this flag is False, leaving self.data as it is.

• Calls self.update() at the end, refreshing derived statistics to reflect the new (possibly larger, possibly gap-containing) data.

Warning

This method modifies self.data in place (there is no inplace parameter). If you need the original, irregular data preserved, keep a separate reference or a copy.deepcopy of the object before calling this method.

Warning

Row count generally increases after standardizing an irregular series, since missing grid slots are inserted as null rows. Review len(self.data) and the null count after calling this method rather than assuming they’re unchanged.

Returns:

None. Updates self.data and self.is_standard in place.

Return type:

None

Example:

>>> ts.is_standard
False
>>> len(ts.data)
311
>>> ts.standardize()
>>> ts.is_standard
True
>>> len(ts.data)          # now includes inserted null rows
360
>>> ts.data[ts.varfield].isna().sum()
49

_get_standard_data(cut=False)

Get a copy of the data on the regular grid. The series is not changed.

Parameters:

cut (bool) – If True, also cut off the initial and final NaN records.

Returns:

data on the regular grid

Return type:

pandas.DataFrame

clear_outliers(inplace=False)

Clears outlier values from the specified variable field in the DataFrame.

Parameters:

inplace (if inplace is True, otherwise the DataFrame with outliers cleared.) – If True, the operation is performed in-place, modifying the DataFrame directly. If False, a new DataFrame with outliers removed is returned. Default value = False

Return type:

pandas.DataFrame or None

get_epochs(inplace=False)

Get Epochs (periods) for continuous time series (0 = gap epoch).

Parameters:

inplace (bool) – Option to set Epochs inplace. Default is False.

Returns:

A DataFrame if inplace is False or None.

Return type:

pandas.DataFrame`, None

Notes

This function labels continuous chunks of data as Epochs, with Epoch 0 representing gaps in the time series. Missing timestamps count as gaps, since the labels are made on the regular grid.

With inplace=True, the data becomes the labeled regular grid.

_label_epochs(df)

Label the records of a dataframe by epoch (0 = gap epoch).

Parameters:

df (pandas.DataFrame) – dataframe with the variable field, one record per time step

Returns:

copy of the dataframe with the epoch field

Return type:

pandas.DataFrame

update_epochs_stats()

Update all epochs statistics.

Notes

• This function updates statistics for all epochs in the time series.

• Works on a regular copy of the data without its NaN edges. The data itself is not changed.

• Removes epoch 0 from the statistics since it typically represents non-standardized or invalid data.

• Groups the data by and calculates statistics such as count, start, and end timestamps for each epoch.

• Generates random colors for each epoch using the get_random_colors function with a specified colormap (cmap` attribute).

• Includes the time series name in the statistics for identification.

• Organizes the statistics DataFrame to include relevant columns

• Updates the attribute with the number of epochs in the statistics.

interpolate_gaps(method='linear', constant=0, inplace=False)

Fills gaps in a time series using various interpolation methods.

Parameters:

• method (str) – Specifies the interpolation method. The default value is linear.

• constant (float) – The constant value used when the constant method is selected. Default value = 0.

• inplace (bool) – If True, modifies the original DataFrame in-place. Default value = False.

Returns:

A new pandas.DataFrame with interpolated values and an is_interpolation flag column (1 where the value was filled by interpolation, 0 where it was already present) if inplace is False, otherwise None.

Return type:

pandas.DataFrame or None

Notes

The interpolation runs on the regular grid. The series is only standardized if inplace is True. The process is applied to each unique epoch within the series.

• linear: linear interpolation

• nearest: uses the value of the closest data point.

• zero: fills gaps with zeros.

• constant: fills gaps with a constant value provided in method parameter

• slinear: first order spline interpolation

• quadratic: second order spline interpolation

• cubic: third order spline interpolation

aggregate(freq, bad_max, agg_funcs=None)

Aggregate the time series data based on a specified frequency using various aggregation functions.

Parameters:

• freq (str) – Pandas-like alias frequency at which to aggregate the time series data.

• bad_max (int) – The maximum number of Bad records allowed in a time window for aggregation. Records with more Bad entries will be excluded from the aggregated result. Default is 7.

• agg_funcs (dict) – A dictionary specifying customized aggregation functions for each variable. Default is None, which uses standard aggregation functions (sum, mean, median, min, max, std, var, percentiles).

Returns:

A new pandas.DataFrame with aggregated values based on the specified frequency.

Return type:

pandas.DataFrame

Notes

Resamples the time series data to the specified frequency using Pandas-like alias strings. Aggregates the values using the specified aggregation functions. Counts the number of Bad records in each time window and excludes time windows with more Bad entries than the specified threshold.

Common options include:

• h for hourly frequency

• D for daily frequency

• W for weekly frequency

• MS for monthly/start frequency

• QS for quarterly/start frequency

• YS for yearly/start frequency

More options and details can be found in the Pandas documentation: https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#timeseries-offset-aliases.

scale_up(freq, bad_max, inplace=True)

Upscale time series for larger time steps. This method uses the agg attribute. See the aggregate method.

Parameters:

• freq (str) –

  Pandas-like alias frequency at which to aggregate the time series data. Common options include: - h for hourly frequency - D for daily frequency - W for weekly frequency - MS for monthly/start frequency - QS for quarterly/start frequency - YS for yearly/start frequency More options and details can be found in the Pandas documentation: https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#timeseries-offset-aliases.

  Anchoring behavior – this affects where each aggregation window starts/ends:

  • Plain multiples of a base unit (e.g. "5D" for a pentad, "10D") are data-start-anchored: bins are chunked every N units starting from wherever the series begins, not from a fixed calendar boundary.

  • Calendar units (W, MS, QS, YS, etc.) are calendar-anchored: bins snap to fixed real-world boundaries regardless of where the data starts.

  • W defaults to W-SUN (weeks ending Sunday). Anchor to any weekday with a suffix, e.g. W-MON, W-WED, W-FRI.

  • YS/YE default to the calendar year (start Jan 1 / end Dec 31). Anchor to any month with a suffix to define e.g. a hydrological/water year: "YS-OCT" (year starting Oct 1, e.g. US water year convention) or "YE-SEP" (year ending Sep 30). The suffix month plus YS-/YE- together set whether that month is the start or the end of the bin.

• bad_max (int) – The maximum number of Bad records allowed in a time window for aggregation. Records with more Bad entries will be excluded from the aggregated result.

• inplace (bool) – option for overwrite data, default True. When False, returns a new TimeSeries object (an exact copy of self) holding the upscaled data, instead of a bare DataFrame.

Returns:

None if inplace=True (data is overwritten in place), otherwise a new TimeSeries instance of the same subclass as self, with identical metadata and the upscaled data/derived stats.

Return type:

None or TimeSeries

Example:

>>> # Pentad upscale (data-start-anchored)
>>> ts_pentad = ts.scale_up(freq="5D", bad_max=0, inplace=False)
>>> # Weekly upscale, anchored to Monday-ending weeks
>>> ts_weekly = ts.scale_up(freq="W-MON", bad_max=0, inplace=False)
>>> # Hydrological year, Oct-Sep
>>> ts_hydro = ts.scale_up(freq="YS-OCT", bad_max=0, inplace=False)

scale_down(freq, covariate=None, align='center', inplace=False)

Downscale the time series to a finer time step.

For non-flow variables (self.agg != "sum"), each coarse data point is first repositioned in time according to align (see below), then linearly interpolated onto the finer grid. Because this repositioning shifts the interpolation anchors away from a naive “value at period start” assumption, a single global multiplicative correction is applied afterward so that the downscaled series’ overall mean exactly matches the original series’ overall mean. Note this conserves the mean of the whole series, not each individual period – an earlier, stricter per-period mean-preserving approach was found to produce unstable, oscillating results with volatile inputs and was intentionally not used here.

The align parameter controls where each coarse point is assumed to sit within the period it represents:

• "start": at the period’s own timestamp (no shift). E.g. a daily value stays anchored at 00:00.

• "center" (default): at the middle of the period. E.g. a daily value is anchored at 12:00 of that day.

• "end": at the end of the period. E.g. a daily value is anchored at the following day’s 00:00.

Anchor placement leaves flat (constant) values outside the earliest/latest anchor – e.g. with align="center", there is no data before the first period’s midpoint, so the interpolated series holds that first value flat until the midpoint is reached.

For flow/sum variables (self.agg == "sum", e.g. precipitation totals), each source period’s total is distributed across its fine sub-steps such that the sub-steps sum back to exactly that period’s original total – no mass leaks across period boundaries. align is not used in this case (sum conservation is enforced directly at the level of each time step, not via anchor placement). Two modes:

• Uniform split (default, covariate=None): each period’s total is split evenly across its fine sub-steps.

• Covariate-weighted (covariate given): each period’s total is distributed proportionally to a covariate signal’s own shape within that period, e.g. using a higher-resolution proxy (radar or satellite precipitation) to shape how a daily gauge total is spread across finer time steps. The covariate is linearly interpolated onto the target grid first if it isn’t already sampled at freq. Any period where the covariate is entirely zero or missing falls back to a uniform split for that period, so covariate gaps never produce NaN or divide-by-zero results.

In both branches, the fine grid is extended one full period past the series’ last timestamp so the final period is subdivided the same way as every other period, rather than being collapsed into a single fine step holding that whole period’s value.

Parameters:

• freq (str) – new time step frequency

• covariate (TimeSeries or None) – optional higher-resolution TimeSeries whose values are used to shape the within-period distribution for flow/sum variables. Ignored when self.agg != "sum".

• align (str) – for non-sum variables, where each coarse point is anchored within its period: "start", "center" (default), or "end". Ignored when self.agg == "sum".

• inplace (bool) – option for overwrite data, default False. When True, overwrites self.data with the downscaled result and returns None. When False (default), returns a new TimeSeries instance (an exact copy of self) holding the downscaled data, instead of a bare DataFrame.

Returns:

None if inplace=True (data is overwritten in place), otherwise a new TimeSeries instance of the same subclass as self, with identical metadata and the downscaled data/derived stats.

Return type:

None or TimeSeries

Example:

>>> # non-sum variable, e.g. daily-average water level -> hourly,
>>> # anchored at midday, overall mean preserved
>>> ts_level_hourly = ts_level.scale_down(freq="1h")
>>> # uniform split: each day's total spread evenly across hours
>>> ts_flat = ts_daily.scale_down(freq="1h")
>>> # covariate-weighted: shaped by an hourly satellite proxy
>>> ts_shaped = ts_daily.scale_down(freq="1h", covariate=ts_satellite)

assess_extreme_values(eva_freq='YS', eva_agg='max')

Run Extreme Values Analysis (EVA) over the Time Series and set the eva attribute

Parameters:

• eva_freq (str) – standard pandas frequency alias for upscaling data

• eva_agg (str) – standard pandas aggregation alias for upscaling (expected: max or min)

_build_axes(fig, gs, specs)

Add subplots to the figure grid according to the active layout.

_plot(fig, gs, specs)

Plot on figure based on layout.

Parameters:

• fig (matplotlib.figure.Figure) – figure object

• gs (matplotlib.gridspec.GridSpec) – grid of the figure

• specs (dict) – plot specification dictionary

Returns:

figure object

Return type:

matplotlib.figure.Figure

_set_view_specs()

Set view specifications.

view(show=True, return_fig=False)

View the TimeSeries data.

Note

Use values in the view_specs() attribute for plotting

Layouts, set by view_specs["layout"]:

Layout	Panels
full	Series, histogram and CDF, with the statistics table.
mini	Series, histogram and CDF.
simple	Series only.
simple-shallow	Series only, in a shallow figure.
epochs	Series with epochs in colors and gaps in the background, and the list of epochs.
default	Same panels of mini, in the figure of full.

View specs, set by view_specs[key] = value before the call:

Key	Default	Description
style	"wien"	Name of the plot style. See plans.viewer.set_style().
folder	auto	Folder of the saved figure.
filename	auto	Name of the saved figure, without extension.
fig_format	"jpg"	Format of the saved figure.
dpi	300	Resolution of the saved figure.
title	auto	Title of the figure.
xvar	auto	Internal. Column of dates.
yvar	auto	Internal. Column of values.
xlabel	auto	Label of the x axis.
ylabel	auto	Label of the y axis.
color	"gray"	Color of the line.
xmin	None	Not in use.
xmax	None	Not in use.
ymin	0	Bottom of the fill.
ymax	None	Not in use.
layout	"full"	Name of the layout. See the table of layouts.
data_plot	"scatter"	Plot of the data panel: "scatter" or "boxplot".
subtitle_data	"Time Series"	Title of the series panel. None hides it.
subtitle_box	"Boxplot"	Title of the data panel, if a boxplot.
subtitle_hist	"Histogram"	Title of the histogram. None hides it.
subtitle_cdf	"CDF"	Title of the CDF. None hides it.
subtitle_qq	"Q-Q"	Title of the Q-Q panel. None hides it.
yvar_field	auto	Column of values. Set with the data.
xlabel_cdf	"P(X)"	Label of the x axis of the CDF.
xlabel_qq	auto	Label of the x axis of the Q-Q panel.
data_label	auto	Label of the data in the legend.
data_legend	False	Show the legend of the data panel.
color_hist	"tab:grey"	Color of the histogram.
color_cdf	"black"	Color of the CDF.
color_mean	"red"	Color of the mean line.
color_mean_text	None	Color of the mean label. None is gray.
scheme_cmap	"equal"	Classes of the color map: "equal", "quantiles" or other schemes of plans.stochastic.binning.get_bins().
n_classes_cmap	5	Number of classes of the color map.
cmap	"viridis"	Name of the color map.
alpha	1	Opacity of the line.
alpha_hist	1	Opacity of the histogram.
alpha_cdf	1	Opacity of the CDF.
range	None	Range of the y axis, as [low, high]. None is set from the data.
range_x	None	Range of the x axis, as [low, high]. None is the time span with pad_x.
plot_mean	True	Show the mean line.
plot_mean_data	False	Show the mean line also on the data panel.
linestyle_mean	"solid"	Line style of the mean.
pad_mean	1	Spaces between the mean label and its line.
plot_mean_label	True	Show the mean label.
hist_density	True	Not in use.
bins	20	Number of histogram bins, or the width of the bins if bins_density.
bins_density	False	Take bins as the width of the bins.
ax_data	0	Internal. Index of the data axis.
ax_hist	1	Internal. Index of the histogram axis. False has no histogram.
ax_cdf	2	Internal. Index of the CDF axis. False has no CDF.
x_stats	0.73	Horizontal position of the statistics table, as a share of the figure.
x_stats_sep	0.12	Space between columns of the statistics table.
y_stats	0.28	Vertical position of the statistics table, as a share of the figure.
zorder_data	1	Drawing order of the data.
zorder_histh	1	Drawing order of the histogram.
zorder_cdf	1	Drawing order of the CDF.
scatter_factor	4	Size of the scatter markers.
colorize_scatter	False	Color the scatter markers by the color map.
box_width	0.4	Width of the boxplot.
box_showfliers	True	Show the outliers of the boxplot.
subtitle_epochs	"Epochs"	Title of the list of epochs, in the epochs layout.
color_aux	"gray"	Not in use.
color_fill	None	Color of the fill. None is the color of the line.
color_eva	"blue"	Color of the annual maxima.
legend_eva	"Annual Maxima"	Label of the annual maxima.
alpha_aux	1	Not in use.
alpha_fill	1	Opacity of the fill.
fill	False	Fill below the line, down to ymin.
fill_only	False	With fill, hide the line.
color_gaps	"tab:red"	Color of the gaps, in the epochs layout.
alpha_gaps	0.6	Opacity of the gaps, in the epochs layout.
linewidth_gaps	0.5	Width of the edge of the gaps, which keeps short ones visible.
xmax_aux	20	Not in use.
pad_x	0.05	Share of the time span added on each side of the x axis, if range_x is None.
linestyle	"solid"	Line style.
marker	None	Marker of the line.
marker_eva	"."	Not in use.
drawstyle	None	Draw style of the line, such as "steps-mid".
n_bins	100	Not in use.
n_dates	5	Number of date ticks, evenly spaced in time. None chooses them automatically.
format_dates	"%Y-%m-%d"	Format of the date labels.
include_eva	False	Show the annual maxima and their model. Needs the extreme values analysis.
gs_*	auto	Internal. Replaced by the shared grid of plans.viewer.

Parameters:

• show (bool) – option for showing instead of saving.

• return_fig (bool) – option for returning the figure object itself.

_plot_epochs(ax, ax_legend, specs)

Plot each epoch in its own color and the gaps in the background, with the list of epochs on the side. The series is not changed.

Parameters:

• ax (matplotlib.axes.Axes) – axis of the series

• ax_legend (matplotlib.axes.Axes) – axis of the legend

• specs (dict) – plot specification dictionary

Returns:

None

Return type:

None

static get_range_x(xmin, xmax, pad)

Get the range of a time axis with a padding on each side.

Parameters:

• xmin (pandas.Timestamp) – first date

• xmax (pandas.Timestamp) – last date

• pad (float) – share of the time span added on each side

Returns:

first and last date of the range

Return type:

list

static set_date_ticks(ax, xmin, xmax, n_dates, format_dates)

Set ticks evenly spaced in calendar time on a time axis, within its limits.

Parameters:

• ax (matplotlib.axes.Axes) – target axis

• xmin (pandas.Timestamp) – date of the first tick

• xmax (pandas.Timestamp) – date of the last tick

• n_dates (int) – number of ticks. If None, they are chosen automatically

• format_dates (str) – format of the dates. If None, it is the current one

Returns:

None

Return type:

None

static plot_series(data, ax, specs)

Draw a time series line (and optional fill) onto an existing axes.

Parameters:

• data (pandas.DataFrame) – DataFrame containing the series to plot.

• ax (matplotlib.axes.Axes) – Target Matplotlib axes.

• specs (dict) – Plot specification dictionary (from view_specs).

static add_hour(df, hour=12, dt_field='datetime')

Set the time component of a date-only datetime column to a fixed hour.

Parameters:

• df (pandas.DataFrame) – DataFrame with a datetime column to modify.

• hour (int) – Hour to set. Default is 12 (noon).

• dt_field (str) – Name of the datetime column. Default is "datetime".

Returns:

DataFrame with the datetime column updated.

Return type:

pandas.DataFrame

static view_compare_times_series(ts_first, ts_second, specs, show=False, return_fig=False)

Plot two TimeSeries objects together for visual comparison.

Renders a three-panel figure – the two series overlaid on a shared time axis, a horizontal histogram, and a CDF – using ts_first’s panel layout as the base and drawing ts_second on top of it. Both series are shown with their own colors (taken from each object’s view_specs["color"]) and labeled with their respective name attributes; each series’ mean is annotated on the CDF panel.

Parameters:

• ts_first (TimeSeries) – The first time series to plot. Its own view_specs supplies the base panel layout (axes, figure size, etc.); set ts_first.view_specs["color"] before calling to control its plotted color.

• ts_second (TimeSeries) – The second time series to plot on top of the first. Likewise, set ts_second.view_specs["color"] to control its color.

• specs (dict) – Plot overrides applied to both series before plotting (merged into each series’ view_specs). Must include "title". If return_fig is False, must also include "folder" and "filename" (used to build the output file path); "dpi" and "fig_format" are taken from ts_first.view_specs regardless of what is passed in specs. Without "range", the y axis of all panels covers both series.

• show (bool) – If return_fig is False, whether to display the figure interactively in addition to saving it. Ignored if return_fig is True.

• return_fig (bool) – If True, return the Matplotlib Figure instead of saving it to disk. Useful for inline display (e.g. in a notebook) or for further customization before saving.

Returns:

The Figure if return_fig=True, otherwise None (the figure is saved to "{folder}/{filename}.{fig_format}").

Return type:

matplotlib.figure.Figure or None

Note

Both input objects’ view_specs are mutated in place by this method (colors, labels, layout, and the contents of specs are all written into ts_first.view_specs/ts_second.view_specs). If you need the originals preserved, pass copies.

Example:

>>> ts1.view_specs["color"] = "tab:blue"
>>> ts2.view_specs["color"] = "tab:orange"
>>> fig = TimeSeries.view_compare_times_series(
...     ts1, ts2, specs={"title": "Site A vs Site B"}, return_fig=True
... )

static _get_steps_per_year(freq)

Get the number of time steps in a year for a frequency.

Parameters:

freq (str) – frequency alias

Returns:

steps per year, a whole number when the steps follow the calendar

Return type:

float

_get_generator_params(start, freq, n)

Convert generator_specs to the parameters of a given time step.

\[\varphi = e^{-\Delta t / \tau}, \qquad \sigma = s \sqrt{1 - \varphi^2}\]

Parameters:

• start (pandas.Timestamp) – first date of the series

• freq (str) – frequency alias

• n (int) – number of steps

Returns:

parameters. See plans.stochastic.arma.fit_params().

Return type:

dict

generate(start, end, freq=None, params=None, seed=None, inplace=False)

Generate a synthetic series with trend, a yearly cycle and AR(1) memory.

Without params, it uses the generator_specs attribute, which each child class sets for its own variable and which can be edited. These specs are in physical terms, so they apply to any time step:

• baseline and topline: lowest and highest points of the yearly cycle, at the middle of the record. Per day if the object aggregates by sum.

• peak_day: day of the year of the peak.

• power: shape of the cycle. See plans.stochastic.arma.cycle_shape().

• memory_days: time for the memory of the remainder to decay by a factor of e.

• remainder_sd: standard deviation of the remainder. Per day if aggregated by sum.

• change_per_year: change of the trend per year. Per day if aggregated by sum.

Values below generator_floor are pruned to it, if it is set.

Warning

Default specs are plausible values for examples, not climatology. There is no daily cycle at any time step, since sub-daily series are meant to come from downscaling a daily series.

Parameters:

• start (str or pandas.Timestamp) – first date

• end (str or pandas.Timestamp) – last date

• freq (str) – frequency alias. By default, it is the one in params or D.

• params (dict) – parameters, usually from fit(). Those from fit() follow the calendar, so the cycle and trend carry over to any start.

• seed (int) – random seed

• inplace (bool) – If True, sets the data of this object. Default value = False

Returns:

generated data if inplace is False, otherwise None.

Return type:

pandas.DataFrame or None

static _move_params(params, start)

Move step 0 of the parameters from their origin, if any, to a new start.

Parameters:

• params (dict) – parameters

• start (pandas.Timestamp) – new first date

Returns:

parameters that apply from the new start

Return type:

dict

decompose(params=None)

Split the data into trend, cycle, remainder and shocks. The data is not changed. The remainder holds the memory and the shocks, so that trend + cycle + remainder rebuilds the data.

Parameters:

params (dict) – parameters. By default, they come from fit().

Returns:

dates and components, in columns trend, cycle, remainder and shocks

Return type:

pandas.DataFrame

fit()

Fit the generator parameters to the data. The data is not changed.

The time step comes from the timestamps, so the data must be regular and without gaps. Use standardize() and interpolate_gaps() first if needed.

Returns:

parameters from plans.stochastic.arma.fit_params(), and also origin and freq, so generate() can use them from any date.

Return type:

dict

class plans.datasets.core.TimeSeriesCollection(name='myTSCollection', base_object=None)

Bases: Collection

A collection of time series objects with associated metadata.

The TimeSeriesCollection class extends the Collection class and is designed to handle time series data. It can be miscellaneous datasets.

Note

See TimeSeriesCluster for managing time series of the same variable

PANEL_ROWS = 5

PANEL_GAP_ROWS = 2

ROW_HEIGHT = 5

__init__(name='myTSCollection', base_object=None)

Initialize the Collection object.

Parameters:

• base_object (MbaE) – MbaE-based object for collection

• name (str) – unique object name

• alias (str) – unique object alias.

update(details=False)

Update the time series collection.

Parameters:

details (bool) – bool, optional If True, update additional details. Default is False.

Examples

load_data(table_file, filter_dates=None)

Load data from table file (information table) into the time series collection.

Parameters:

table_file (str) – Path to file. Expected to be a csv table.

set_data(df_info, src_dir=None, filter_dates=None)

Set data for the time series collection from a info class:pandas.DataFrame.

Parameters:

• df_info (class:pandas.DataFrame) – This DataFrame is expected to have matching fields to the metadata keys.

• src_dir (str) – Path for inputs directory in the case for only file names in File column.

• filter_dates (str) – List of Start and End dates for filter data

Notes

• The set_data method populates the time series collection with data based on the provided DataFrame.

• It creates time series objects, loads data, and performs additional processing steps.

• Adjust skip_process according to your data processing needs.

clear_outliers()

Clear outliers in the collection based on the datarange_min and datarange_max attributes.

merge_data(standard=False)

Merge data from every series in the collection into one DataFrame, aligned by an outer join on the datetime field.

Parameters:

standard (bool) – If True, merge the data of each series on its regular grid, so missing timestamps show up. The series are not changed.

Returns:

A merged DataFrame with one datetime column and one value column per series (named "{variable_field}_{alias}").

Return type:

pandas.DataFrame

Notes

This is a passive alignment: the datetime axis is the union of every series’ own timestamps, nothing more. It does not assume, pick, or resample onto any single frequency – a collection is explicitly allowed to mix a daily and an hourly series, and each keeps its own native timestamps here. A daily series simply has no row (NaN) at the hourly series’ intermediate timestamps, and vice versa; nothing is invented and nothing is thrown away. This also means the result is read-only with respect to the members: it is a view for reporting/analysis, and is never written back into any series’ own .data (see standardize()).

standardize()

Standardize every series in the collection, independently.

Notes:

This is deliberately just a batched per-series operation: each member calls its own TimeSeries.standardize() (regularize onto its own native time step), and its own epoch stats are refreshed. Gaps stay as they are. Filling them is a separate decision, see TimeSeries.interpolate_gaps().

No cross-series merge happens here, and no series’ .data is touched by any other series. A collection is explicitly allowed to mix frequencies (e.g. hourly temperature alongside daily rainfall), so there is no single shared grid to standardize onto – that would mean picking one series’ frequency as authoritative and silently resampling everyone else onto it, corrupting their native resolution. Cross-series alignment for reporting/analysis is a separate, non-destructive concern: see merge_data() and get_epochs().

merge_local_epochs()

Merge local epochs statistics from individual time series within the collection.

Returns:

Merged pandas.DataFrame`` containing epochs statistics.

Return type:

pandas.DataFrame

Notes

• This method creates an empty list to store individual epochs statistics dataframes.

• It iterates through each time series in the collection.

• For each time series, it updates the local epochs statistics using the :meth:update_epochs_stats method.

• The local epochs statistics dataframes are then appended to the list.

• Finally, the list of dataframes is concatenated into a single dataframe.

get_epochs()

Calculate epochs for the time series data.

Returns:

DataFrame with epochs information.

Return type:

pandas.DataFrame

Notes

• This method merges the time series data to create a working DataFrame.

• It creates a copy of the DataFrame for NaN-value calculation.

• Converts non-NaN values to 1 and NaN values to 0.

• Calculates the sum of non-NaN values for each row and updates the DataFrame with the result.

• Extracts relevant columns for epoch calculation.

• Sets 0 values in the specified overfield column to NaN.

• Creates a new TimeSeries` instance for epoch calculation using the overfield values.

• Calculates epochs using the :meth:get_epochs method of the new TimeSeries` instance.

• Updates the original DataFrame with the calculated epochs.

_set_view_specs()

Set view specifications for the collection dashboard plot (Gantt chart of per-series epochs + cross-series overlap + series prevalence). Mirrors the TimeSeries/Univar pattern: everything the plot needs lives in self.view_specs and is consumed by _get_fig_specs() / _plot().

_set_series_layouts()

Register the series layouts. Meant for same-variable subclasses only, since series of different variables can not share axes.

_get_fig_specs()

Merge view_specs with the chosen named layout’s sizing and with the shared grid defaults (viewer.GRID_SPECS).

_get_panels(specs)

Get the names of series in each panel, checking them. Series in a panel share an axis, so they must have the same units.

Parameters:

specs (dict) – plot specification dictionary

Returns:

names of series, for each panel

Return type:

list

_get_panel_rows(specs)

Get the grid rows of each panel, by share of the total height.

Parameters:

specs (dict) – plot specification dictionary

Returns:

number of rows, for each panel

Return type:

list

_build_axes(fig, gs, specs)

Add the dashboard’s Axes to fig according to layout.

_plot(fig, gs, specs)

Draw the Gantt / overlap / prevalence panels onto fig using proper Axes objects (ax.set_xlim(...) etc.) rather than stateful plt.* calls, so this composes safely with other plots and is safe to call more than once per session.

_get_range_x(specs)

Get the time axis: from the first date to the last one of all series, with a padding on the sides not set by xmin and xmax.

Parameters:

specs (dict) – plot specification dictionary

Returns:

first and last tick, and the range of the axis

Return type:

tuple

_get_labels(specs)

Get series labels (names or aliases), in catalog order.

_plot_series(axes, specs, extra=None, force_background=False)

Plot all series overlaid: series, and (if axes are given) horizontal histograms and CDFs. Reuses the single TimeSeries plotters.

Series in highlight are drawn in color on top of the others, drawn in background style. Above n_series_max series without highlights, all series are background. With plot_background off, background series leave the series panel, but stay in the histograms and CDFs.

Layers, from the bottom: background, bands (from the ensemble), extras and members in color.

Parameters:

• axes (list) – axes to plot on (1 or 3)

• specs (dict) – plot specification dictionary

• extra (list) – [optional] foreground series that are not members (e.g., ensemble reducers)

• force_background (bool) – option to draw all non-highlighted members in background style

Returns:

None

Return type:

None

_set_series_legend(axes, specs)

Set the legend of labeled (foreground) artists of the series panel.

_clear_title(fig, title)

Lower the top of all panels if legend rows reach the figure title.

Parameters:

• fig (matplotlib.figure.Figure) – figure with the panels, the first one having the legend

• title (matplotlib.text.Text) – figure title

Returns:

None

Return type:

None

_plot_stacked(axes, specs)

Plot series on stacked panels with a shared time axis, and (if axes are given) their histograms and CDFs. A lone series looks as in its own view, from its view_specs. Series sharing a panel have overlaid histograms and CDFs in the color of the series. Colors repeated in a panel are replaced, and the y range covers all series of the panel.

Parameters:

• axes (list) – axes to plot on, by panel: series, or series, histogram and CDF

• specs (dict) – plot specification dictionary

Returns:

None

Return type:

None

static _get_panel_colors(ls_series, specs)

Get the color of each series in a panel. A series with a color already in use takes the color of cmap_series farthest from those in use.

Parameters:

• ls_series (list) – series of the panel

• specs (dict) – plot specification dictionary

Returns:

colors, for each series

Return type:

list

view(show=True, return_fig=False)

Visualize the time series collection: a Gantt chart of each series’ own epochs, the cross-series overlap over time, and (in the "full" layout) each series’ data prevalence. The "stacked" and "stacked-simple" layouts draw series on panels instead, set by view_specs["panels"] and view_specs["panel_heights"].

Every knob previously passed as a loose keyword (folder, filename, dpi, fig_format, usealias, colors, titles, axis ranges, layout choice…) now lives in self.view_specs – set it before calling, exactly like TimeSeries.view().

Layouts, set by view_specs["layout"]:

Layout	Panels
full	Gantt chart, overlap and prevalence.
simple	Gantt chart and overlap.
default	Same as full.
stacked	A panel for each entry of panels, with histograms and CDFs, on a shared time axis.
stacked-simple	A panel for each entry of panels, on a shared time axis.

View specs, set by view_specs[key] = value before the call:

Key	Default	Description
layout	"full"	Name of the layout. See the table of layouts.
style	"wien"	Name of the plot style. See plans.viewer.set_style().
title	auto	Title of the figure.
gantt	auto	Title of the Gantt chart.
over	auto	Title of the overlap panel.
prev	auto	Title of the prevalence panel.
xlabel	auto	Label of the time axis.
ylabel_over	"%"	Label of the y axis of the overlap panel.
xlabel_prev	"%"	Label of the x axis of the prevalence panel.
usealias	False	Use aliases instead of names in labels.
n_dates	5	Number of date ticks, evenly spaced in time. None chooses them automatically.
format_dates	"%Y-%m-%d"	Format of the date labels.
xtick_rotation	0	Rotation of the date labels in the full and simple layouts.
color_over	"tab:blue"	Color of the overlap panel.
alpha_over	0.4	Opacity of the fill of the overlap panel.
color_prev	"tab:gray"	Color of the prevalence bars.
gantt_linewidth	6	Largest width of the Gantt lines. It shrinks to fit many series.
n_series_max	10	Above this many series, labels are hidden and series lines go to the background.
xmin	None	Start of the time axis. None is the first date of all series, with pad_x.
xmax	None	End of the time axis. None is the last date of all series, with pad_x.
ymin	None	Bottom of the overlap panel. None is automatic.
ymax	None	Top of the overlap panel. None is automatic.
pad_x	0.05	Share of the time span added on each side of the time axis not set by xmin or xmax.
folder	auto	Folder of the saved figure.
filename	auto	Name of the saved figure, without extension. None is the name of the collection.
suff	""	Suffix of the saved figure, if filename is None.
dpi	300	Resolution of the saved figure.
fig_format	"jpg"	Format of the saved figure.
series	"Series"	Title of the series panel, in the series layouts.
subtitle_hist	"Histogram"	Title of the histograms.
subtitle_cdf	"CDF"	Title of the CDFs.
ylabel	auto	Label of the y axis, in the series layouts. None comes from the variable.
range	None	Common y range, in the series layouts. None is set from the data.
cmap_series	"tab10"	Color map of the series. In series layouts, None uses the color of each series.
linewidth	0.8	Width of the series lines, in the series layouts.
alpha_hist	0.4	Opacity of overlaid histograms.
histtype	"bar"	Type of overlaid histograms. "step" draws outlines only.
bins	30	Number of common bins of overlaid histograms.
plot_mean	True	Show mean lines on overlaid histograms and CDFs.
legend	True	Show the legend of overlaid series.
highlight	None	Names of the series drawn in color, in the series layouts.
plot_background	True	Show the background lines on the series panel.
color_background	"silver"	Color of the background series.
linewidth_background	0.5	Width of the background lines.
alpha_background	0.6	Opacity of the background lines.
alpha_hist_background	0.1	Opacity of the background histograms.
panels	None	Names of the series in each panel, as a list of lists. None is one series per panel.
panel_heights	None	Relative heights of the panels, like [3, 1]. None is equal.

Parameters:

• show (bool) – option for showing instead of saving.

• return_fig (bool) – option for returning the figure object itself.

Returns:

the matplotlib.figure.Figure if return_fig is True, otherwise None (the figure is shown or saved to "{folder}/{filename or name+suff}.{fig_format}").

Return type:

matplotlib.figure.Figure or None

view_old(show=True, folder='./output', filename=None, dpi=300, fig_format='jpg', suff='', usealias=False)

Visualize the time series collection.

Parameters:

• show (bool) – bool, optional If True, the plot will be displayed interactively. If False, the plot will be saved to a file. Default is True.

• folder (str) – str, optional The folder where the plot file will be saved. Used only if show is False. Default is “./output”.

• filename (str or None) – str, optional The base name of the plot file. Used only if show is False. If None, a default filename is generated. Default is None.

• dpi (int) – int, optional The dots per inch (resolution) of the plot file. Used only if show is False. Default is 300.

• fig_format (str) – str, optional The format of the plot file. Used only if show is False. Default is “jpg”.

• usealias – bool, optional Option for using the Alias instead of Name in the plot. Default is False.

export_views(folder, dpi=300, fig_format='jpg', suff='', skip_main=False, raw=False)

Export views of time series data and individual time series within the collection.

Parameters:

• folder (str) – The folder path where the views will be exported.

• dpi (int) – Dots per inch (resolution) for the exported images, default is 300.

• fig_format (str) – Format for the exported figures, default is “jpg”.

• suff (str) – Suffix to be appended to the exported file names, default is an empty string.

• skip_main (bool) – Option for skipping the main plot (pannel)

• raw (str) – Option for considering a raw data series. No epochs analysis. Default is False.

Notes

• Updates the collection details and epoch statistics.

• Calls the view method for the entire collection and individual time series with specified parameters.

• Sets view specifications for individual time series, such as y-axis limits and time range.

export_data(folder, filename=None, merged=True)

Export collection data as CSV files in the given folder.

Parameters:

• folder (str) – Output folder path.

• filename (str or None) – Base filename; defaults to self.name when None.

• merged (bool) – If True, exports a merged data CSV and an epochs summary CSV. If False, exports each series individually.

class plans.datasets.core.TimeSeriesCluster(name='myTimeSeriesCluster', base_object=None)

Bases: TimeSeriesCollection

Collection of same-variable time series from different sites (e.g., a network of rain gauges). No miscellaneous data is allowed.

Supports cross-site analysis: correlation between sites via get_correlation() and gap filling from neighboring sites via regionalize(). Site coordinates are read from the x and y attributes of each series.

Note

See TimeSeriesEnsemble for many realizations of the same series (same site and time).

__init__(name='myTimeSeriesCluster', base_object=None)

Initialize the Collection object.

Parameters:

• base_object (MbaE) – MbaE-based object for collection

• name (str) – unique object name

• alias (str) – unique object alias.

_get_names_others(name)

Get names of all series except name, in catalog order.

get_correlation(method='pearson', min_overlap=30)

Get the correlation matrix between all series, on their overlapping time steps.

Parameters:

• method (str) – correlation method. Options: pearson or spearman

• min_overlap (int) – minimum number of overlapping time steps. Pairs with less overlap are set to NaN.

Returns:

square correlation matrix, indexed by series names

Return type:

pandas.DataFrame

get_weights_by_name(name, method='average')

Compute interpolation weights of all other series relative to a named series.

Parameters:

• name (str) – name of the target series (excluded from the weight set)

• method (str) – weighting scheme: average (uniform) or idw (inverse-distance). Default is average.

Returns:

weights for the other series, in catalog order

Return type:

numpy.ndarray

regionalize(method='average')

Fill gaps of every series with a weighted average of the other series.

Parameters:

method (str) – weighting scheme: average (uniform) or idw (inverse-distance). Default is average.

Returns:

None

Return type:

None

Notes

• Series are standardized first, if not yet.

• Only gaps are filled; observed values are never changed.

• Values are taken as they are, so sites with different levels (e.g., temperature at different elevations) will bias the filling.

• All fillings use the original data, so filled values do not cascade.

_set_view_specs()

Set view specifications. Expected to increment superior methods.

_build_axes(fig, gs, specs)

Add axes to figure based on layout.

_plot(fig, gs, specs)

Plot on figure based on layout.

view(show=True, return_fig=False)

Get the visualization, which also has the correlation between series.

Layouts, set by view_specs["layout"]:

Layout	Panels
full	Gantt chart, overlap and prevalence.
simple	Gantt chart and overlap.
default	Same as full.
stacked	A panel for each entry of panels, with histograms and CDFs, on a shared time axis.
stacked-simple	A panel for each entry of panels, on a shared time axis.
series	All series overlaid, with histograms and CDFs.
series-simple	All series overlaid.
correlation	Correlation matrix.

View specs, set by view_specs[key] = value before the call:

Key	Default	Description
layout	"full"	Name of the layout. See the table of layouts.
style	"wien"	Name of the plot style. See plans.viewer.set_style().
title	auto	Title of the figure.
gantt	auto	Title of the Gantt chart.
over	auto	Title of the overlap panel.
prev	auto	Title of the prevalence panel.
xlabel	auto	Label of the time axis.
ylabel_over	"%"	Label of the y axis of the overlap panel.
xlabel_prev	"%"	Label of the x axis of the prevalence panel.
usealias	False	Use aliases instead of names in labels.
n_dates	5	Number of date ticks, evenly spaced in time. None chooses them automatically.
format_dates	"%Y-%m-%d"	Format of the date labels.
xtick_rotation	0	Rotation of the date labels in the full and simple layouts.
color_over	"tab:blue"	Color of the overlap panel.
alpha_over	0.4	Opacity of the fill of the overlap panel.
color_prev	"tab:gray"	Color of the prevalence bars.
gantt_linewidth	6	Largest width of the Gantt lines. It shrinks to fit many series.
n_series_max	10	Above this many series, labels are hidden and series lines go to the background.
xmin	None	Start of the time axis. None is the first date of all series, with pad_x.
xmax	None	End of the time axis. None is the last date of all series, with pad_x.
ymin	None	Bottom of the overlap panel. None is automatic.
ymax	None	Top of the overlap panel. None is automatic.
pad_x	0.05	Share of the time span added on each side of the time axis not set by xmin or xmax.
folder	auto	Folder of the saved figure.
filename	auto	Name of the saved figure, without extension. None is the name of the collection.
suff	""	Suffix of the saved figure, if filename is None.
dpi	300	Resolution of the saved figure.
fig_format	"jpg"	Format of the saved figure.
series	"Series"	Title of the series panel, in the series layouts.
subtitle_hist	"Histogram"	Title of the histograms.
subtitle_cdf	"CDF"	Title of the CDFs.
ylabel	auto	Label of the y axis, in the series layouts. None comes from the variable.
range	None	Common y range, in the series layouts. None is set from the data.
cmap_series	"tab10"	Color map of the series. In series layouts, None uses the color of each series.
linewidth	0.8	Width of the series lines, in the series layouts.
alpha_hist	0.4	Opacity of overlaid histograms.
histtype	"bar"	Type of overlaid histograms. "step" draws outlines only.
bins	30	Number of common bins of overlaid histograms.
plot_mean	True	Show mean lines on overlaid histograms and CDFs.
legend	True	Show the legend of overlaid series.
highlight	None	Names of the series drawn in color, in the series layouts.
plot_background	True	Show the background lines on the series panel.
color_background	"silver"	Color of the background series.
linewidth_background	0.5	Width of the background lines.
alpha_background	0.6	Opacity of the background lines.
alpha_hist_background	0.1	Opacity of the background histograms.
panels	None	Names of the series in each panel, as a list of lists. None is one series per panel.
panel_heights	None	Relative heights of the panels, like [3, 1]. None is equal.
correlation	"Correlation"	Title of the correlation panel.
corr_method	"pearson"	Correlation method: "pearson", "kendall" or "spearman".
corr_min_overlap	30	Fewest common records for a correlation.
cmap_corr	"RdBu_r"	Color map of the correlation.
range_corr	[-1, 1]	Range of the color map. Narrow it to reveal structure.
annotate	True	Show values on the correlation cells.

Parameters:

• show (bool) – option for showing instead of saving

• return_fig (bool) – option for returning the figure object

Returns:

figure object if return_fig is True, else None

Return type:

matplotlib.figure.Figure or None

_plot_correlation(ax, specs)

Plot the correlation matrix as an annotated heatmap.

class plans.datasets.core.TimeSeriesEnsemble(name='myTimeSeriesEnsemble', base_object=None)

Bases: TimeSeriesCollection

Collection of same-variable time series as realizations of the same series (same site and time), e.g., stochastic draws or model runs.

Supports ensemble reduction across members at each time step via reducer() and its shortcuts (mean(), percentiles(), stats(), etc.). Reducers ignore missing values. The series view draws members in background style, with reducers and percentile bands on top.

Note

See TimeSeriesCluster for same-variable series from different sites.

__init__(name='myTimeSeriesEnsemble', base_object=None)

Initialize the Collection object.

Parameters:

• base_object (MbaE) – MbaE-based object for collection

• name (str) – unique object name

• alias (str) – unique object alias.

reducer(reducer_funcs=None, stepwise=False)

Apply reducer functions across all members at each time step.

Parameters:

• reducer_funcs (dict) – mapping of output name to a dict with "Func" (callable) and "Args" (extra scalar argument or None).

• stepwise (bool) – if True, apply each function row-by-row rather than vectorized along axis 1. Default is False.

Returns:

DataFrame with datetime and one column per reducer function, named "{varalias}_{name}"

Return type:

pandas.DataFrame

mean()

Return the time-step-wise mean across all members.

median()

Return the time-step-wise median across all members.

rng()

Return the time-step-wise range (max - min) across all members.

std()

Return the time-step-wise standard deviation across all members.

min()

Return the time-step-wise minimum across all members.

max()

Return the time-step-wise maximum across all members.

percentile(p=90)

Return the time-step-wise p-th percentile across all members.

Parameters:

p (float) – percentile value (0-100). Default is 90.

Returns:

DataFrame with datetime and the "{varalias}_p{p}" column

Return type:

pandas.DataFrame

percentiles(values=None)

Return time-step-wise percentiles across all members.

Parameters:

values (list) – percentile values to compute. Default is [1, 5, 10, 25, 50, 75, 90, 95, 99].

Returns:

DataFrame with datetime and one "{varalias}_p{p}" column per value (e.g., p05, p50)

Return type:

pandas.DataFrame

stats(basic=False)

Return a combined DataFrame of common statistics and percentiles across all members.

Parameters:

basic (bool) – if True, compute only quartile percentiles (25, 50, 75).

Returns:

DataFrame with datetime, sum, mean, std, min, max and percentiles

Return type:

pandas.DataFrame

get_reducer_series(name)

Get a reducer as a series object of the ensemble base type.

Parameters:

name (str) – reducer name: mean, median, min, max or a percentile such as p90

Returns:

series holding the reducer values

Return type:

TimeSeries

_set_view_specs()

Set view specifications. Expected to increment superior methods.

_plot_series(axes, specs, extra=None, force_background=False)

Plot members in background style, with reducers and bands on top.

view(show=True, return_fig=False)

Get the visualization, with members in the background and reducers and bands on top.

Layouts, set by view_specs["layout"]:

Layout	Panels
full	Gantt chart, overlap and prevalence.
simple	Gantt chart and overlap.
default	Same as full.
stacked	A panel for each entry of panels, with histograms and CDFs, on a shared time axis.
stacked-simple	A panel for each entry of panels, on a shared time axis.
series	All series overlaid, with histograms and CDFs.
series-simple	All series overlaid.

View specs, set by view_specs[key] = value before the call:

Key	Default	Description
layout	"series"	Name of the layout. See the table of layouts.
style	"wien"	Name of the plot style. See plans.viewer.set_style().
title	auto	Title of the figure.
gantt	auto	Title of the Gantt chart.
over	auto	Title of the overlap panel.
prev	auto	Title of the prevalence panel.
xlabel	auto	Label of the time axis.
ylabel_over	"%"	Label of the y axis of the overlap panel.
xlabel_prev	"%"	Label of the x axis of the prevalence panel.
usealias	False	Use aliases instead of names in labels.
n_dates	5	Number of date ticks, evenly spaced in time. None chooses them automatically.
format_dates	"%Y-%m-%d"	Format of the date labels.
xtick_rotation	0	Rotation of the date labels in the full and simple layouts.
color_over	"tab:blue"	Color of the overlap panel.
alpha_over	0.4	Opacity of the fill of the overlap panel.
color_prev	"tab:gray"	Color of the prevalence bars.
gantt_linewidth	6	Largest width of the Gantt lines. It shrinks to fit many series.
n_series_max	10	Above this many series, labels are hidden and series lines go to the background.
xmin	None	Start of the time axis. None is the first date of all series, with pad_x.
xmax	None	End of the time axis. None is the last date of all series, with pad_x.
ymin	None	Bottom of the overlap panel. None is automatic.
ymax	None	Top of the overlap panel. None is automatic.
pad_x	0.05	Share of the time span added on each side of the time axis not set by xmin or xmax.
folder	auto	Folder of the saved figure.
filename	auto	Name of the saved figure, without extension. None is the name of the collection.
suff	""	Suffix of the saved figure, if filename is None.
dpi	300	Resolution of the saved figure.
fig_format	"jpg"	Format of the saved figure.
series	"Series"	Title of the series panel, in the series layouts.
subtitle_hist	"Histogram"	Title of the histograms.
subtitle_cdf	"CDF"	Title of the CDFs.
ylabel	auto	Label of the y axis, in the series layouts. None comes from the variable.
range	None	Common y range, in the series layouts. None is set from the data.
cmap_series	"tab10"	Color map of the series. In series layouts, None uses the color of each series.
linewidth	0.8	Width of the series lines, in the series layouts.
alpha_hist	0.4	Opacity of overlaid histograms.
histtype	"bar"	Type of overlaid histograms. "step" draws outlines only.
bins	30	Number of common bins of overlaid histograms.
plot_mean	True	Show mean lines on overlaid histograms and CDFs.
legend	True	Show the legend of overlaid series.
highlight	None	Names of the series drawn in color, in the series layouts.
plot_background	True	Show the background lines on the series panel.
color_background	"silver"	Color of the background series.
linewidth_background	0.5	Width of the background lines.
alpha_background	0.6	Opacity of the background lines.
alpha_hist_background	0.1	Opacity of the background histograms.
panels	None	Names of the series in each panel, as a list of lists. None is one series per panel.
panel_heights	None	Relative heights of the panels, like [3, 1]. None is equal.
reducers	["mean"]	Names of the reducers drawn in color, such as mean. None hides them.
bands	[[5, 95]]	Percentile bands, as [low, high] pairs. None hides them.
color_band	"#8db4dc"	Color of the bands.
alpha_band	0.6	Opacity of the bands.

Parameters:

• show (bool) – option for showing instead of saving

• return_fig (bool) – option for returning the figure object

Returns:

figure object if return_fig is True, else None

Return type:

matplotlib.figure.Figure or None

static _nanrange(x, axis=None)

Range (max - min) ignoring missing values.

static _get_percentile_name(p)

Get the percentile name, zero padded (e.g., p05, p50, p2.5).

class plans.datasets.core.SeasonalEnsemble(name='mySeasonalEnsemble', base_object=None)

Bases: TimeSeriesEnsemble

Ensemble of the years of a single series, for seasonal plots.

Each year becomes a member, with dates moved onto one reference year, so reducers, bands and highlight work across years. Works with any time step that repeats each year: sub-daily, daily or monthly.

Note

Dates in members and reducers are placeholders. The reference year is a leap year, so 29 Feb has its own step, filled only by leap years. To join reducers by calendar date, use the month and day, as in df["datetime"].dt.strftime("%m-%d").

MONTHS = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec']

__init__(name='mySeasonalEnsemble', base_object=None)

Initialize the Collection object.

Parameters:

• base_object (MbaE) – MbaE-based object for collection

• name (str) – unique object name

• alias (str) – unique object alias.

set_series(ts, year_start=1)

Split a series into one member per year, replacing current members.

Members are named by year, like 2021. When the year does not start in January (e.g., a water year), names hold both years, like 2020-21. Incomplete years are kept, and count in the reducers.

Parameters:

• ts (TimeSeries) – series to split

• year_start (int) – first month of the year, from 1 to 12. Default is 1.

Returns:

None

Return type:

None

_set_view_specs()

Set view specifications. Expected to increment superior methods.

_get_reference_start()

Get the first date of the reference year, chosen so it holds 29 Feb.

_plot_series(axes, specs, extra=None, force_background=False)

Plot as in the ensemble, with the x axis of the reference year.

_set_xaxis(ax, mode)

Set the ticks and labels of the x axis.

view(show=True, return_fig=False)

Get the visualization, with the years of the series on the same calendar.

Layouts, set by view_specs["layout"]:

Layout	Panels
full	Gantt chart, overlap and prevalence.
simple	Gantt chart and overlap.
default	Same as full.
stacked	A panel for each entry of panels, with histograms and CDFs, on a shared time axis.
stacked-simple	A panel for each entry of panels, on a shared time axis.
series	All series overlaid, with histograms and CDFs.
series-simple	All series overlaid.

View specs, set by view_specs[key] = value before the call:

Key	Default	Description
layout	"series"	Name of the layout. See the table of layouts.
style	"wien"	Name of the plot style. See plans.viewer.set_style().
title	auto	Title of the figure.
gantt	auto	Title of the Gantt chart.
over	auto	Title of the overlap panel.
prev	auto	Title of the prevalence panel.
xlabel	auto	Label of the time axis.
ylabel_over	"%"	Label of the y axis of the overlap panel.
xlabel_prev	"%"	Label of the x axis of the prevalence panel.
usealias	False	Use aliases instead of names in labels.
n_dates	5	Number of date ticks, evenly spaced in time. None chooses them automatically.
format_dates	"%Y-%m-%d"	Format of the date labels.
xtick_rotation	0	Rotation of the date labels in the full and simple layouts.
color_over	"tab:blue"	Color of the overlap panel.
alpha_over	0.4	Opacity of the fill of the overlap panel.
color_prev	"tab:gray"	Color of the prevalence bars.
gantt_linewidth	6	Largest width of the Gantt lines. It shrinks to fit many series.
n_series_max	10	Above this many series, labels are hidden and series lines go to the background.
xmin	None	Start of the time axis. None is the first date of all series, with pad_x.
xmax	None	End of the time axis. None is the last date of all series, with pad_x.
ymin	None	Bottom of the overlap panel. None is automatic.
ymax	None	Top of the overlap panel. None is automatic.
pad_x	0	Share of the time span added on each side of the time axis not set by xmin or xmax.
folder	auto	Folder of the saved figure.
filename	auto	Name of the saved figure, without extension. None is the name of the collection.
suff	""	Suffix of the saved figure, if filename is None.
dpi	300	Resolution of the saved figure.
fig_format	"jpg"	Format of the saved figure.
series	"Series"	Title of the series panel, in the series layouts.
subtitle_hist	"Histogram"	Title of the histograms.
subtitle_cdf	"CDF"	Title of the CDFs.
ylabel	auto	Label of the y axis, in the series layouts. None comes from the variable.
range	None	Common y range, in the series layouts. None is set from the data.
cmap_series	"tab10"	Color map of the series. In series layouts, None uses the color of each series.
linewidth	0.8	Width of the series lines, in the series layouts.
alpha_hist	0.4	Opacity of overlaid histograms.
histtype	"bar"	Type of overlaid histograms. "step" draws outlines only.
bins	30	Number of common bins of overlaid histograms.
plot_mean	True	Show mean lines on overlaid histograms and CDFs.
legend	True	Show the legend of overlaid series.
highlight	None	Names of the series drawn in color, in the series layouts.
plot_background	True	Show the background lines on the series panel.
color_background	"silver"	Color of the background series.
linewidth_background	0.5	Width of the background lines.
alpha_background	0.6	Opacity of the background lines.
alpha_hist_background	0.1	Opacity of the background histograms.
panels	None	Names of the series in each panel, as a list of lists. None is one series per panel.
panel_heights	None	Relative heights of the panels, like [3, 1]. None is equal.
reducers	["mean"]	Names of the reducers drawn in color, such as mean. None hides them.
bands	[[5, 95]]	Percentile bands, as [low, high] pairs. None hides them.
color_band	"#8db4dc"	Color of the bands.
alpha_band	0.6	Opacity of the bands.
xaxis	"month-alias"	Labels of the x axis: "days", "month", "month-letter" or "month-alias".

Parameters:

• show (bool) – option for showing instead of saving

• return_fig (bool) – option for returning the figure object

Returns:

figure object if return_fig is True, else None

Return type:

matplotlib.figure.Figure or None

static _align_steps(dates)

Check that time steps repeat each year, moving monthly steps to the first day of the month.

Parameters:

dates (pandas.Series) – dates of the series

Returns:

dates with repeating steps

Return type:

pandas.Series

class plans.datasets.core.Raster(name='myRasterMap', alias='Rst', dtype='float32')

Bases: GeoUnivar

The basic Raster map dataset. A GeoUnivar with a grid as data, in place of a table with geometries.

N_DRAW = 5000

var_min

Attribute computed from the data on first use, and kept until it is set to None.

var_max

Attribute computed from the data on first use, and kept until it is set to None.

__init__(name='myRasterMap', alias='Rst', dtype='float32')

property data

The grid. A new grid drops the statistics of the previous one.

_reset_stats()

Drop the statistics, to be computed again on next use.

Returns:

None

Return type:

None

_get_values()

Get the values of the grid, flat and cleared.

Returns:

vector of values

Return type:

numpy.ndarray

_get_var_min()

_get_var_max()

_thin(data)

Get evenly spaced records of a sequence, since a screen shows no more than a few thousand. Panels of statistics and the histogram still use all data.

Parameters:

data (numpy.ndarray or pandas.DataFrame) – vector or dataframe, with one record for each value

Returns:

thinned sequence

Return type:

numpy.ndarray or pandas.DataFrame

_set_fields()

Set fields names. Expected to increment superior methods.

get_metadata()

Get a dictionary with object metadata. Expected to increment superior methods.

Note

Metadata does not necessarily inclue all object attributes.

Returns:

dictionary with all metadata

Return type:

dict

get_bbox()

Get the Bounding Box of the map.

Returns:

Dictionary of xmin, xmax, ymin, and ymax. - “xmin” (float): Minimum x-coordinate. - “xmax” (float): Maximum x-coordinate. - “ymin” (float): Minimum y-coordinate. - “ymax” (float): Maximum y-coordinate.

Return type:

dict

get_extent()

Get the Extent of the map. See get_bbox.

Returns:

list of [xmin, xmax, ymin, ymax]

Return type:

list

get_crs_info()

Get the EPSG code and the units of the cells, from the CRS or the projection file. Without the database of PROJ, a CRS may lose its EPSG code.

Returns:

dictionary of epsg and units, "m" or "deg.". None if unknown.

Return type:

dict

get_metadata_lines()

Get the lines of text of the metadata, for the annotations of the view.

Returns:

lines of text

Return type:

list

get_grid_datapoints(drop_nan=False)

Get flat and cleared grid data points (x, y, and z).

Notes This function extracts coordinates (x, y, and z) from the raster grid. The x and y coordinates are determined based on the grid cell center positions. If drop_nan is True, nan values are ignored in the resulting DataFrame. The resulting DataFrame includes columns for x, y, z, i, and j coordinates.

Parameters:

drop_nan (bool) – Option to ignore nan values.

Returns:

DataFrame of x, y, and z fields.

Return type:

pandas.DataFrame`` or None. If the grid is None, returns None.

get_grid_data()

Get flat and cleared grid values.

Returns:

1D vector of cleared sample.

Return type:

numpy.ndarray` or None. If the grid is None, returns None.

Notes

• This function extracts and flattens the grid, removing any masked or NaN values.

• For integer grids, the masked values are ignored.

• For floating-point grids, both masked and NaN values are ignored.

get_stats(inplace=False)

Get basic statistics from flat and cleared grid.

Returns:

Dict of basic statistics. If the grid is None, returns None.

Return type:

dict or None

get_stats_df()

Get pandas.DataFrame statistics from flat and cleared grid.

Returns:

DataFrame of basic statistics. If the grid is None, returns None.

Return type:

pandas.DataFrame or None

get_aoi(by_value_lo, by_value_hi)

Get the AOI map from an interval of values (values are expected to exist in the raster).

Parameters:

• by_value_lo (float) – Number for the lower bound (inclusive).

• by_value_hi (float) – Number for the upper bound (inclusive).

Returns:

AOI map.

Return type:

AOI` object

Notes

• This function creates an AOI (Area of Interest) map based on a specified value range.

• The AOI map is constructed as a binary grid where values within the specified range are set to 1, and others to 0.

update()

Refresh all mutable attributes based on data (includins paths). Expected to be incremented downstream.

set_data(grid)

Set the data grid for the raster object. This function allows setting the data grid for the raster object. The incoming grid should be a NumPy array.

Parameters:

grid (numpy.ndarray) – The data grid to be set for the raster.

Notes

• The function overwrites the existing data grid in the raster object with the incoming grid, ensuring that the data type matches the raster’s dtype.

• Nodata values are masked after setting the grid.

set_array(array)

Set the data grid for the raster object. See set_data().

Parameters:

array (numpy.ndarray) – The data grid to be set for the raster.

Returns:

None

Return type:

None

set_raster_metadata(metadata)

Set metadata for the raster object based on incoming metadata. This function allows setting metadata for the raster object from an incoming metadata dictionary. The metadata should include information such as the number of columns, number of rows, corner coordinates, cell size, and nodata value.

Parameters:

metadata (dict) – A dictionary containing metadata for the raster.

load_data(file_data, file_prj=None, id_band=1)

Load data and metadata from files to the Raster object.

Parameters:

• file_data (str) – The path to the raster file.

• file_prj (str) – The path to the ‘.prj’ projection file. If not provided, an attempt is made to use the same path and name as the .asc file with the ‘.prj’ extension.

• id_band (int) – Band id to read for GeoTIFF. Default value = 1

load_metadata(file_data, id_band=1)

Load only metadata from files to the raster object.

Parameters:

• file_data (str) – The path to the raster file.

• id_band (int) – Band id to read for GeoTIFF. Default value = 1

load_image(file_input, xxl=False)

Load data from an image ‘.tif’ raster files.

Parameters:

• file_input (str) – The file path of the ‘.tif’ raster file.

• xxl (bool) – option flag for very large images

Notes

• The function uses the Pillow (PIL) library to open the ‘.tif’ file and converts it to a NumPy array.

• Metadata may need to be provided separately, as this function focuses on loading raster data.

• The loaded data grid is set using the set_grid method of the raster object.

load_tif(file_input, id_band=1)

Load data and metadata from .tif raster file.

Parameters:

file_input (str) – The file path to the .tif raster file.

load_tif_metadata(file_input, id_band=1)

Load only metadata from .tif raster file.

Parameters:

file_input (str) – The file path to the .tif raster file.

load_asc(file_input)

Load data and metadata from .asc raster file.

Parameters:

file_input (str) – The file path to the .asc raster file.

load_asc_metadata(file_input)

Load only metadata from .asc raster files.

Parameters:

file_input (str) – The file path to the .asc raster file.

load_prj(file_input)

Load ‘.prj’ auxiliary file to the ‘prj’ attribute.

Parameters:

file_input (str) – The file path to the ‘.prj’ auxiliary file.

copy_structure(raster_ref, n_nodatavalue=None)

Copy structure (metadata and prj) from another raster object.

Parameters:

• raster_ref (datasets.Raster) – The reference incoming raster object from which to copy.

• n_nodatavalue (float) – The new nodata value for different raster objects. If None, the nodata value remains unchanged.

export(folder, filename=None, mode='tif')

Exports the raster to a specified file format and location.

Parameters:

• folder (str) – The destination folder for the exported file.

• filename (str) – [optional] The name of the output file. If None, the original raster name is used.

• mode (str) – The export format, either “tif” (default) or “asc”. Default value = “tif”

Returns:

file path to output file

Return type:

str

export_tif(folder, filename=None)

Export an .tif raster file..

Parameters:

• folder (str) – The directory path to export the raster file.

• filename (str) – The name of the exported file without extension. If None, the name of the raster object is used.

Returns:

The full file name (path and extension) of the exported raster file.

Return type:

str

export_asc(folder, filename=None)

Export an .asc raster file.

Parameters:

• folder (str) – The directory path to export the raster file.

• filename (str) – The name of the exported file without extension. If None, the name of the raster object is used.

Returns:

The full file name (path and extension) of the exported raster file.

Return type:

str

export_prj(folder, filename=None)

Export a ‘.prj’ file. This function exports the coordinate system information to a ‘.prj’ file in the specified folder.

Parameters:

• folder (str) – The directory path to export the ‘.prj’ file.

• filename (str) – The name of the exported file without extension. If None, the name of the raster object is used.

Returns:

The full file name (path and extension) of the exported ‘.prj’ file, or None if no coordinate system information is available.

Return type:

str or None

reset_nodata(new_nodata, ensure=True)

Resets the no-data value in the raster metadata and updates the data mask accordingly.

This method first ensures the current no-data values are masked, then updates the NODATA_value in the raster metadata, and finally re-applies the mask based on the new no-data value.

Parameters:

• new_nodata (int or float) – The new no-data value to set.

• ensure (bool) – If True, ensures the current no-data values are masked before resetting. Default value = True

mask_nodata()

Mask grid cells as NaN where data is NODATA.

Notes

• The function masks grid cells as NaN where the data is equal to the specified NODATA value.

• If NODATA value is not set, no masking is performed.

insert_nodata()

Set grid cells as NODATA where data is NaN using the static method.

load_aoi_mask(file_raster, inplace=False)

Loads an Area of Interest (AOI) mask from a raster file and applies it to the current object’s data.

Parameters:

• file_raster (str) – The file path to the AOI raster.

• inplace (bool) – If True, the mask is applied in-place to the current object’s data. Default value = False

apply_aoi_mask(grid_aoi, inplace=False)

Apply AOI (area of interest) mask to the raster map. This function applies an AOI (area of interest) mask to the raster map, replacing values outside the AOI with the NODATA value.

Notes The function replaces values outside the AOI (where grid_aoi is 0) with the NODATA value. If NODATA value is not set, no replacement is performed. If inplace is True, the main grid is modified. If False, a backup of the grid is created before modification. This function is useful for focusing analysis or visualization on a specific area within the raster map.

Parameters:

• grid_aoi (numpy.ndarray) – Map of AOI (masked array or pseudo-boolean). Expected to have the same grid shape as the raster.

• inplace (bool) – If True, overwrite the main grid with the masked values. If False, create a backup and modify a copy of the grid. Default is False.

release_aoi_mask()

Release AOI mask from the main grid. Backup grid is restored.

This function releases the AOI (area of interest) mask from the main grid, restoring the original values from the backup grid.

Notes If an AOI mask has been applied, this function restores the original values to the main grid from the backup grid. If no AOI mask has been applied, the function has no effect. After releasing the AOI mask, the backup grid is set to None, and the raster object is no longer considered to have an AOI mask.

rebase_grid(base_raster, inplace=False, method='linear_model')

Rebase the grid of a raster. This function creates a new grid based on a provided reference raster. Both rasters are expected to be in the same coordinate system and have overlapping bounding boxes.

Parameters:

• base_raster (datasets.Raster) – The reference raster used for rebase. It should be in the same coordinate system and have overlapping bounding boxes.

• inplace (bool) – If True, the rebase operation will be performed in-place, and the original raster’s grid will be modified. If False, a new rebased grid will be returned, and the original data will remain unchanged. Default is False.

• method (str) – Interpolation method for rebasing the grid. Options include “linear_model,” “nearest,” and “cubic.” Default is “linear_model.”

Returns:

If inplace is False, a new rebased grid as a NumPy array. If inplace is True, returns None, and the original raster’s grid is modified in-place.

Return type:

numpy.ndarray` or None

Notes

• The rebase operation involves interpolating the values of the original grid to align with the reference raster’s grid.

• The method parameter specifies the interpolation method and can be “linear_model,” “nearest,” or “cubic.”

• The rebase assumes that both rasters are in the same coordinate system and have overlapping bounding boxes.

cut_edges(upper, lower, inplace=False)

Cutoff upper and lower values of the raster grid.

Parameters:

• upper (float or int) – The upper value for the cutoff.

• lower (float or int) – The lower value for the cutoff.

• inplace (bool) – If True, modify the main grid in-place. If False, create a processed copy of the grid. Default is False.

Returns:

The processed grid if inplace is False. If inplace is True, returns None.

Return type:

Union[None, np.ndarray]

Notes Values in the raster grid below the lower value are set to the lower value. Values in the raster grid above the upper value are set to the upper value. If inplace is False, a processed copy of the grid is returned, leaving the original grid unchanged. This function is useful for clipping extreme values in the raster grid.

_set_view_specs()

Set default view specs.

_plot(fig, gs, specs)

Plot the panels of the family, with the raster on the map panel.

Parameters:

• fig (matplotlib.figure.Figure) – The matplotlib figure object.

• gs (matplotlib.gridspec.GridSpec) – The matplotlib gridspec object for arranging subplots.

• specs (dict) – A dictionary containing plotting specifications and options.

Returns:

The modified matplotlib figure object with the plots.

Return type:

matplotlib.figure.Figure

_get_annotation_columns()

Get the columns of annotations, with the metadata next to the statistics.

Returns:

list of columns, each one a list of lines of text

Return type:

list

_draw_map(ax, cmap, norm, specs)

Draw the grid on the map panel, in map coordinates.

Parameters:

• ax (matplotlib.axes.Axes) – axis to plot on

• cmap (matplotlib.colors.Colormap) – color map

• norm (matplotlib.colors.Normalize) – norm of the color scheme

• specs (dict) – plot specification dictionary

Returns:

None

Return type:

None

view(show=True, return_fig=False)

Get the visualization, with the raster on the map panel. All layouts and view specs of plans.datasets.analyst.GeoUnivar.view() are available, except for those of points. These are the differences:

Key	Default	Description
scheme_cmap	"continuous"	Color scheme. Classes are also available, such as "equal".
cmap	auto	Name of the color map, from the cmap attribute.
range	auto	Range of the y axis and of continuous colors. None is set from the data.
zoom_window	None	Part of the grid on the map, as a dictionary of i_min, i_max, j_min and j_max.
zorder_map	0	Drawing order of the raster, which stays below the grid of the map.
alpha	None	Opacity of the data panel. None sets it by the number of points.
run_id	None	Not in use.

The data and CDF panels draw evenly spaced records, up to about N_DRAW of them. The histogram and the statistics use all data.

Parameters:

• show (bool) – option for showing instead of saving

• return_fig (bool) – option for returning the figure object

Returns:

figure object if return_fig is True, else None

Return type:

matplotlib.figure.Figure or None

static read_tif_metadata(file_input, n_band=1)

Read raster metadata from a file.

Parameters:

• file_input (str) – Path to the input raster file.

• n_band (int) – [optional] Band number to read. Default value = 1

Returns:

Dictionary containing raster metadata.

Return type:

dict

static read_tif(file_input, dtype='float', id_band=1, metadata=True)

Read a raster band from a file.

Parameters:

• file_input (str) – Path to the input raster file.

• dtype (str) – Data type for the output grid. Default value = “float”

• id_band (int) – Band id to read. Default value = 1

• metadata (bool) – Whether to include metadata in the output dictionary. Default value = True

Returns:

Dictionary containing the raster grid and optionally its metadata.

Return type:

dict

static write_tif(grid_output, dc_metadata, file_output, dtype='float32', n_bands=1, id_band=1)

Write a raster band to a file.

Parameters:

• grid_output (numpy.ndarray) – The grid data to write.

• dc_metadata (dict) – Dictionary containing the raster metadata.

• file_output (str) – Path to the output raster file.

• dtype (str) – Data type alias for the output grid (numpy standard). Default value = “float32”

• n_bands (int) – Number of bands in the output raster. Default value = 1

• id_band (int) – Band ID to write the data to. Default value = 1

Returns:

Path to the output raster file. (echo)

Return type:

str

static read_asc_metadata(file_input)

Reads metadata from an ASCII raster file.

Parameters:

file_input (str) – Path to the input ASCII file.

Returns:

A dictionary containing the metadata.

Return type:

dict

static read_asc(file_input, dtype='float32', metadata=True)

Reads an ASCII raster file into a dictionary.

Parameters:

• file_input (str) – Path to the input ASCII file.

• dtype (str) – Data type for the raster data. Default value = “float32”

• metadata (bool) – Whether to read and include metadata from the ASCII file. Default value = True

Returns:

A dictionary containing the raster data and optionally its metadata.

Return type:

dict

static write_asc(grid_output, dc_metadata, file_output, dtype='float32')

Writes a raster grid and its metadata to an ASCII file.

Parameters:

• grid_output (numpy.ndarray) – The raster data to write.

• dc_metadata (dict) – Dictionary containing the metadata for the ASCII file.

• file_output (str) – Path for the output ASCII file.

• dtype (str) – Data type for the raster data in the output file. Default value = “float32”

Returns:

The path of the generated output ASCII file.

Return type:

str

static apply_nodata(grid_input, nodatavalue=None)

Applies a nodata value to the input grid.

Parameters:

• grid_input (numpy.ndarray) – The input grid.

• nodatavalue (int or float) – [optional] The nodata value to apply. Default value = None

Returns:

The grid with the nodata value applied.

Return type:

numpy.ndarray

class plans.datasets.core.SciRaster(name='MySciRaster', alias=None)

Bases: Raster

Scientific (float32) raster dataset with a configurable nodata value and display range.

__init__(name='MySciRaster', alias=None)

_set_view_specs()

Set default view specs.

_overwrite_nodata()

set_raster_metadata(metadata)

Set metadata for the raster object based on incoming metadata. This function allows setting metadata for the raster object from an incoming metadata dictionary. The metadata should include information such as the number of columns, number of rows, corner coordinates, cell size, and nodata value.

Parameters:

metadata (dict) – A dictionary containing metadata for the raster.

class plans.datasets.core.QualiRaster(name='QualiMap', dtype='uint8')

Bases: Raster

Basic qualitative raster map dataset. todo [docstring] – examples

__init__(name='QualiMap', dtype='uint8')

_set_fields()

Set fields names. Expected to increment superior methods.

_overwrite_nodata()

get_metadata()

Get all metadata from base_object

Returns:

metadata

Return type:

dict

get_areas(inplace=False)

Get areas in map of each category in table.

Parameters:

inplace (bool, defaults to False) – option to merge data with raster table

Returns:

areas dataframe

Return type:

pandas.DataFrame

get_normality(clevel=0.95)

Not available, since category IDs have no distribution.

Parameters:

clevel (float) – confidence level

Raises:

ValueError – always

get_cdf_gumbel()

Not available, since category IDs have no maxima.

Raises:

ValueError – always

get_zonal_stats(raster_sample, merge=False, skip_count=False)

Get zonal stats from other raster map to sample.

Parameters:

• raster_sample (datasets.Raster) – raster map to sample

• merge (bool) – option to merge data with raster table, defaults to False

• skip_count (bool) – set True to skip count, defaults to False

Returns:

dataframe of zonal stats

Return type:

pandas.DataFrame

get_aoi(by_value_id=None)

Get the AOI map from a specific value id (value is expected to exist in the raster) :param by_value_id: category id value :type by_value_id: int :return: AOI map :rtype: AOI` object

set_random_colors()

Set random colors to attribute table.

set_raster_metadata(metadata)

Set metadata for the raster object based on incoming metadata. This function allows setting metadata for the raster object from an incoming metadata dictionary. The metadata should include information such as the number of columns, number of rows, corner coordinates, cell size, and nodata value.

Parameters:

metadata (dict) – A dictionary containing metadata for the raster.

set_table(dataframe)

Set attributes dataframe from incoming pandas.DataFrame.

Parameters:

dataframe (pandas.DataFrame) – incoming pandas dataframe

load_data(file_data, file_table=None, file_prj=None, id_band=1)

Load data from files to the raster object.

Parameters:

• file_data (str) – The path to the raster file.

• file_table (str) – path to table file

• file_prj (str) – The path to the ‘.prj’ projection file. If not provided, an attempt is made to use the same path and name as the .asc file with the ‘.prj’ extension.

• id_band (int) – Band id to read for GeoTIFF. Default value = 1

load_table(file_table)

Load attributes dataframe from table file.

Parameters:

file_table (str) – path to to file

export(folder, filename=None)

Export raster sample

Parameters:

• folder (str) – path to folder,

• filename (str) – string of file without extension, defaults to None

export_table(folder, filename=None)

Export table file.

Parameters:

• folder (str) – path to folde

• filename (str) – string of file without extension

Returns:

full file name (path to and extension) string

Return type:

str

clear_table()

Clear the unfound values in the map from the table.

rebase_grid(base_raster, inplace=False)

This method calls the rebase_grid method of the superclass to perform the grid rebasement using the “nearest” interpolation method.

Parameters:

• base_raster (Raster) – The raster object to rebase against.

• inplace (bool) – If True, the operation is performed in-place. Default value = False

Returns:

The rebased object.

Return type:

Raster

reclassify(dict_ids, df_new_table, talk=False)

Reclassify QualiRaster Ids in grid and table

Parameters:

• dict_ids (dict) – dictionary to map from “Old_Id” to “New_id”

• df_new_table (pandas.DataFrame) – new table for QualiRaster

• talk (bool) – option for printing messages

apply_values(table_field)

_plot(fig, gs, specs)

Plot the map panel of the family, with the areas of each class in place of the panels of statistics.

Parameters:

• fig (matplotlib.figure.Figure) – The matplotlib figure object.

• gs (matplotlib.gridspec.GridSpec) – The matplotlib gridspec object for arranging subplots.

• specs (dict) – A dictionary containing plotting specifications and options.

Returns:

The modified matplotlib figure object with the plots.

Return type:

matplotlib.figure.Figure

_get_annotation_columns()

Get the columns of annotations. Here, only the metadata.

Returns:

list of columns, each one a list of lines of text

Return type:

list

_get_cmap_norm(specs)

Get the color map and the norm of the map panel, one color for each ID.

Parameters:

specs (dict) – plot specification dictionary

Returns:

color map and norm

Return type:

tuple

_set_view_specs()

Get default view specs

view(show=True, return_fig=False)

Get the visualization, with the map and the areas of each class. All layouts of plans.datasets.analyst.GeoUnivar.view() and the keys of the map panel are available. These are the differences:

Key	Default	Description
cmap	auto	Colors of the classes, from the table.
range	auto	Range of the IDs, from the table.
cbar_map	False	Show the color bar of the map. The areas take its role.
color	"tab:gray"	Color of the bars of areas.
use_alias	False	Label the bars with the alias of the classes.
cutoff	True	Hide classes without area.
max_classes	15	Number of classes shown. Others are aggregated.
subtitle_areas	"Aereal ratios"	Title of the panel of areas. None hides it.
area_unit	"km2"	Unit of the total area: "m2", "ha" or "km2".
total_area	"Total area"	Label of the total area.

Parameters:

• show (bool) – option for showing instead of saving

• return_fig (bool) – option for returning the figure object

Returns:

figure object if return_fig is True, else None

Return type:

matplotlib.figure.Figure or None

class plans.datasets.core.QualiHard(name='qualihard')

Bases: QualiRaster

A Quali-Hard is a hard-coded qualitative map (that is, the table is pre-set)

__init__(name='qualihard')

get_table()

Retrieves a DataFrame representing a classification table.

Returns:

A DataFrame with classification data.

Return type:

pandas.DataFrame

load_data(file_data, file_prj=None, id_band=1, file_table=None)

Load data from file to the raster object.

Parameters:

• file_data (str) – The path to the raster file.

• file_prj (str) – The path to the ‘.prj’ projection file. If not provided, an attempt is made to use the same path and name as the .asc file with the ‘.prj’ extension.

• id_band (int) – Band id to read for GeoTIFF. Default value = 1

class plans.datasets.core.Zones(name='ZonesMap')

Bases: QualiRaster

Zones map dataset is a QualiRaster designed to handle large volume of positive integer numbers (ids of zones)

__init__(name='ZonesMap')

compute_table()

Computes an internal table summarizing unique values in the spatial data, assigns aliases, names, and sets up viewing specifications.

set_data(grid)

Sets the spatial data for the object and recomputes the internal table.

Parameters:

grid (numpy.ndarray) – The input grid data.

load_data(asc_file, prj_file)

Load data from files to raster

Parameters:

• asc_file (str) – path to raster file

• prj_file (str) – path to projection file

get_aoi(zone_id)

Get the AOI map from a zone id

Parameters:

zone_id (int) – number of zone ID

Returns:

AOI map

Return type:

AOI` object

view(show=True, folder='./output', filename=None, specs=None, dpi=150, fig_format='jpg')

Plot a basic pannel of raster map.

Parameters:

• show (bool) – boolean to show plot instead of saving, defaults to False

• folder (str) – path to output folder, defaults to ./output

• filename (str) – name of file, defaults to None

• specs (dict) – specifications dictionary, defaults to None

• dpi (int) – image resolution, defaults to 96

• fig_format (str) – image fig_format (ex: png or jpg). Default jpg

class plans.datasets.core.RasterCollection(name='myRasterCollection')

Bases: Collection

The raster collection base dataset. This data strucute is designed for holding and comparing Raster` objects.

__init__(name='myRasterCollection')

Deploy the raster collection data structure.

Parameters:

name (str) – name of raster collection

_set_fields()

Set fields names. Expected to increment superior methods.

load_data(name, file_data, file_prj=None, varname=None, varalias=None, units=None, datetime=None, dtype='float32', skip_grid=False)

Load a Raster` base_object from a raster file.

Parameters:

• name (str) – Raster.name` name attribute

• file_data (str) – path to raster file

• varname (str) – Raster.varname` variable name attribute, defaults to None

• varalias (str) – Raster.varalias` variable alias attribute, defaults to None

• units (str) – Raster.units` units attribute, defaults to None

• datetime (str) – Raster.date` date attribute, defaults to None

• skip_grid (bool) – option for loading only the metadata

load_folder(folder, name_pattern, is_series=False, file_table=None, verbose=False, file_format='tif', logger=None)

Load all rasters from a folder by following a name pattern.

Parameters:

• folder (str) – path to folder

• name_pattern (str) – name pattern. example map_*

• is_series (bool) – flag to handle datetime

• file_table (str or Path) – file path to qualiraster table

• verbose (bool) – option for printing messages

• file_format (str) – file extension.

is_same_grid()

Checks if all datasets in the catalog have the same grid dimensions (number of columns and rows).

Returns:

True if all datasets have the same grid dimensions, False otherwise.

Return type:

bool

reduce(reducer_func, reduction_name, extra_arg=None, skip_nan=False, talk=False)

This method reduces the collection by applying a numpy broadcasting function (example: np.mean)

Parameters:

• reducer_func (numpy function) – reducer numpy function (example: np.mean)

• reduction_name (str) – name for the output raster

• extra_arg (any) – extra argument for function (example: np.percentiles) - Default: None

• skip_nan (bool) – Option for skipping NaN values in map

• talk (bool) – option for printing messages

Returns:

raster object based on the first object found in the collection

Return type:

Raster

to_mean(skip_nan=False, talk=False)

Reduce Collection to the Mean raster

Parameters:

• skip_nan (bool) – Option for skipping NaN values in map

• talk (bool) – option for printing messages

Returns:

raster object based on the first object found in the collection

Return type:

Raster

to_sd(skip_nan=False, talk=False)

Reduce Collection to the Standard Deviation raster

Parameters:

• skip_nan (bool) – Option for skipping NaN values in map

• talk (bool) – option for printing messages

Returns:

raster object based on the first object found in the collection

Return type:

Raster

to_min(skip_nan=False, talk=False)

Reduce Collection to the Min raster

Parameters:

• skip_nan (bool) – Option for skipping NaN values in map

• talk (bool) – option for printing messages

Returns:

raster object based on the first object found in the collection

Return type:

Raster

to_max(skip_nan=False, talk=False)

Reduce Collection to the Max raster

Parameters:

• skip_nan (bool) – Option for skipping NaN values in map

• talk (bool) – option for printing messages

Returns:

raster object based on the first object found in the collection

Return type:

Raster

to_sum(skip_nan=False, talk=False)

Reduce Collection to the Sum raster

Parameters:

• skip_nan (bool) – Option for skipping NaN values in map

• talk (bool) – option for printing messages

Returns:

raster object based on the first object found in the collection

Return type:

Raster

to_percentile(percentile, skip_nan=False, talk=False)

Reduce Collection to the Nth Percentile raster

Parameters:

• percentile (float) – Nth percentile (from 0 to 100)

• skip_nan (bool) – Option for skipping NaN values in map

• talk (bool) – option for printing messages

Returns:

raster object based on the first object found in the collection

Return type:

Raster

to_median(skip_nan=False, talk=False)

Reduce Collection to the Median raster

Parameters:

• skip_nan (bool) – Option for skipping NaN values in map

• talk (bool) – option for printing messages

Returns:

raster object based on the first object found in the collection

Return type:

Raster

get_collection_stats()

Get basic statistics from collection.

Returns:

statistics sample

Return type:

pandas.DataFrame

get_views(show=False, folder='./output', dpi=300, fig_format='jpg', talk=False, specs=None, suffix=None)

Plot all basic pannel of raster maps in collection.

Parameters:

• show (bool) – boolean to show plot instead of saving,

• folder (str) – path to output folder, defaults to ./output

• dpi (int) – image resolution, defaults to 96

• fig_format (str) – image fig_format (ex: png or jpg). Default jpg

• talk (bool) – option for print messages

view_bboxes(colors=None, datapoints=False, show=True, folder='./output', filename=None, dpi=150, fig_format='jpg')

View Bounding Boxes of Raster collection

Parameters:

• colors (list) – list of colors for plotting. expected to be the same runsize of catalog

• datapoints (bool) – option to plot datapoints as well, defaults to False

• show (bool) – option to show plot instead of saving, defaults to False

• folder (str) – path to output folder, defaults to ./output

• filename (str) – name of file, defaults to None

• dpi (int) – image resolution, defaults to 96

• fig_format (str) – image fig_format (ex: png or jpg). Default jpg

Return type:

none

get_catalog(mode='full')

Retrieves the data catalog in different modes.

Parameters:

mode (str) – The mode of the catalog to retrieve. Can be “full” for the complete catalog, “short” for a truncated version, or any other value to filter by a list ls. Default value = “full”

Returns:

The requested data catalog.

Return type:

pandas.DataFrame

class plans.datasets.core.QualiRasterCollection(name)

Bases: RasterCollection

The raster collection base dataset.

This data strucute is designed for holding and comparing QualiRaster` objects.

__init__(name)

Deploy Qualitative Raster Series

Parameters:

• name (str) – RasterSeries.name` name attribute

• varname (str) – Raster.varname` variable name attribute, defaults to None

• varalias (str) – Raster.varalias` variable alias attribute, defaults to None

load_data(name, file_data, file_table=None, prj_file=None)

Load a QualiRaster` from file.

Parameters:

• name (str) – Raster.name` name attribute

• file_data (str) – path to raster file.

• file_table (str) – path to table file

• prj_file (str) – path to projection file

class plans.datasets.core.RasterSeries(name, varname, varalias, units, dtype='float32')

Bases: RasterCollection

A RasterCollection` where datetime matters and all maps in collections are expected to be the same variable, same projection and same grid.

__init__(name, varname, varalias, units, dtype='float32')

Deploy RasterSeries

Parameters:

• name (str) – RasterSeries.name` name attribute

• varname (str) – Raster.varname` variable name attribute, defaults to None

• varalias (str) – Raster.varalias` variable alias attribute, defaults to None

• units (str) – Raster.units` units attribute, defaults to None

load_data(name, datetime, file_data, prj_file=None, dtype='float32', skip_grid=False)

Load a Raster` object from raster file.

Parameters:

• name (str) – Raster.name` name attribute

• datetime (str) – Raster.date` date attribute, defaults to None

• file_data (str) – path to raster file

• prj_file (str) – path to projection file

• skip_grid (bool) – option for loading only the metadata

load_folder(folder, name_pattern, file_table=None, verbose=False, file_format='tif', logger=None)

Load all rasters from a folder by following a name pattern.

Parameters:

• folder (str) – path to folder

• name_pattern (str) – name pattern. example map_*

• is_series (bool) – flag to handle datetime

• file_table (str or Path) – file path to qualiraster table

• verbose (bool) – option for printing messages

• file_format (str) – file extension.

apply_aoi_masks(grid_aoi, inplace=False)

Batch method to apply AOI mask over all maps in collection

Parameters:

• grid_aoi (numpy.ndarray) – aoi grid

• inplace (bool) – overwrite the main grid if True, defaults to False

release_aoi_masks()

Batch method to release the AOI mask over all maps in collection

rebase_grids(base_raster, talk=False)

Batch method for rebase all maps in collection

Parameters:

• base_raster (datasets.Raster) – base raster for rebasing

• talk (bool) – option for print messages

get_series_stats()

Get the raster series statistics

Returns:

dataframe of raster series statistics

Return type:

pandas.DataFrame

view_series_stats(statistic='mean', folder='./output', filename=None, specs=None, show=True, dpi=150, fig_format='jpg')

View raster series statistics

Parameters:

• statistic (str) – statistc to view. Default mean

• show (bool) – option to show plot instead of saving, defaults to False

• folder (str) – path to output folder, defaults to ./output

• filename (str) – name of file, defaults to None

• specs (dict) – specifications dictionary, defaults to None

• dpi (int) – image resolution, defaults to 96

• fig_format (str) – image fig_format (ex: png or jpg). Default jpg

class plans.datasets.core.QualiRasterSeries(name, varname, varalias, dtype='uint8')

Bases: RasterSeries

A RasterSeries where date matters and all maps in collections are expected to be QualiRaster` with the same variable, same projection and same grid.

__init__(name, varname, varalias, dtype='uint8')

Deploy Qualitative Raster Series

Parameters:

• name (str) – RasterSeries.name` name attribute

• varname (str) – Raster.varname variable name attribute, defaults to None

• varalias (str) – Raster.varalias variable alias attribute, defaults to None

update_table(clear=True)

Update series table (attributes)

Parameters:

clear (bool) – option for clear table from unfound values. default: True

append(raster)

Append a new object to the Collection.

Parameters:

new_object (object) – Object to append.

Important

The object is expected to have a .get_metadata() method that returns a dictionary with metadata keys and values.

load_data(name, datetime, file_data, prj_file=None, table_file=None)

Load a QualiRaster base_object from raster file.

Parameters:

• name (str) – Raster.name name attribute

• datetime (str) – Raster.date date attribute

• file_data (str) – path to raster file

• prj_file (str) – path to projection file

• table_file (str) – path to .txt table file

w_load_file(file_info)

Worker function to load a single file.

load_folder(folder, name_pattern, file_table, verbose=False, file_format='tif', logger=None)

Load all rasters from a folder by following a name pattern.

Parameters:

• folder (str) – path to folder

• name_pattern (str) – name pattern. example map_*

• is_series (bool) – flag to handle datetime

• file_table (str or Path) – file path to qualiraster table

• verbose (bool) – option for printing messages

• file_format (str) – file extension.

get_series_areas()

Get areas prevalance for all series

Returns:

dataframe of series areas

Return type:

pandas.DataFrame

static view_series_areas(df_table, df_areas, specs=None, show=True, export_areas=True, folder='./output', filename=None, dpi=300, fig_format='jpg')

View series areas

Parameters:

• specs (dict) – specifications dictionary, defaults to None

• show (bool) – option to show plot instead of saving, defaults to False

• folder (str) – path to output folder, defaults to ./output

• filename (str) – name of file, defaults to None

• dpi (int) – image resolution, defaults to 96

• fig_format (str) – image fig_format (ex: png or jpg). Default jpg