Package: smana
smana: repairing tool for time series with weekly seasonalityWhat is it?smanais a Python package useful to restore missing values of a time series with a weekly pattern.Table of ContentsMain FeaturesDependenciesHow it worksHow to get itDocumentationLicenseContributing to smanaMain FeaturesMissing values restoring for time series with weekly seasonal patternAny time series with sub-daily resolution is supportedHandling of calendar information on public holidays (if provided by the user)DependenciesstatsmodelspandasNumPyHow it worksThis package arises from the need to restore energy time series data, which usually present weekly seasonality and
not rarely even a correlation with public holidays. Nevertheless, the implementation is based only on the assumption
that the time series shows a weekly pattern, thus this tool can be used to repair data of whatever nature with this
seasonal characteristic.The core of the algorithm is based onSTL decomposition("Seasonal and Trend decomposition using Loess"), a robust method for decomposing time series into trend, seasonal and
remainder components, implemented instatsmodelsmodule.The main method of this package,smana.repair(), aims to restore sequences of missing data (represented asnumpy.NaN) by means of locally approximation of the trend and the seasonal components of the time series; in order to get the
seasonality estimation, the algorithm tries to identify a sequence of at least 14 consecutive days of valid data: if
it does not exist, linear interpolation or lookup table strategies are iteratively applied (using a ranking criteria
on missing-values sequences) until a 14-days sequence appears.In addition, this tool is able to handle calendar information on public holidays: this feature is useful only if the
time series presents a correlation with these specific days, in particular if its daily pattern resemble that of
standard week holidays; for this reason, it is recommended to leverage this feature only if this assumption is verified.How to get itThe source code is currently hosted on GitHub at:https://github.com/ToBe-Analytics/smanaBinary installers for the latest released version are available at thePython
Package Index (PyPI).# PyPIpipinstall-ihttps://pypi.org/simple/smanaThe list of changes tosmanabetween each release can be foundhere. For full
details, see the commit logs athttps://github.com/ToBe-Analytics/smana.DocumentationThe package provides the following main method, which implements the whole procedure described:smana.repair(input_df,scan_column,datetime_column=None,trend_approx_days=7,nonnegative_constraint=False,holidays_stl=False,week_holiday_int=6,holidays_column=None,inplace=False)This function restores missing values (numpy.NaN) of the time seriesscan_columnininput_dfdataframe,
withdatetime_columnas timestamps column, by a process based on the STL decomposition.
Optionally, settingholidays_stlto True, it is possible to apply a similar strategy to repair
missing data related to public holidays (this procedure is based on week holiday data).Parametersinput_df:pandas.DataFrameInput dataframe which collects the time series to be repaired, the datetime series and optionally
the column with public holidays information.scan_column:strLabel of the numeric column ofinput_dfto be restored. Missing values must be represented asnumpy.NaN.datetime_column:str, default NoneLabel of the datetime column ofinput_df; aware or naive datetime are supported. If unspecified,input_df.indexis considered.trend_approx_days:int, default 7Number of days to consider for trend estimation; higher values lead to approximations over longer periods.
Integers less than 7 will be replaced by default value. It is not necessary to modify this parameter.nonnegative_constraint:bool, default FalseSet to True to check and repair negative restored values.holidays_stl:bool, default FalseApply a specific strategy for the restoring of missing values related to public holidays.week_holiday_int:int, default 6Index corresponding to the week holiday, from 0 (Monday) to 6 (Sunday). This argument is considered only ifholidays_stlis set to True.holidays_column:str, default NoneLabel of the column which collects holidays information; for each row ininput_df, the allowed values are
only 0 (working day) or 1 (holiday, including standard week holiday). This argument is considered only ifholidays_stlis set to True.inplace:bool, default FalseIf False, return a copy. Otherwise, do operation inplace and the method returns None.Returnspandas.DataFrame or NoneDataFrame restored or None ifinplaceis set to True.LicenseBSD 3Contributing to smanaAll contributions, bug reports, bug fixes, documentation improvements, enhancements, and ideas are welcome.
A detailed overview on how to contribute can be found in thecontributing guide.
As contributors and maintainers to this project, you are expected to abide by our code of conduct.
More information can be found at:Contributor Code of ConductGo to Top