ReachObservation

ReachObservation(
    data,
    *,
    reach,
    item=None,
    name=None,
    weight=1.0,
    quantity=None,
    aux_items=None,
    attrs=None,
)

Class for observations representing a quantity uniform across a network reach.

Some quantities (e.g. discharge in a river reach) are constant for the whole reach, even though the underlying model stores values at nodes/breakpoints. A ReachObservation associates a timeseries with a named reach; when matched against a :class:~modelskill.model.network.NetworkModelResult the data is extracted from the breakpoints on that reach that carry the quantity and hold data for it. When there are several, they must agree, and the one with the lowest position is used. The comparer sits on the reach; mr.extract(obs).at gives the breakpoint read.

Parameters

Name	Type	Description	Default
data	(str, Path, mikeio.Dataset, mikeio.DataArray, pd.DataFrame, pd.Series, xr.Dataset or xr.DataArray)	data source with time series for the reach quantity	required
reach	str	Reach identifier (reach name / reach ID) in the network.	required
item	(int, str)	index or name of the wanted item/column, by default None if data contains more than one item, item must be given	None
name	str	user-defined name for easy identification in plots etc, by default derived from data	None
weight	float	weighting factor for skill scores, by default 1.0	1.0
quantity	Quantity	The quantity of the observation, for validation with model results	None
aux_items	list	list of names or indices of auxiliary items, by default None	None
attrs	dict	additional attributes to be added to the data, by default None	None

Examples

>>> import modelskill as ms
>>> o1 = ms.ReachObservation(df, reach="reach_1", name="Q_reach_1")
>>> o2 = ms.ReachObservation(df, item="Discharge", reach="reach_2")

Attributes

Name	Description
at	Observation location: the reach name.
attrs	Attributes of the observation
gtype	Geometry type
n_points	Number of data points
name	Name of time series (value item name)
plot	Plot using the ComparerPlotter
quantity	Quantity of time series
reach	Reach ID of this observation.
time	Time index
values	Values as numpy array
weight	Weighting factor for skill scores
x	x-coordinate
y	y-coordinate

Methods

Name	Description
copy	Create a deep copy of the TimeSeries.
equals	Check if two TimeSeries are equal
from_multiple	Create multiple ReachObservation objects.
sel	Select data by label
to_dataframe	Convert matched data to pandas DataFrame
trim	Trim observation data to a given time interval

copy

ReachObservation.copy()

Create a deep copy of the TimeSeries.

Returns

Name	Type	Description
	TimeSeries	Deep copy of the TimeSeries object

equals

ReachObservation.equals(other)

Check if two TimeSeries are equal

from_multiple

ReachObservation.from_multiple(
    data=None,
    reaches=None,
    quantity=None,
    aux_items=None,
    attrs=None,
)

Create multiple ReachObservation objects.

Two calling conventions are supported:

1. Separate data sources — pass only reaches as a dict mapping each reach ID to its own data source (file path, DataFrame, etc.)::

   obs = ReachObservation.from_multiple(reaches={"r1": df1, "r2": "sensor.csv"})

2. Shared data source — pass a single data object together with reaches as a dict mapping each reach ID to the column name or index to select from data::

   obs = ReachObservation.from_multiple(data=df, reaches={"r1": "col_a", "r2": "col_b"})

Parameters

Name	Type	Description	Default
data	PointType	Shared data source (required when reaches values are column selectors).	None
reaches	dict[str, PointType | str | int]	Mapping of reach_id -> data source or column selector. Note that a reach can appear only once, so this form cannot express several observations on the same reach.	None
quantity	Quantity	Physical quantity metadata, by default None.	None
aux_items	list[int | str] | None	Auxiliary items, by default None.	None
attrs	dict | None	Additional attributes, by default None.	None

Returns

Name	Type	Description
	list[ReachObservation]	List of ReachObservation objects.

Raises

Name	Type	Description
	ValueError	If reaches is not given.

sel

ReachObservation.sel(**kwargs)

Select data by label

to_dataframe

ReachObservation.to_dataframe()

Convert matched data to pandas DataFrame

Include x, y coordinates only if gtype=track

Returns

Name	Type	Description
	pd.DataFrame	data as a pandas DataFrame

trim

ReachObservation.trim(
    start_time=None,
    end_time=None,
    buffer='1s',
    no_overlap='error',
)

Trim observation data to a given time interval

Parameters

Name	Type	Description	Default
start_time	pd.Timestamp	start time	None
end_time	pd.Timestamp	end time	None
buffer	str	buffer time around start and end time, by default “1s”	'1s'
no_overlap	Literal['ignore', 'error', 'warn']	Empty data handling.	'error'