{"id":13571038,"url":"https://github.com/Nixtla/tsfeatures","last_synced_at":"2025-04-04T07:32:48.118Z","repository":{"id":47337617,"uuid":"222991822","full_name":"Nixtla/tsfeatures","owner":"Nixtla","description":"Calculates various features from time series data. Python implementation of the R package tsfeatures.","archived":false,"fork":false,"pushed_at":"2024-04-23T14:31:12.000Z","size":236,"stargazers_count":398,"open_issues_count":8,"forks_count":44,"subscribers_count":8,"default_branch":"main","last_synced_at":"2025-03-28T06:18:48.447Z","etag":null,"topics":["errors","features","fforma","forecasting","m4","metrics","python","time-series","tsfeatures"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Nixtla.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-11-20T17:29:55.000Z","updated_at":"2025-03-27T00:39:47.000Z","dependencies_parsed_at":"2024-04-16T01:43:31.121Z","dependency_job_id":"7cbce4fe-6729-4914-bdd6-43f70aac9e79","html_url":"https://github.com/Nixtla/tsfeatures","commit_stats":{"total_commits":193,"total_committers":4,"mean_commits":48.25,"dds":0.04663212435233166,"last_synced_commit":"fe4f6e63b8883f84922354b7a57056cf534aa4ae"},"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Nixtla%2Ftsfeatures","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Nixtla%2Ftsfeatures/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Nixtla%2Ftsfeatures/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Nixtla%2Ftsfeatures/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Nixtla","download_url":"https://codeload.github.com/Nixtla/tsfeatures/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247139408,"owners_count":20890229,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["errors","features","fforma","forecasting","m4","metrics","python","time-series","tsfeatures"],"created_at":"2024-08-01T14:00:57.786Z","updated_at":"2025-04-04T07:32:43.105Z","avatar_url":"https://github.com/Nixtla.png","language":"Python","readme":"[![Build](https://github.com/FedericoGarza/tsfeatures/workflows/Python%20package/badge.svg)](https://github.com/FedericoGarza/tsfeatures/tree/master)\n[![PyPI version fury.io](https://badge.fury.io/py/tsfeatures.svg)](https://pypi.python.org/pypi/tsfeatures/)\n[![Downloads](https://pepy.tech/badge/tsfeatures)](https://pepy.tech/project/tsfeatures)\n[![Python 3.6+](https://img.shields.io/badge/python-3.7+-blue.svg)](https://www.python.org/downloads/release/python-370+/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://github.com/FedericoGarza/tsfeatures/blob/master/LICENSE)\n\n# tsfeatures\n\nCalculates various features from time series data. Python implementation of the R package _[tsfeatures](https://github.com/robjhyndman/tsfeatures)_.\n\n# Installation\n\nYou can install the *released* version of `tsfeatures` from the [Python package index](pypi.org) with:\n\n``` python\npip install tsfeatures\n```\n\n# Usage\n\nThe `tsfeatures` main function calculates by default the features used by Montero-Manso, Talagala, Hyndman and Athanasopoulos in [their implementation of the FFORMA model](https://htmlpreview.github.io/?https://github.com/robjhyndman/M4metalearning/blob/master/docs/M4_methodology.html#features).\n\n```python\nfrom tsfeatures import tsfeatures\n```\n\nThis function receives a panel pandas df with columns `unique_id`, `ds`, `y` and optionally the frequency of the data.\n\n\u003cimg src=https://raw.githubusercontent.com/FedericoGarza/tsfeatures/master/.github/images/y_train.png width=\"152\"\u003e\n\n```python\ntsfeatures(panel, freq=7)\n```\n\nBy default (`freq=None`) the function will try to infer the frequency of each time series (using `infer_freq` from `pandas` on the `ds` column) and assign a seasonal period according to the built-in dictionary `FREQS`:\n\n```python\nFREQS = {'H': 24, 'D': 1,\n         'M': 12, 'Q': 4,\n         'W':1, 'Y': 1}\n```\n\nYou can use your own dictionary using the `dict_freqs` argument:\n\n```python\ntsfeatures(panel, dict_freqs={'D': 7, 'W': 52})\n```\n\n## List of available features\n\n| Features |||\n|:--------|:------|:-------------|\n|acf_features|heterogeneity|series_length|\n|arch_stat|holt_parameters|sparsity|\n|count_entropy|hurst|stability|\n|crossing_points|hw_parameters|stl_features|\n|entropy|intervals|unitroot_kpss|\n|flat_spots|lumpiness|unitroot_pp|\n|frequency|nonlinearity||\n|guerrero|pacf_features||\n\nSee the docs for a description of the features. To use a particular feature included in the package you need to import it:\n\n```python\nfrom tsfeatures import acf_features\n\ntsfeatures(panel, freq=7, features=[acf_features])\n```\n\nYou can also define your own function and use it together with the included features:\n\n```python\ndef number_zeros(x, freq):\n\n    number = (x == 0).sum()\n    return {'number_zeros': number}\n\ntsfeatures(panel, freq=7, features=[acf_features, number_zeros])\n```\n\n`tsfeatures` can handle functions that receives a numpy array `x` and a frequency `freq` (this parameter is needed even if you don't use it) and returns a dictionary with the feature name as a key and its value.\n\n## R implementation\n\nYou can use this package to call `tsfeatures` from R inside python (you need to have installed R, the packages `forecast` and `tsfeatures`; also the python package `rpy2`):\n\n```python\nfrom tsfeatures.tsfeatures_r import tsfeatures_r\n\ntsfeatures_r(panel, freq=7, features=[\"acf_features\"])\n```\n\nObserve that this function receives a list of strings instead of a list of functions.\n\n## Comparison with the R implementation (sum of absolute differences)\n\n### Non-seasonal data (100 Daily M4 time series)\n\n| feature         |   diff | feature         |   diff | feature         |   diff | feature         |   diff |\n|:----------------|-------:|:----------------|-------:|:----------------|-------:|:----------------|-------:|\n| e_acf10         |   0    | e_acf1         |   0    | diff2_acf1         |   0    | alpha         |   3.2    |\n| seasonal_period |   0    | spike         |   0    | diff1_acf10         |   0    | arch_acf         |   3.3    |\n| nperiods        |   0    | curvature         |   0    | x_acf1         |   0    | beta         |   4.04    |\n| linearity       |   0    | crossing_points         |   0    | nonlinearity         |   0    | garch_r2         |   4.74    |\n| hw_gamma        |   0    | lumpiness         |   0    | diff2x_pacf5         |   0    | hurst         |   5.45    |\n| hw_beta         |   0    | diff1x_pacf5         |   0    | unitroot_kpss         |   0    | garch_acf         |   5.53    |\n| hw_alpha        |   0    | diff1_acf10         |   0    | x_pacf5         |   0    | entropy         |   11.65    |\n| trend           |   0    | arch_lm         |   0    | x_acf10         |   0    |\n| flat_spots      |   0    | diff1_acf1         |   0    | unitroot_pp         |   0    |\n| series_length   |   0    | stability         |   0    | arch_r2         |   1.37    |\n\nTo replicate this results use:\n\n``` console\npython -m tsfeatures.compare_with_r --results_directory /some/path\n                                    --dataset_name Daily --num_obs 100\n```\n\n### Sesonal data (100 Hourly M4 time series)\n\n| feature           |   diff | feature      | diff | feature   | diff    | feature    | diff    |\n|:------------------|-------:|:-------------|-----:|:----------|--------:|:-----------|--------:|\n| series_length     |   0    |seas_acf1     | 0    | trend | 2.28 | hurst | 26.02 |\n| flat_spots        |   0    |x_acf1|0| arch_r2 | 2.29 | hw_beta | 32.39 |\n| nperiods          |   0    |unitroot_kpss|0| alpha | 2.52 | trough | 35 |\n| crossing_points   |   0    |nonlinearity|0| beta | 3.67 | peak | 69 |\n| seasonal_period   |   0    |diff1_acf10|0| linearity | 3.97 |\n| lumpiness         |   0    |x_acf10|0| curvature | 4.8 |\n| stability         |   0    |seas_pacf|0| e_acf10 | 7.05 |\n| arch_lm           |   0    |unitroot_pp|0| garch_r2 | 7.32 |\n| diff2_acf1        |   0    |spike|0| hw_gamma | 7.32 |\n| diff2_acf10       |   0    |seasonal_strength|0.79| hw_alpha | 7.47 |\n| diff1_acf1        |   0    |e_acf1|1.67| garch_acf | 7.53 |\n| diff2x_pacf5      |   0    |arch_acf|2.18| entropy | 9.45 |\n\nTo replicate this results use:\n\n``` console\npython -m tsfeatures.compare_with_r --results_directory /some/path \\\n                                    --dataset_name Hourly --num_obs 100\n```\n\n# Authors\n\n* **Federico Garza** - [FedericoGarza](https://github.com/FedericoGarza)\n* **Kin Gutierrez** - [kdgutier](https://github.com/kdgutier)\n* **Cristian Challu** - [cristianchallu](https://github.com/cristianchallu)\n* **Jose Moralez** - [jose-moralez](https://github.com/jose-moralez)\n* **Ricardo Olivares** - [rolivaresar](https://github.com/rolivaresar)\n* **Max Mergenthaler** - [mergenthaler](https://github.com/mergenthaler)\n","funding_links":[],"categories":["Time Series Analysis","📦 Packages"],"sub_categories":["Specialized Machine Learning Libraries","Python"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FNixtla%2Ftsfeatures","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FNixtla%2Ftsfeatures","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FNixtla%2Ftsfeatures/lists"}