Metadata-Version: 2.4
Name: hypertrees-forecasting
Version: 0.1.0
Summary: Forecasting with Hyper-Trees
Author-email: Alexander März <statmixedmlgit@gmail.com>, Kashif Rasul <rasul.kashif@morganstanley.com>
Maintainer-email: Alexander März <statmixedmlgit@gmail.com>
License: Commons Clause License Condition v1.0
        
        The Software is provided to you by the Licensor under the License, as
        defined below, subject to the following condition.
        
        Without limiting other conditions in the License, the grant of rights
        under the License will not include, and the License does not grant to
        you, the right to Sell the Software.
        
        For purposes of the foregoing, "Sell" means practicing any or all of
        the rights granted to you under the License to provide to third
        parties, for a fee or other consideration, a product or service whose
        value derives, entirely or substantially, from the functionality of
        the Software. For the avoidance of doubt, consulting or support
        services where the Software is a tool rather than the delivered
        product are not considered "Sell" under this condition.
        
        For clarity: You MAY use the Software for research, academic,
        testing, and production purposes, including for internal commercial
        use and integration into larger products or services, as long as you
        are not selling access to the Software's functionality itself as a
        primary offering (e.g., as an API service, managed service, or hosted
        offering where the Software provides the primary value).
        
        Any license notice or attribution required by the License must also
        include this Commons Clause License Condition notice.
        
        Software: Hyper-Trees
        
        License: Apache License 2.0
        
        Licensor: Alexander März
        
        ---
        
                                      Apache License
                                Version 2.0, January 2004
                             http://www.apache.org/licenses/
        
        TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
        
        1. Definitions.
        
        "License" shall mean the terms and conditions for use, reproduction,
        and distribution as defined by Sections 1 through 9 of this document,
        together with the Commons Clause License Condition set forth above.
        
        "Licensor" shall mean the copyright owner or entity authorized by the
        copyright owner that is granting the License.
        
        "Legal Entity" shall mean the union of the acting entity and all other
        entities that control, are controlled by, or are under common control
        with that entity. For the purposes of this definition, "control" means
        (i) the power, direct or indirect, to cause the direction or
        management of such entity, whether by contract or otherwise, or (ii)
        ownership of fifty percent (50%) or more of the outstanding shares, or
        (iii) beneficial ownership of such entity.
        
        "You" (or "Your") shall mean an individual or Legal Entity exercising
        permissions granted by this License.
        
        "Source" form shall mean the preferred form for making modifications,
        including but not limited to software source code, documentation
        source, and configuration files.
        
        "Object" form shall mean any form resulting from mechanical
        transformation or translation of a Source form, including but not
        limited to compiled object code, generated documentation, and
        conversions to other media types.
        
        "Work" shall mean the work of authorship, whether in Source or Object
        form, made available under the License, as indicated by a copyright
        notice that is included in or attached to the work.
        
        "Derivative Works" shall mean any work, whether in Source or Object
        form, that is based on (or derived from) the Work and for which the
        editorial revisions, annotations, elaborations, or other modifications
        represent, as a whole, an original work of authorship. For the
        purposes of this License, Derivative Works shall not include works
        that remain separable from, or merely link (or bind by name) to the
        interfaces of, the Work and Derivative Works thereof.
        
        "Contribution" shall mean any work of authorship, including the
        original version of the Work and any modifications or additions to
        that Work or Derivative Works thereof, that is intentionally submitted
        to the Licensor for inclusion in the Work by the copyright owner or by
        an individual or Legal Entity authorized to submit on behalf of the
        copyright owner. For the purposes of this definition, "submitted"
        means any form of electronic, verbal, or written communication sent to
        the Licensor or its representatives, including but not limited to
        communication on electronic mailing lists, source code control
        systems, and issue tracking systems that are managed by, or on behalf
        of, the Licensor for the purpose of discussing and improving the Work,
        but excluding communication that is conspicuously marked or otherwise
        designated in writing by the copyright owner as "Not a Contribution."
        
        "Contributor" shall mean Licensor and any individual or Legal Entity on
        behalf of whom a Contribution has been received by the Licensor and
        subsequently incorporated within the Work.
        
        2. Grant of Copyright License. Subject to the terms and conditions of
        this License (including the Commons Clause License Condition), each
        Contributor hereby grants to You a perpetual, worldwide,
        non-exclusive, no-charge, royalty-free, irrevocable copyright license
        to reproduce, prepare Derivative Works of, publicly display, publicly
        perform, sublicense, and distribute the Work and such Derivative Works
        in Source or Object form.
        
        3. Grant of Patent License. Subject to the terms and conditions of
        this License (including the Commons Clause License Condition), each
        Contributor hereby grants to You a perpetual, worldwide,
        non-exclusive, no-charge, royalty-free, irrevocable (except as stated
        in this section) patent license to make, have made, use, offer to
        sell, sell, import, and otherwise transfer the Work, where such
        license applies only to those patent claims licensable by such
        Contributor that are necessarily infringed by their Contribution(s)
        alone or by combination of their Contribution(s) with the Work to
        which such Contribution(s) was submitted. If You institute patent
        litigation against any entity (including a cross-claim or counterclaim
        in a lawsuit) alleging that the Work or a Contribution incorporated
        within the Work constitutes direct or contributory patent
        infringement, then any patent licenses granted to You under this
        License for that Work shall terminate as of the date such litigation
        is filed.
        
        4. Redistribution. You may reproduce and distribute copies of the Work
        or Derivative Works thereof in any medium, with or without
        modifications, and in Source or Object form, provided that You meet
        the following conditions:
        
        (a) You must give any other recipients of the Work or Derivative Works
            a copy of this License (including the Commons Clause License
            Condition); and
        
        (b) You must cause any modified files to carry prominent notices
            stating that You changed the files; and
        
        (c) You must retain, in the Source form of any Derivative Works that
            You distribute, all copyright, patent, trademark, and attribution
            notices from the Source form of the Work, excluding those notices
            that do not pertain to any part of the Derivative Works; and
        
        (d) If the Work includes a "NOTICE" text file as part of its
            distribution, then any Derivative Works that You distribute must
            include a readable copy of the attribution notices contained
            within such NOTICE file, excluding any notices that do not pertain
            to any part of the Derivative Works, in at least one of the
            following places: within a NOTICE text file distributed as part of
            the Derivative Works; within the Source form or documentation, if
            provided along with the Derivative Works; or, within a display
            generated by the Derivative Works, if and wherever such
            third-party notices normally appear. The contents of the NOTICE
            file are for informational purposes only and do not modify the
            License. You may add Your own attribution notices within Derivative
            Works that You distribute, alongside or as an addendum to the
            NOTICE text from the Work, provided that such additional
            attribution notices cannot be construed as modifying the License.
        
        You may add Your own copyright statement to Your modifications and may
        provide additional or different license terms and conditions for use,
        reproduction, or distribution of Your modifications, or for any such
        Derivative Works as a whole, provided Your use, reproduction, and
        distribution of the Work otherwise complies with the conditions stated
        in this License (including the Commons Clause License Condition).
        
        5. Submission of Contributions. Unless You explicitly state otherwise,
        any Contribution intentionally submitted for inclusion in the Work by
        You to the Licensor shall be under the terms and conditions of this
        License, without any additional terms or conditions. Notwithstanding
        the above, nothing herein shall supersede or modify the terms of any
        separate license agreement you may have executed with Licensor
        regarding such Contributions.
        
        6. Trademarks. This License does not grant permission to use the trade
        names, trademarks, service marks, or product names of the Licensor,
        except as required for reasonable and customary use in describing the
        origin of the Work and reproducing the content of the NOTICE file.
        
        7. Disclaimer of Warranty. Unless required by applicable law or agreed
        to in writing, Licensor provides the Work (and each Contributor
        provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR
        CONDITIONS OF ANY KIND, either express or implied, including, without
        limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT,
        MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely
        responsible for determining the appropriateness of using or
        redistributing the Work and assume any risks associated with Your
        exercise of permissions under this License.
        
        8. Limitation of Liability. In no event and under no legal theory,
        whether in tort (including negligence), contract, or otherwise, unless
        required by applicable law (such as deliberate and grossly negligent
        acts) or agreed to in writing, shall any Contributor be liable to You
        for damages, including any direct, indirect, special, incidental, or
        consequential damages of any character arising as a result of this
        License or out of the use or inability to use the Work (including but
        not limited to damages for loss of goodwill, work stoppage, computer
        failure or malfunction, or any and all other commercial damages or
        losses), even if such Contributor has been advised of the possibility
        of such damages.
        
        9. Accepting Warranty or Additional Liability. While redistributing
        the Work or Derivative Works thereof, You may choose to offer, and
        charge a fee for, acceptance of support, warranty, indemnity, or other
        liability obligations and/or rights consistent with this License
        (including the Commons Clause License Condition). However, in
        accepting such obligations, You may act only on Your own behalf and on
        Your sole responsibility, not on behalf of any other Contributor, and
        only if You agree to indemnify, defend, and hold each Contributor
        harmless for any liability incurred by, or claims asserted against,
        such Contributor by reason of your accepting any such warranty or
        additional liability.
        
        END OF TERMS AND CONDITIONS
        
        Copyright 2026 Alexander März
        
        Licensed under the Apache License, Version 2.0, with Commons Clause
        License Condition v1.0 (the "License"); you may not use this file
        except in compliance with the License. You may obtain a copy of the
        License at
        
            http://www.apache.org/licenses/LICENSE-2.0
        
        Unless required by applicable law or agreed to in writing, software
        distributed under the License is distributed on an "AS IS" BASIS,
        WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
        implied. See the License for the specific language governing
        permissions and limitations under the License.
Project-URL: Repository, https://github.com/StatMixedML/Hyper-Trees
Project-URL: Issues, https://github.com/StatMixedML/Hyper-Trees/issues
Project-URL: Discussions, https://github.com/StatMixedML/Hyper-Trees/discussions
Project-URL: Documentation, https://github.com/StatMixedML/Hyper-Trees#readme
Keywords: Gradient Boosted Trees,Hyper Models,Hybrid Models,Machine Learning,Time Series Forecasting,Time-Varying Parameters
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Requires-Python: <3.13,>=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: lightgbm>=4.6
Requires-Dist: numpy>=2.0
Requires-Dist: pandas>=2.3
Requires-Dist: torch<2.10,>=2
Provides-Extra: extras
Requires-Dist: matplotlib>=3.10; extra == "extras"
Requires-Dist: shap<0.51,>=0.48; extra == "extras"
Requires-Dist: optuna>=4; extra == "extras"
Provides-Extra: docs
Requires-Dist: mkdocs; extra == "docs"
Requires-Dist: mkdocstrings[python]; extra == "docs"
Requires-Dist: mkdocs-jupyter; extra == "docs"
Requires-Dist: mkdocs-material; extra == "docs"
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: pytest-cov; extra == "test"
Requires-Dist: pytest-mock; extra == "test"
Requires-Dist: coverage; extra == "test"
Requires-Dist: flake8; extra == "test"
Provides-Extra: dev
Requires-Dist: hypertrees-forecasting[test]; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: isort; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Requires-Dist: pre-commit; extra == "dev"
Dynamic: license-file

<h4 align="center">

|                      | **[Release Notes](https://github.com/StatMixedML/Hyper-Trees/releases)** |
|----------------------|---|
| **Open&#160;Source** | [![License: Apache 2.0 + Commons Clause](https://img.shields.io/badge/License-Apache_2.0_with_Commons_Clause-yellow.svg)](LICENSE) |
| **CI/CD**            | [![github-actions](https://img.shields.io/github/actions/workflow/status/StatMixedML/Hyper-Trees/unit-tests.yml?logo=github)](https://github.com/StatMixedML/Hyper-Trees/actions/workflows/unit-tests.yml) |
| **Code**             | [![!python-versions](https://img.shields.io/pypi/pyversions/hypertrees-forecasting)](https://www.python.org/) <img src="https://codecov.io/gh/StatMixedML/Hyper-Trees/branch/main/graph/badge.svg" alt="Code coverage status badge"> |
| **Downloads**        | ![Pepy Total Downloads](https://img.shields.io/pepy/dt/hypertrees-forecasting?label=PyPI%20Downloads&color=green) |
| **Paper**            | [![Arxiv link](https://img.shields.io/badge/arXiv-Forecasting%20with%20Hyper--Trees-color=brightgreen)](https://arxiv.org/pdf/2405.07836) |

</h4>

---
# Overview

Hyper-Trees are a novel framework for modeling time series data with gradient boosted trees (GBDTs). Instead of forecasting time series directly, Hyper-Trees use GBDTs to learn the parameters of a classical time series model such as ARIMA or Exponential Smoothing as functions of features. The target time series model then generates the final forecasts. This naturally injects the inductive bias of forecasting models into tree-based learning. 
While our framework is built upon the well-established LightGBM model, it can in principle be used with any modern GBDT framework.



<div align="center">
  <img src="hypertrees/hyper_treenet.png" width="70%" alt="Hyper-Tree architecture">
</div>

Hyper-Trees offer several advantages:

- **Improved Extrapolation in Tree-Based Models.** Forecasts are generated via a parametric target time series model, rather than the piece-wise constant output of tree-models.
- **Cross-Series Learning with Local Adaptivity.** A global GBDT learns the feature-to-parameter mapping, so similar series share information while each still receives its own parameters.
- **Time-Varying Parameters.** Coefficients vary cross-sectionally (series-specific features such as store type or region) and temporally (day, week, month, year, ...), capturing effects such as distinct AR(p) dynamics on weekdays versus weekends.
- **Model Transparency and Interpretability.** Forecasts are produced by classical time series models whose parameters retain clear statistical meaning.
- **Full Functionality of GBDTs.** Core GBDT capabilities (missing-value handling, feature importance, categorical support, monotonicity constraints) carry over unchanged.

---

# News
[2024-05-01] Create repository and initial commits.

---

## Available Models

| Model | Description | Scope |
| :--- | :--- | :---: |
| **`Hyper-Tree-AR`** | Autoregressive model with tree-learned, time-varying AR(p) parameters. | ![](https://img.shields.io/badge/Global-blue) ![](https://img.shields.io/badge/Local-green) |
| **`Hyper-TreeNet-AR`** | Hybrid model combining tree embeddings with a neural network to learn AR(p) parameters. | ![](https://img.shields.io/badge/Global-blue) ![](https://img.shields.io/badge/Local-green) |
| **`Hyper-Tree-ETS`** | Exponential smoothing model where ETS parameters are estimated by trees. | ![](https://img.shields.io/badge/Global-blue) ![](https://img.shields.io/badge/Local-green) |
| **`Hyper-Tree-STL`** | STL decomposition with tree-learned parameters for trend and seasonality. | ![](https://img.shields.io/badge/Local-green) |

`Global` means a single model is trained across multiple time series; `Local` means a separate model is trained for each individual series.
All models currently provide point forecasts only. Probabilistic forecasting is planned for future releases. Note on `Hyper-Tree-STL`: it is designed to decompose time series into trend and seasonal components and is not intended for forecasting. However, the STL-parameters can still be used to generate forecasts.

# Getting Started

We refer to the `examples/` notebooks for quick-start guides on using the Hyper-Tree models.

---



# Installation

To run the `Hyper-TreeNet-AR` model efficiently, we recommend installing PyTorch with CUDA support. While GPU is recommended for faster runtime, it is not strictly required. All models also run on CPU. We use `uv pip` for installs. If you don't have `uv`, consider installing it or simply replace `uv pip install` with `pip install`.

### Basic Installation (CPU)

Install the latest release from PyPI:

```bash
uv pip install hypertrees-forecasting
```

Or install the development version directly from GitHub:

```bash
uv pip install git+https://github.com/StatMixedML/Hyper-Trees.git
```

Or clone the repository and install in editable mode for development:

```bash
git clone https://github.com/StatMixedML/Hyper-Trees.git
cd Hyper-Trees
uv pip install -e .
```

This installs Hyper-Trees with the latest compatible versions of all dependencies, including a CPU-compatible version of PyTorch. All models will work, just without GPU acceleration.

### Optional: Extra Dependencies

The example notebooks under `examples/` use `matplotlib` (plotting), `shap` (feature-importance visualization), and `optuna` (hyper-parameter optimization). To install these alongside the package, use the `extras` option:

```bash
uv pip install "hypertrees-forecasting[extras]"     # from PyPI
uv pip install -e ".[extras]"                       # editable / development
```

These packages are not required to use the Hyper-Tree models themselves, only to run the example notebooks.

### GPU Support

For CUDA-enabled PyTorch, install Hyper-Trees first, then install PyTorch from its CUDA index:

```bash
uv pip install torch --index-url https://download.pytorch.org/whl/cu121 --upgrade
```

Replace `cu121` with the variant matching your driver. See [pytorch.org/get-started/locally](https://pytorch.org/get-started/locally/) for the current list.

# Reproducing Paper Results

The full reproducibility package, including the pinned environment, datasets, configurations, and experiment notebooks needed to reproduce all paper results, lives in the [`experiments/`](experiments/) folder. See the [Experiments README](experiments/README.md) for installation instructions and step-by-step guidance on running the experiments.

---

# Early-stage software
`hypertrees-forecasting` is in an early stage of development and is provided *“as is”*, without any warranty or guarantee. We welcome bug reports, feature requests, and pull requests, and encourage feedback by opening a [new discussion](https://github.com/StatMixedML/Hyper-Trees/discussions). We strongly recommend thorough testing and validation before using the package in production or other critical applications.

---

# Acknowledgments

This work draws on and integrates methods and implementations from the following key repositories:

- [**<u>LightGBM</u>**](https://github.com/microsoft/LightGBM) – Gradient boosting framework for efficient tree-based learning.  
- [**<u>PyTorch</u>**](https://github.com/pytorch/pytorch) – Deep learning framework for tensor computation and neural network modeling.  
- [**<u>Nixtla</u>**](https://github.com/Nixtla) – Open Source Time Series Ecosystem.  
- [**<u>sktime</u>**](https://github.com/sktime/sktime) – A unified framework for machine learning with time series.
- [**<u>GluonTS</u>**](https://github.com/awslabs/gluonts) – Probabilistic time series modeling and forecasting with deep learning.  
---

## License

This project is licensed under the Apache License 2.0 with Commons Clause License Condition v1.0. In short, the code is free for research, academic, testing, production, and internal commercial use; selling access to the Software's functionality as a primary offering (e.g., as an API service, managed service, or hosted offering) requires a separate commercial license. See the [LICENSE](LICENSE) file for details.

---

## Citation

If you use `Hyper-Trees` in your research, please cite our paper:

[![Arxiv link](https://img.shields.io/badge/arXiv-Forecasting%20with%20Hyper--Trees-color=brightgreen)](https://arxiv.org/pdf/2405.07836) <br/>

```bibtex
@article{maerz2024hypertrees,
  title   = {Forecasting with Hyper-Trees},
  author  = {März, Alexander and Rasul, Kashif},
  journal = {arXiv preprint arXiv:2405.07836},
  year    = {2024}
}
```
