Plotting

DatasetPlot is the plotting helper returned by dataset.plot. It groups the built-in visual diagnostics for time-series inspection and seasonal analysis.

colombia_hydrodata.plot.DatasetPlot

__init__(dataset)

Create a plotting helper bound to a dataset.

Parameters:

Name	Type	Description	Default
dataset	Dataset	The dataset whose time-series data will be visualised.	required

time_series(column_name='value', **kwargs)

Plot a timestamp-versus-value line series for the dataset.

Uses the dataset timestamp column on the x-axis and the selected data column on the y-axis. When plotting the default value column, the trend series is included as an overlay if it exists.

Parameters:

Name	Type	Description	Default
column_name	str	Name of the dataset column to plot on the y-axis.	'value'
**kwargs	Any	Additional keyword arguments forwarded to :func:colombia_hydrodata.utils.plot.time_series.	{}

Returns:

Type	Description
Axes	The Matplotlib axes containing the plot.

stem_series(column_name='value', **kwargs)

Plot a stem chart for a dataset column against time.

Parameters:

Name	Type	Description	Default
column_name	str	Name of the dataset column to plot.	'value'
**kwargs	Any	Additional keyword arguments forwarded to :func:colombia_hydrodata.utils.plot.stem_series.	{}

Returns:

Type	Description
Axes	The Matplotlib axes containing the plot.

histogram(column_name='value', **kwargs)

Plot a histogram for one dataset column.

Parameters:

Name	Type	Description	Default
column_name	str	Name of the dataset column to summarise.	'value'
**kwargs	Any	Additional keyword arguments forwarded to :func:colombia_hydrodata.utils.plot.histogram.	{}

Returns:

Type	Description
Axes	The Matplotlib axes containing the histogram.

monthly_data_series(column_name='value', **kwargs)

Plot the selected series grouped by calendar month.

Parameters:

Name	Type	Description	Default
column_name	str	Name of the dataset column to plot.	'value'
**kwargs	Any	Additional keyword arguments forwarded to :func:colombia_hydrodata.utils.plot.month_series.	{}

Returns:

Type	Description
Axes	The Matplotlib axes containing the monthly plot.

annual_data_series(column_name='value', years=None, **kwargs)

Plot the annual cycle envelope and optional individual years.

Draws the day-of-year quantile bands for the selected column and, when requested, overlays one or more specific years as individual lines.

Parameters:

Name	Type	Description	Default
column_name	str	Name of the dataset column to plot.	'value'
years	Sequence[int] | None	Optional sequence of calendar years to overlay on top of the annual envelope.	None
**kwargs	Any	Additional keyword arguments forwarded to :func:colombia_hydrodata.utils.plot.year_series.	{}

Returns:

Type	Description
Axes	The Matplotlib axes containing the annual plot.

tsa_classic(**kwargs)

Create the classic four-panel time-series analysis figure.

The panels show the raw series, detrended series, monthly seasonal pattern, and anomalies in a vertical layout.

Parameters:

Name	Type	Description	Default
**kwargs	Any	Additional keyword arguments forwarded to :func:matplotlib.pyplot.subplots.	{}

Returns:

Type	Description
tuple[Figure, NDArray[object_]]	A tuple containing the Matplotlib figure and the array of axes.

tsa_new(**kwargs)

Create the compact time-series analysis dashboard.

The layout combines the raw series, detrended histogram, anomalies, and monthly seasonal pattern in a 2x2 grid.

Parameters:

Name	Type	Description	Default
**kwargs	Any	Additional keyword arguments forwarded to :func:matplotlib.pyplot.figure.	{}

Returns:

Type	Description
tuple[Figure, NDArray[object_]]	A tuple containing the Matplotlib figure and the array of axes.

time_series_analysis(layout='new', **kwargs)

Create a standard time-series analysis figure for the dataset.

Parameters:

Name	Type	Description	Default
layout	Literal['classic', 'new']	Figure layout to generate. Use "classic" for the stacked four-panel version or "new" for the compact grid.	'new'
**kwargs	Any	Additional keyword arguments forwarded to the selected layout builder.	{}

Returns:

Type	Description
tuple[Figure, NDArray[object_]]	A tuple containing the Matplotlib figure and the array of axes.

Raises:

Type	Description
ValueError	If layout is not one of the supported options.

daily_series_analysis(column_name='value', years=None, **kwargs)

Create a two-panel annual-cycle analysis figure.

The left panel shows the annual envelope with optional highlighted years, and the right panel shows the corresponding value histogram.

Parameters:

Name	Type	Description	Default
column_name	str	Name of the dataset column to analyse.	'value'
years	Sequence[int] | None	Optional sequence of calendar years to overlay on the annual envelope.	None
**kwargs	Any	Additional keyword arguments forwarded to :func:matplotlib.pyplot.figure.	{}

Returns:

Type	Description
tuple[Figure, NDArray[object_]]	A tuple containing the Matplotlib figure and the array of axes.