Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Fix _fh.py docstrings #4

Merged
merged 2 commits into from
Jul 26, 2021
Merged

Fix _fh.py docstrings #4

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
c4cf883
Fix _fh.py docstrings
RNKuhns Jul 18, 2021
dd908fb
Merge branch 'fix_docs' into forecasting_docstrings
RNKuhns Jul 26, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
107 changes: 66 additions & 41 deletions sktime/forecasting/base/_fh.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -48,11 +48,10 @@


def _delegator(method):
"""Decorate ForecastingHorizon with pandas.index methods.
"""Automatically decorate ForecastingHorizon class with pandas.Index methods.

Helper function to automatically decorate ForecastingHorizon class with
Also delegates method calls to wrapped pandas.Index object.
methods from pandas.Index and delegate method calls to wrapped pandas.Index
object.
"""

def delegated(obj, *args, **kwargs):
Expand All @@ -62,7 +61,10 @@ def delegated(obj, *args, **kwargs):


def _check_values(values):
"""Validate forecasting horizon values and coerce to pandas.Index type.
"""Validate forecasting horizon values.

Validation checks validity and also converts forecasting horizon values
to supported pandas.Index types if possible.

Parameters
----------
Expand All @@ -71,7 +73,8 @@ def _check_values(values):

Raises
------
TypeError : if values type is not supported
TypeError :
Raised if `values` type is not supported

Returns
-------
Expand Down Expand Up @@ -180,15 +183,15 @@ def _new(self, values=None, is_relative=None):
Parameters
----------
values : pd.Index, np.array, list or int
Values of forecasting horizon
is_relative : bool, optional (default=same as self.is_relative)
Values of forecasting horizon.
is_relative : bool, default=same as self.is_relative
- If None, determined automatically: same as self.is_relative
- If True, values are relative to end of training series.
- If False, values are absolute.

Returns
-------
ForecastingHorizon
ForecastingHorizon :
New ForecastingHorizon based on current object
"""
if values is None:
Expand All @@ -199,7 +202,7 @@ def _new(self, values=None, is_relative=None):

@property
def is_relative(self):
"""Whether forecasting horizon is relative.
"""Whether forecasting horizon is relative to the end of the training series.

Returns
-------
Expand All @@ -208,16 +211,17 @@ def is_relative(self):
return self._is_relative

def to_pandas(self):
"""Return underlying values as pd.Index.
"""Return forecasting horizon's underlying values as pd.Index.

Returns
-------
fh : pd.Index
pandas Index containing forecasting horizon's underlying values.
"""
return self._values

def to_numpy(self, **kwargs):
"""Return underlying values as np.array.
"""Return forecasting horizon's underlying values as np.array.

Parameters
----------
Expand All @@ -227,6 +231,7 @@ def to_numpy(self, **kwargs):
Returns
-------
fh : np.ndarray
NumPy array containg forecasting horizon's underlying values.
"""
return self.to_pandas().to_numpy(**kwargs)

Expand All @@ -235,18 +240,18 @@ def to_numpy(self, **kwargs):
# calling different methods.
@lru_cache(typed=True)
def to_relative(self, cutoff=None):
"""Return relative values.
"""Return forecasting horizon values relative to a cutoff.

Parameters
----------
cutoff : pd.Period, pd.Timestamp, int, optional (default=None)
Cutoff value is required to convert a relative forecasting
horizon to an absolute one and vice versa.
Cutoff value required to convert a relative forecasting
horizon to an absolute one (and vice versa).

Returns
-------
fh : ForecastingHorizon
Relative representation of forecasting horizon
Relative representation of forecasting horizon.
"""
if self.is_relative:
return self._new()
Expand Down Expand Up @@ -277,18 +282,18 @@ def to_relative(self, cutoff=None):

@lru_cache(typed=True)
def to_absolute(self, cutoff):
"""Convert ForecastingHorizon to absolute and return.
"""Return absolute version of forecasting horizon values.

Parameters
----------
cutoff : pd.Period, pd.Timestamp, int
Cutoff value is required to convert a relative forecasting
horizon to an absolute one and vice versa.
horizon to an absolute one (and vice versa).

Returns
-------
fh : ForecastingHorizon
Absolute representation of forecasting horizon
Absolute representation of forecasting horizon.
"""
if not self.is_relative:
return self._new()
Expand Down Expand Up @@ -320,14 +325,14 @@ def to_absolute_int(self, start, cutoff=None):
start : pd.Period, pd.Timestamp, int
Start value returned as zero.
cutoff : pd.Period, pd.Timestamp, int, optional (default=None)
Cutoff value is required to convert a relative forecasting
horizon to an absolute one and vice versa.
Cutoff value required to convert a relative forecasting
horizon to an absolute one (and vice versa).

