bulum.stats.negflo module

Bulum implementation of Negflo and supporting classes.

Warning

This implementation is mildly experimental, insofar as having been written entirely based off the Qld Hydrology page as a “spec”. See below. If there are bugs/unexpected behaviours please let us know!

Of note is that there is currently still no reading from negflo config files!

See also

Spec

https

//qldhyd.atlassian.net/wiki/spaces/MET/pages/524386/Negflo

class Negflo(df_residual: DataFrame | TimeseriesDataframe, flow_limit: float = 0.0, num_segments: int = 0, segments: MutableSequence[tuple[Timestamp, Timestamp]] | None = None)

Bases: object

Bulum implementation of NEGFLO.

When there are negative overflows from the smoothing algorithm, they will be noted in self.neg_overflows.

cl1() → None

Clip all negative flows to zero.

log() → None

Not yet implemented.

Input_file_name.LOG

A file is also created which gives the total of the positive and negative flows, the total of the positive flows above the flow limit. It also gives the start and end of each period of flows above the flow limit, the total of the preceding negatives and the total of the positive flow above the flow limit.

run_all(filename='./residual')

Runs all analyses on the residual.

rw1() → None

Compute the raw residual i.e. downstream-upstream flows.

Internally, resets the residual to that stored on initialisation.

sm1() → None

Redistribute negative flows across all positive flow events.

The negative flows are set to zero and the excess positive flows have been adjusted by a factor of:

1 - abs(Total of the negative flows)/(Total of the positive flows)
Returns:

The results are written to self.df_residual.

Return type:

None

sm2() → None

Redistribute negative flows into future positive flow events, with carry-over.

Accumulated negative flows are factored into positive flow events (defined as periods above the flow limit) using the formula from before, namely:

1 - abs(Total of the accumulated negative flows)/(Total of the positive flow period)

Note that this will not reduce flows below the specified flow limit (self.flow_limit).

This method accumulates negative flows such that if the first encountered positive flow period is not sufficiently large, it will load the remaining balance into the next positive flow period.

As before, if the flow limit is set to zero flow, the flows will give modelled flows with a mean that is close to the mean of the measure flows. However, it can eliminate small flow peaks if there are a lot of negative flows. Setting the flow limit to a high flow preserves these peaks, but can severely reduce the high flows. It can give a ranked flow plot with a notch at the flow limit.

sm3() → None

Redistribute negative flows into future positive flow events, without carry-over.

See also

sm4() → None

Redistribute negative flows into past positive flow events, carrying forward negative flow into the future. Refer to sm2().

sm5() → None

Redistribute negative flows into past positive flow events, without carrying negative flows into the future.

See also

sm6(*, use_predefined_segments=True, sampling_frequency: DateOffset | None = None, sampling_start_date: Timestamp | None = None) → None

Smooths over the specified segments.

Applies the SM1 smoothing algorithm (ie global smoothing) for flows across the specified periods. If no segments are defined or method is set to sample, then it will partition the full period on an annual (default) basis.

Unlike the reference documentation, this function does not set the flow limit to zero while smoothing.

Assumes the indices of the underlying dataframe are datetimes.

Parameters:

  • use_predefined_segments (bool, default True) – Use the stored segments (self.sm6_segment_boundaries) if they exist. Otherwise the segments will be computed when this method is called.

  • sampling_frequency (pd.DateOffset, optional) – Specifies the time interval for smoothing periods. Defaults to one year.

  • sampling_start_date (pd.Timestamp, optional) – Specifies the start of the first period for sampling. Defaults to the start of the data period.

Returns:

Writes the result to self.df_residual.

Return type:

None

See also

sm7() → None

Smooths negative flows over the largest adjacent positive flow event.

Note

Unlike the reference document, this program does not require the flow limit be negative.

See also

to_file(*, out_filename: str | None = None)

Saves the result dataframe to the output file.