DOCSEARCHbyAlgolia
Submit Docs

nixtla/tsfeatures

repository·main·Indexed 19 days ago

https://github.com/nixtla/tsfeatures

A Python implementation of the R package 'tsfeatures' used to calculate statistical features from time series data for machine learning models like FFORMA. It provides a main tsfeatures() function for pandas DataFrames, a set of built-in feature functions such as acf_features and entropy, and support for custom feature functions. Additionally, it offers tsfeatures_r to call the original R implementation via rpy2 and a comparison module to validate results against the R version.

Tokens
1.1K
Snippets
6
Records
6
Agent score
16%

What's inside tsfeatures

  2. Define and use custom feature functions

    main

    You can extend tsfeatures by defining your own feature functions. A custom function must:

    1. Accept two arguments: a numpy array x (the time series values) and a frequency freq.
    2. Return a dictionary where the key is the feature name and the value is the calculated feature.

    Pass these functions in a list to the features argument of tsfeatures() alongside existing features.

    from tsfeatures import tsfeatures, acf_features

def number_zeros(x, freq):
    number = (x == 0).sum()
    return {'number_zeros': number}

# Use both a built-in feature and a custom one
tsfeatures(panel, freq=7, features=[acf_features, number_zeros])

  3. Use the tsfeatures main function

    main

    The tsfeatures() function calculates time series features from a pandas DataFrame.

    Input Requirements:

    • A pandas DataFrame (panel) containing the following columns:
      • unique_id: Identifier for each time series.
      • ds: Timestamp column.
      • y: The time series values.
    • freq (optional): The frequency of the data. If None (default), the function attempts to infer the frequency from the ds column using pandas infer_freq and maps it to a seasonal period using the built-in FREQS dictionary:
      • 'H': 24
      • 'D': 1
      • 'M': 12
      • 'Q': 4
      • 'W': 1
      • 'Y': 1

    Customizing Frequency Mapping: You can provide a custom dictionary to the dict_freqs argument to override default seasonal periods.

    from tsfeatures import tsfeatures

# Basic usage with inferred frequency
tsfeatures(panel)

# Usage with explicit frequency
tsfeatures(panel, freq=7)

# Usage with custom frequency dictionary
tsfeatures(panel, dict_freqs={'D': 7, 'W': 52})

  4. Call R implementation of tsfeatures from Python

    main

    If you have R installed along with the forecast and tsfeatures R packages, and the rpy2 Python package, you can call the original R implementation directly from Python using tsfeatures_r.

    Note: Unlike the Python implementation which takes a list of function objects, tsfeatures_r accepts a list of strings representing the feature names.

    from tsfeatures.tsfeatures_r import tsfeatures_r

# Note: features are passed as strings here
tsfeatures_r(panel, freq=7, features=["acf_features"])

  5. Calculate specific time series features

    main

    By default, tsfeatures() calculates a standard set of features. To use a specific subset, import the desired feature function and pass it in a list to the features argument.

    Available Features: acf_features, arch_stat, count_entropy, crossing_points, entropy, flat_spots, frequency, guerrero, heterogeneity, holt_parameters, hurst, hw_parameters, intervals, lumpiness, nonlinearity, pacf_features, series_length, sparsity, stability, stl_features, unitroot_kpss, unitroot_pp.

    from tsfeatures import tsfeatures, acf_features

# Calculate only acf_features
tsfeatures(panel, freq=7, features=[acf_features])

  6. Compare Python implementation with R implementation

    main

    You can run a comparison tool to check the sum of absolute differences between the Python and R implementations for specific datasets.

    Use the tsfeatures.compare_with_r module via the command line.

    # For Daily M4 time series
python -m tsfeatures.compare_with_r --results_directory /some/path --dataset_name Daily --num_obs 100

# For Hourly M4 time series
python -m tsfeatures.compare_with_r --results_directory /some/path --dataset_name Hourly --num_obs 100