Returns
-------
fh : ForecastingHorizon
Absolute representation of forecasting horizon as zero-based
integer index
integer index.
"""
# We here check the start value, the cutoff value is checked when we use it
# to convert the horizon to the absolute representation below
Expand All @@ -351,13 +356,13 @@ def to_in_sample(self, cutoff=None):
Parameters
----------
cutoff : pd.Period, pd.Timestamp, int, optional (default=None)
Cutoff value is required to convert a relative forecasting
horizon to an absolute one and vice versa.
Cutoff value required to convert a relative forecasting
horizon to an absolute one (and vice versa).

Returns
-------
fh : ForecastingHorizon
In-sample values of forecasting horizon
In-sample values of forecasting horizon.
"""
is_in_sample = self._is_in_sample(cutoff)
in_sample = self.to_pandas()[is_in_sample]
Expand All @@ -370,12 +375,12 @@ def to_out_of_sample(self, cutoff=None):
----------
cutoff : pd.Period, pd.Timestamp, int, optional (default=None)
Cutoff value is required to convert a relative forecasting
horizon to an absolute one and vice versa.
horizon to an absolute one (and vice versa).

Returns
-------
fh : ForecastingHorizon
Out-of-sample values of forecasting horizon
Out-of-sample values of forecasting horizon.
"""
is_out_of_sample = self._is_out_of_sample(cutoff)
out_of_sample = self.to_pandas()[is_out_of_sample]
Expand All @@ -386,13 +391,12 @@ def _is_in_sample(self, cutoff=None):
return self.to_relative(cutoff).to_pandas() <= 0

def is_all_in_sample(self, cutoff=None):
"""Whether or not the fh is purely in-sample given cutoff, yes/no.
"""Whether the forecasting horizon is purely in-sample for given cutoff.

Parameters
----------
cutoff : pd.Period, pd.Timestamp, int, optional (default=None)
Cutoff value is required to convert a relative forecasting
horizon to an absolute one and vice versa.
cutoff : pd.Period, pd.Timestamp, int, default=None
Cutoff value used to check if forecasting horizon is purely in-sample.

Returns
-------
Expand All @@ -407,13 +411,13 @@ def _is_out_of_sample(self, cutoff=None):
return self.to_relative(cutoff).to_pandas() > 0

def is_all_out_of_sample(self, cutoff=None):
"""Whether or not the fh is purely out-of-sample given cutoff, yes/no.
"""Whether the forecasting horizon is purely out-of-sample for given cutoff.

Parameters
----------
cutoff : pd.Period, pd.Timestamp, int, optional (default=None)
Cutoff value is required to convert a relative forecasting
horizon to an absolute one and vice versa.
Cutoff value used to check if forecasting horizon is purely
out-of-sample.

Returns
-------
Expand All @@ -429,7 +433,7 @@ def to_indexer(self, cutoff=None, from_cutoff=True):
Parameters
----------
cutoff : pd.Period, pd.Timestamp, int, optional (default=None)
Cutoff value is required to convert a relative forecasting
Cutoff value required to convert a relative forecasting
horizon to an absolute one and vice versa.
from_cutoff : bool, optional (default=True)
- If True, zero-based relative to cutoff.
Expand All @@ -439,7 +443,7 @@ def to_indexer(self, cutoff=None, from_cutoff=True):
Returns
-------
fh : pd.Index
Indexer
Indexer.
"""
if from_cutoff:
return self.to_relative(cutoff).to_pandas() - 1
Expand All @@ -455,10 +459,19 @@ def __repr__(self):


def _check_cutoff(cutoff, index):
"""Check whether cutoff is compatible with fh index type.
"""Check if the cutoff is valid based on time index of forecasting horizon.

Helper function to check if the cutoff contains all necessary information and is
compatible with the time index of the forecasting horizon
Validates that the cutoff contains necessary information and is
compatible with the time index of the forecasting horizon.

Parameters
----------
cutoff : pd.Period, pd.Timestamp, int, optional (default=None)
Cutoff value is required to convert a relative forecasting
horizon to an absolute one and vice versa.
index : pd.PeriodIndex or pd.DataTimeIndex
Forecasting horizon time index that the cutoff value will be checked
against.
"""
if cutoff is None:
raise ValueError("`cutoff` must be given, but found none.")
Expand Down Expand Up @@ -493,10 +506,22 @@ def _check_start(start, index):


def _coerce_to_period(x, freq=None):
"""Coerce compatible index type to pd.PeriodIndex.
"""Coerce pandas time index to a alternative pandas time index.

Helper function to coerce pd.Timestamp to pd.Period or pd.DatetimeIndex to
pd.PeriodIndex for more reliable arithmetic operations with time indices
This coerces pd.Timestamp to pd.Period or pd.DatetimeIndex to
pd.PeriodIndex, because pd.Period and pd.PeriodIndex allow more reliable
arithmetic operations with time indices.

Parameters
----------
x : pandas Index
pandas Index to convert.
freq :

Returns
-------
index : pd.Period or pd.PeriodIndex
Index coerced to preferred format.
"""
if freq is None:
freq = _get_freq(x)
Expand Down