hypertrees-forecasting 0.1.0__tar.gz

hypertrees_forecasting-0.1.0/LICENSE

@@ -0,0 +1,228 @@
+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.

hypertrees_forecasting-0.1.0/PKG-INFO

@@ -0,0 +1,427 @@
+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}
+}
+```