Welcome to TimeSeriesX’s documentation!
TimeSeriesX
The eXtended time series library.
Manage time series data with explicit time zone, frequency and unit.
Free software: MIT license
Documentation: https://timeseriesx.readthedocs.io.
About
TimeSeriesX is motivated by handling time series data in a convenient way. Almost all the features are actually already provided by pandas. TimeSeriesX extends the pandas time series functionality by the unit functionalities of pint and pint-pandas. Further, TimeSeriesX offers an easy and convenient interface to work with time series without the need to dig deep into these libraries, which nevertheless is still recommended, since they go way beyond time series data.
The main challenges that arise when handling time series data are time zones and frequencies. Since time series data is often obtained by measurements, the values are associated with units. Then these units can be confused easily, since the units are often not modeled in code.
TimeSeriesX forces the user to handle time zones, frequencies and units explicitly, while taking care of validation and convenient formats. It also supports deriving these attributes from raw time series data. It offers a limited set of actions on time series that are translated to pandas or pint functionality under the hood. It was designed to guarantee that every transformation of time series data results in a new valid time series, which would require quite some pandas code if done “manually”.
Features
model time series data with explicit frequency, time zone and unit
convert time zone or unit
resample data to new frequency
fill and get gaps
join time series
perform calculations on time series with python standard operators
Credits
This package was created with Cookiecutter and the audreyr/cookiecutter-pypackage project template.
Installation
Stable release
To install TimeSeriesX, run this command in your terminal:
$ pip install timeseriesx
This is the preferred method to install TimeSeriesX, as it will always install the most recent stable release.
If you don’t have pip installed, this Python installation guide can guide you through the process.
From sources
The sources for TimeSeriesX can be downloaded from the Github repo.
You can either clone the public repository:
$ git clone git://github.com/carlculator/timeseriesx
Or download the tarball:
$ curl -OJL https://github.com/carlculator/timeseriesx/tarball/master
Once you have a copy of the source, you can install it with:
$ python setup.py install
Usage
To use TimeSeriesX in a project:
import timeseriesx as tx
Create a new series:
timestamps = [
dt.datetime(2020, 3, 1, 15, 0, 0),
dt.datetime(2020, 3, 1, 16, 0, 0),
dt.datetime(2020, 3, 1, 17, 0, 0),
]
values = [0., 1., 2.]
ts = tx.TimestampSeries.create_from_lists(timestamps, values, freq='H', unit='km')
Convert time zone:
# set time zone info
ts = ts.convert_time_zone('Europe/Stockholm')
# convert time zone
ts = ts.convert_time_zone('UTC')
Convert unit:
ts = ts.convert_unit('nautical_mile')
Resample frequency:
ts = ts.resample(
'1D', # one day
method='sum'
)
Perform calculations:
ts = ts + [2., 3., 4]
ts = ts * ts
ts = ts / 42.
timeseriesx
timeseriesx package
Subpackages
timeseriesx.base package
Submodules
timeseriesx.base.base_time_series module
- class timeseriesx.base.base_time_series.BaseTimeSeries[source]
Bases:
object- aggregate(func)[source]
aggregate all values of the series with a custom aggregation function
- Parameters
func (function) – a function mapping a numeric list/array/vector to a scalar
- Returns
the aggregated value
- Return type
numpy.float/numpy.int
- property empty
- property first
- property last
- map(func, **kwargs)[source]
apply a custom function to each value of the series
- Parameters
func (function) – a function mapping a scalar to another scalar
- Returns
self
- Return type
- property values
timeseriesx.base.timestamp_series module
- exception timeseriesx.base.timestamp_series.TimestampMismatchWarning[source]
Bases:
RuntimeWarningwarning about implicit handling of mismatching timestamps
- class timeseriesx.base.timestamp_series.TimestampSeries(series, freq=None, unit=None, time_zone=None)[source]
Bases:
timeseriesx.mixins.unit.UnitMixin,timeseriesx.mixins.time_zone.TimeZoneMixin,timeseriesx.mixins.frequency.FrequencyMixin,timeseriesx.base.base_time_series.BaseTimeSeries- append(value)[source]
append a new value to a series with frequency
- Parameters
value (float/int) – the value to append
- Returns
the series with the new appended value
- Return type
- static create_constant_timeseries(start, end, value, freq, unit=None, time_zone='infer')[source]
create a TimestampSeries-object from start to end with constant value
- Parameters
start (str/datetime.datetime/pandas.Timestamp) – the start timestamp of the series (included)
end (str/datetime.datetime/pandas.Timestamp) – the end timestamp of the series (included)
value (int/float) – the constant value for each element
freq (str/datetime.timedelta/pandas.Offset/pandas.Timedelta) – the frequency of the timestamp series, pandas offset aliases supported
unit (str/pint.Unit) – the unit of the series’s values, many string representations of common units are supported, such as m, s, kg and many more
time_zone (str/tzinfo) – the name of the time zone, (see IANA) or a tzinfo-object, pass ‘infer’ if you want the time zone to be derived from start and end
- Returns
a new TimestampSeries-object
- Return type
- static create_from_dict(dictionary, freq='infer', unit=None, time_zone='infer')[source]
create a TimestampSeries-object from a dict timestamps as keys and values as values
- Parameters
dictionary (dict) – dict with timestamps as keys and timeseries-values as dict-values
freq (str/datetime.timedelta/pandas.Offset/pandas.Timedelta) –
the frequency of the timestamp series, pandas offset aliases supported, pass ‘infer’ if you want the frequency to be derived by the timestamps
unit (str/pint.Unit) – the unit of the series’s values, many string representations of common units are supported, such as m, s, kg and many more
time_zone (str/tzinfo) –
the name of the time zone, (see IANA) or a tzinfo-object, pass ‘infer’ if you want the time zone to be derived by the timestamps
- Returns
a new TimestampSeries-object
- Return type
- static create_from_lists(timestamps, values, freq='infer', unit=None, time_zone='infer')[source]
create a TimestampSeries-object from a list of timestamps and values matched by their index
- Parameters
timestamps (list) – the timestamps of the series
values (list) – the values of the series
freq (str/datetime.timedelta/pandas.Offset/pandas.Timedelta) –
the frequency of the timestamp series, pandas offset aliases supported, pass ‘infer’ if you want the frequency to be derived by the timestamps
unit (str/pint.Unit) – the unit of the series’s values, many string representations of common units are supported, such as m, s, kg and many more
time_zone (str/tzinfo) –
the name of the time zone, (see IANA) or a tzinfo-object, pass ‘infer’ if you want the time zone to be derived by the timestamps
- Returns
a new TimestampSeries-object
- Return type
- static create_from_pd_series(series, freq='infer', unit=None, time_zone='infer')[source]
create a TimestampSeries-object from a pandas Series with DatetimeIndex
- Parameters
pandas.Series – a pandas series-object with DatetimeIndex
freq (str/datetime.timedelta/pandas.Offset/pandas.Timedelta) –
the frequency of the timestamp series, pandas offset aliases supported, pass ‘infer’ if you want the frequency to be derived by the timestamps
unit (str/pint.Unit) – the unit of the series’s values, many string representations of common units are supported, such as m, s, kg and many more
time_zone (str/tzinfo) –
the name of the time zone, (see IANA) or a tzinfo-object, pass ‘infer’ if you want the time zone to be derived from start and end
- Returns
a new TimestampSeries-object
- Return type
- static create_from_tuples(tuples, freq='infer', unit=None, time_zone='infer')[source]
create a TimestampSeries-object from a list of tuples of timestamps and values
- Parameters
tuples (list) – list of tuples holding timestamp and value
freq (str/datetime.timedelta/pandas.Offset/pandas.Timedelta) –
the frequency of the timestamp series, pandas offset aliases supported, pass ‘infer’ if you want the frequency to be derived by the timestamps
unit (str/pint.Unit) – the unit of the series’s values, many string representations of common units are supported, such as m, s, kg and many more
time_zone (str/tzinfo) –
the name of the time zone, (see IANA) or a tzinfo-object, pass ‘infer’ if you want the time zone to be derived by the timestamps
- Returns
a new TimestampSeries-object
- Return type
- static create_null_timeseries(start, end, freq, unit=None, time_zone='infer')[source]
create a TimestampSeries-object from start to end with NaN-values
- Parameters
start (str/datetime.datetime/pandas.Timestamp) – the start timestamp of the series (included)
end (str/datetime.datetime/pandas.Timestamp) – the end timestamp of the series (included)
freq (str/datetime.timedelta/pandas.Offset/pandas.Timedelta) –
the frequency of the timestamp series, pandas offset aliases supported
unit (str/pint.Unit) – the unit of the series’s values, many string representations of common units are supported, such as m, s, kg and many more
time_zone (str/tzinfo) –
the name of the time zone, (see IANA) or a tzinfo-object, pass ‘infer’ if you want the time zone to be derived from start and end
- Returns
a new TimestampSeries-object
- Return type
- property end
- property first
- property last
- map(func, dimensionless=True)[source]
apply a custom function to each value of the series
- Parameters
func (function) – a function mapping a scalar to another scalar
dimensionless (bool) – if set to True, the mapping function takes an argument of type Number (no unit, dimensionless). The resulting timestamp series will keep the original unit. If set to False, the mapping function takes an argument of type pint.Quantity. The resulting timestamp series will have the unit of the mapped values. Mapping values of one series to different units results in an error. Mapping with dimensionless=False will result in a loop and therefore perform slower.
- Returns
the series with mapped values
- Return type
- prepend(value)[source]
prepend a new value to a series with frequency
- Parameters
value (float/int) – the value to prepend
- Returns
the series with the new prepended value
- Return type
- round(decimals)[source]
round the values of the series
- Parameters
decimals – no of decimal places to round to
- Returns
the series with rounded values
- Return type
- property start
- property time_range
- property timestamps
- property values
Module contents
timeseriesx.mixins package
Submodules
timeseriesx.mixins.frequency module
- class timeseriesx.mixins.frequency.FrequencyMixin(*args, **kwargs)[source]
Bases:
timeseriesx.mixins.BaseMixin- fill_gaps(start=None, end=None, value=nan)[source]
fill all gaps between start and end in a series with a frequency with a constant value
- Parameters
start (datetime.datetime) – the start timestamps of the period that will be investigated (included). If None, then the first timestamp in the time series is considered as start. Defaults to None
end (datetime.datetime) – the end timestamps of the period that will be investigated (included). If None, then the last timestamp in the time series is considered as end. Defaults to None
value (float/int/np.float) – the constant fill value
- Returns
return the series with filled gaps
- Return type
- property freq
- get_gaps(start=None, end=None)[source]
get all timestamps between start and end from a series with a frequency, where the value is missing or NaN
- Parameters
start (datetime.datetime) – the start timestamps of the period that will be investigated (included). If None, then the first timestamp in the time series is considered as start. Defaults to None
end (datetime.datetime) – the end timestamps of the period that will be investigated (included). If None, then the last timestamp in the time series is considered as end. Defaults to None
- Returns
list of timestamps
- Return type
list of datetime.datetime
- resample(freq, method)[source]
resample the series to a smaller frequency, aggregate the values
- Parameters
freq (str/datetime.timedelta/pandas.Offset/pandas.Timedelta) – the new frequency, has to be smaller than the current frequency (greater offset)
method (str/Callable) – aggregation method, currently supported are “all”, “any”, “min”, “max”, “sum”, “mean”, “median”, or function that a collection (e.g. pandas.Series or list) of numeric values as its argument and returns a scalar
- Returns
the resamples time series
- Return type
timeseriesx.mixins.time_zone module
- class timeseriesx.mixins.time_zone.TimeZoneMixin(*args, **kwargs)[source]
Bases:
timeseriesx.mixins.BaseMixin- convert_time_zone(tz)[source]
convert time series index to another time zone, or make an time zone naive index time zone aware (or the other way round)
- Parameters
tz (str/datetime.tzinfo) – tzinfo object or name of the new time zone or None
- Returns
the series with converted index
- Return type
- property time_zone
timeseriesx.mixins.unit module
- class timeseriesx.mixins.unit.UnitMixin(*args, **kwargs)[source]
Bases:
timeseriesx.mixins.BaseMixin- aggregate(func, with_unit=False)[source]
aggregate all values of the series with a custom aggregation function
- Parameters
func (function) – a function mapping a numeric list/array/vector to a scalar
with_unit (boolean) – flag whether to return the result as a pint object, defaults to False
- Returns
the aggregated value
- Return type
numpy.float/numpy.int/pint.Quantity
- convert_unit(unit)[source]
convert the unit of the series
- Parameters
unit (str/pint.Unit) –
- Returns
the time series with converted units
- Return type
- mean(with_unit=False)[source]
calculate the mean of all values of the series
- Parameters
with_unit (boolean) – flag whether to return the result as a pint object, defaults to False
- Returns
the mean of the values
- Return type
numpy.float/numpy.int/pint.Quantity
- sum(with_unit=False)[source]
calculate the sum of all values of the series
- Parameters
with_unit (boolean) – flag whether to return the result as a pint object, defaults to False
- Returns
the sum of the values
- Return type
numpy.float/numpy.int/pint.Quantity
- property unit
Module contents
timeseriesx.validation package
Submodules
timeseriesx.validation.frequency module
- timeseriesx.validation.frequency.coerce_freq(freq)[source]
return a convenient representation of a frequency as a pandas.DateOffset object
- Parameters
freq (str/datetime.timedelta/pandas.Timedelta/pandas.DateOffset) – a frequency string or frequency object to coerce
- Returns
coerced frequency object
- Return type
pandas.DateOffset
timeseriesx.validation.time_zone module
- timeseriesx.validation.time_zone.coerce_time_zone(tz)[source]
returns the convenient representation of a time zone as a pytz-based tzinfo-object
- Parameters
tz (str/datetime.tzinfo) –
- Returns
the coerced time zone object
- Return type
datetime.tzinfo
timeseriesx.validation.timestamp_index module
- timeseriesx.validation.timestamp_index.index_is_datetime(series, exception=True)[source]
check if the index of a pandas.Series is a valid DatetimeIndex
- Parameters
series (pandas.Series) – the series holding the index to check
exception (bool) – if True, raise an exception in case of invalid DatetimeIndex
- Returns
True if index is a valid DatetimeIndex, False otherwise.
- Return type
bool
- timeseriesx.validation.timestamp_index.index_is_sorted(series, ascending=True, exception=True)[source]
check if the (datetime-) index of a pandas.Series is sorted
- Parameters
series (pandas.Series) – the series holding the index to check
ascending (bool) – if true, check for ascending order, if false for descending order
exception (bool) – if True, raise an exception in case of unsorted index
- Returns
True if index is sorted, False otherwise.
- Return type
bool
timeseriesx.validation.unit module
Module contents
Module contents
Top-level package for TimeSeriesX.
Contributing
Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given.
You can contribute in many ways:
Types of Contributions
Report Bugs
Report bugs at https://github.com/carlculator/timeseriesx/issues.
If you are reporting a bug, please include:
Your operating system name and version.
Any details about your local setup that might be helpful in troubleshooting.
Detailed steps to reproduce the bug.
Fix Bugs
Look through the GitHub issues for bugs. Anything tagged with “bug” and “help wanted” is open to whoever wants to implement it.
Implement Features
Look through the GitHub issues for features. Anything tagged with “enhancement” and “help wanted” is open to whoever wants to implement it.
Write Documentation
TimeSeriesX could always use more documentation, whether as part of the official TimeSeriesX docs, in docstrings, or even on the web in blog posts, articles, and such.
Submit Feedback
The best way to send feedback is to file an issue at https://github.com/carlculator/timeseriesx/issues.
If you are proposing a feature:
Explain in detail how it would work.
Keep the scope as narrow as possible, to make it easier to implement.
Remember that this is a volunteer-driven project, and that contributions are welcome :)
Get Started!
Ready to contribute? Here’s how to set up timeseriesx for local development.
Fork the timeseriesx repo on GitHub.
Clone your fork locally:
$ git clone git@github.com:your_name_here/timeseriesx.git
Install your local copy into a virtualenv. Assuming you have virtualenvwrapper installed, this is how you set up your fork for local development:
$ mkvirtualenv timeseriesx $ cd timeseriesx/ $ python setup.py developCreate a branch for local development:
$ git checkout -b name-of-your-bugfix-or-feature
Now you can make your changes locally.
When you’re done making changes, check that your changes pass flake8 and the tests, including testing other Python versions with tox:
$ flake8 timeseriesx tests $ python setup.py test or pytest $ toxTo get flake8 and tox, just pip install them into your virtualenv.
Commit your changes and push your branch to GitHub:
$ git add . $ git commit -m "Your detailed description of your changes." $ git push origin name-of-your-bugfix-or-featureSubmit a pull request through the GitHub website.
Pull Request Guidelines
Before you submit a pull request, check that it meets these guidelines:
The pull request should include tests.
If the pull request adds functionality, the docs should be updated. Put your new functionality into a function with a docstring, and add the feature to the list in README.rst.
The pull request should work for Python 3.7, 3.8 and 3.9, and for PyPy. Check https://travis-ci.com/carlculator/timeseriesx/pull_requests and make sure that the tests pass for all supported Python versions.
Tips
To run a subset of tests:
$ pytest tests.test_timeseriesx
Deploying
A reminder for the maintainers on how to deploy. Make sure all your changes are committed (including an entry in HISTORY.rst). Then run:
$ bump2version patch # possible: major / minor / patch
$ git push
$ git push --tags
Travis will then deploy to PyPI if tests pass.
Credits
Development Lead
Alexander Schulz <info@alexander-schulz.eu>
Contributors
History
0.1.13 (2022-07-19)
fix a few bugs by avoiding is_compatible_with in convert_unit
raise only ValueError instead of DimensionalityError on unit dimensionality mismatch
remove pandas installation dependency because of transitive dependency via pint-pandas
loosen requirements for pytz and dateutil, no special version requirements known
extend __getitem__ functionality by supporting iterables of timestamps or positional indices
explicitly support indexing by time zone naive timestamps, which is deprecated by pandas
make coerce_unit behave like coerce_freq and coerce_time_zone by passing through None
0.1.12 (2022-03-16)
fix equals method
update documentation
0.1.11 (2022-03-07)
fix resampling method to support nan-values
update dependencies
0.1.10 (2022-01-21)
fix equals method
update dependencies
0.1.9 (2021-11-19)
allow aggregation functions to return magnitudes or quantities
update dependencies
0.1.8 (2021-09-28)
fix time zone bug in gap handling
update dependencies
add more tests
0.1.7 (2021-09-28)
improve gap handling
update dependencies
improve documentation
fix calculations with quantity scalar
0.1.6 (2021-09-13)
fix time zone issue with UTC in basic calculations for TimestampSeries as 2nd operand
update pint-pandas version dependency
use pint’s default unit registry
add support of callables as arguments for frequency resampling
add more tests
0.1.5 (2021-09-10)
fix time zone issue with UTC in basic calculations
add round-method for TimestampSeries
fix map-function for series with unit
add more tests
0.1.4 (2021-09-09)
improve test coverage
improve TimeSeries equality check
support NaN-removal in as_pd_series-method
0.1.3 (2021-09-08)
remove manual timezone checks because it is handled by pandas
fix skipped tests
fix repr() method of TimestampSeries
fix basic calculation with units involved
0.1.2 (2021-09-07)
fix timezone handling
First release on PyPI Index.
0.1.1 (2021-02-16)
First release on PyPI Test Index.