mantis-tsfm 0.1.0__tar.gz

mantis_tsfm-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Vasilii Feofanov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mantis_tsfm-0.1.0/PKG-INFO

@@ -0,0 +1,204 @@
+Metadata-Version: 2.1
+Name: mantis-tsfm
+Version: 0.1.0
+Summary: Mantis: Lightweight Calibrated Foundation Model for User-Friendly Time Series Classification
+License: MIT
+Keywords: Time Series Foundation Model,Classification,Transformer
+Author: Vasilii Feofanov
+Author-email: vasilii.feofanov@huawei.com
+Maintainer: Vasilii Feofanov
+Maintainer-email: vasilii.feofanov@huawei.com
+Requires-Python: >=3.9,<4.0
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Dist: einops (>=0.8,<0.9)
+Requires-Dist: huggingface-hub (>=0.23,<0.24)
+Requires-Dist: numpy (>=1.23,<3.0)
+Requires-Dist: pandas (>=1.5,<3.0)
+Requires-Dist: safetensors (>=0.4,<0.5)
+Requires-Dist: scikit-learn (>=1.2,<2.0)
+Requires-Dist: torch (>=1.12,<3.0)
+Requires-Dist: tqdm (>=4.64,<5.0)
+Description-Content-Type: text/markdown
+
+# Mantis: Lightweight Calibrated Foundation Model for User-Friendly Time Series Classification
+
+<p align="center">
+  <img src="figures/mantis_logo_white_with_font.png" alt="Logo" height="300"/>
+</p>
+
+## Overview
+
+**Mantis** is an open-source time series classification foundation model implemented by [Huawei Noah's Ark Lab](https://huggingface.co/paris-noah).\
+The key features are:
+
+ - *Zero-shot feature extraction:* The model can be used in a frozen state to extract deep features and train a classifier on them.
+ - *Fine-tuning:* To achieve the highest performance, the model can be further fine-tuned for a new task.
+ - *Lightweight:* The model contains 8 million parameters, which allows it to be fine-tuned on a single GPU (even feasible on a CPU).
+ - *Calibration:* In our studies, we have shown that Mantis is the most calibrated foundation model for classification so far.
+ - *Adaptable to large-scale datasets:* For datasets with a large number of channels, we propose additional adapters that reduce memory requirements.
+
+<p align="center">
+  <img src="figures/zero-shot-exp-results.png" alt="Logo" height="300"/> 
+  
+  <img src="figures/fine-tuning-exp-results.png" alt="Logo" height="300"/>
+</p>
+
+Please find out technical report on [arXiv](https://arxiv.org/abs/2502.15637). Our pre-trained weights can be found on [Hugging Face](https://huggingface.co/paris-noah/Mantis-8M).
+Below we give instructions how the package can be installed and used.
+
+## Installation
+
+### Pip installation 
+
+> [!WARNING]
+> The package will be released to PyPI very soon. Meanwhile, please use editable mode intallation given below.
+> 
+
+```
+pip install mantis
+```
+
+### Editable mode using Poetry
+
+First, install Poetry and add the path to the binary file to your shell configuration file. 
+For example, on Linux systems, you can do this by running:
+```bash
+curl -sSL https://install.python-poetry.org | python3 -
+export PATH="/home/username/.local/bin:$PATH"
+```
+Now you can create a virtual environment that is based on one of your already installed Python interpreters.
+For example, if your default Python is 3.9, then create the environment by running:
+```bash
+poetry env use 3.9
+```
+Alternatively, you can specify a path to the interpreter. For example, to use an Anaconda Python interpreter:
+```bash
+poetry env use /path/to/anaconda3/envs/my_env/bin/python
+```
+If you want to run any command within the environment, instead of activating the environment manually, you can use `poetry run`:
+```bash
+poetry run <command>
+```
+For example, to install the dependencies and run tests:
+```bash
+poetry install
+poetry run pytest
+```
+If dependencies are not resolving correctly, try re-generating the lock file:
+```bash
+poetry lock
+poetry install
+```
+
+
+## Getting started
+
+Please refer to `getting_started/` folder to see reproducible examples of how the package can be used.
+
+Below we summarize the basic commands needed to use the package.
+
+### Initialization.
+
+To load our pre-trained model with 8M parameters from the Hugging Face, it is sufficient to run:
+
+``` python
+from mantis.architecture import Mantis8M
+
+network = Mantis8M(device='cuda')
+network = network.from_pretrained("paris-noah/Mantis-8M")
+```
+
+### Feature Extraction.
+
+We provide a scikit-learn-like wrapper `MantisTrainer` that allows to use Mantis as a feature extractor by running the following commands:
+
+``` python
+from mantis.trainer import MantisTrainer
+
+model = MantisTrainer(device='cuda', network=network)
+Z = model.transform(X) # X is your time series dataset
+```
+
+### Fine-tuning.
+
+If you want to fine-tune the model on your supervised dataset, you can use `fit` method of `MantisTrainer`:
+
+``` python
+from mantis.trainer import MantisTrainer
+
+model = MantisTrainer(device='cuda', network=network)
+model.fit(X, y) # y is a vector with class labels
+probs = model.predict_proba(X)
+y_pred = model.predict(X)
+```
+
+### Adapters.
+
+We have integrated into the framework the possibility to pass the input to an adapter before sending it to the foundation model. This may be useful for time series data sets with a large number of channels. More specifically, large number of channels may induce the curse of dimensionality or make model's fine-tuning unfeasible. 
+
+A straightforward way to overcome these issues is to use a dimension reduction approach like PCA:
+``` python
+from mantis.adapters import MultichannelProjector
+
+adapter = MultichannelProjector(new_num_channels=5, base_projector='pca')
+adapter.fit(X)
+X_transformed = adapter.transform(X)
+
+model = MantisTrainer(device='cuda', network=network)
+Z = model.transform(X_transformed)
+```
+
+Another wat is to add learnable layers before the foundation model and fine-tune them with the prediction head:
+``` python
+from mantis.adapters import LinearChannelCombiner
+
+model = MantisTrainer(device='cuda', network=network)
+adapter = LinearChannelCombiner(num_channels=X.shape[1], new_num_channels=5)
+model.fit(X, y, adapter=adapter, fine_tuning_type='adapter_head')
+```
+
+## Structure
+
+```
+├── data/                <-- two datasets for demonstration
+├── getting_started/     <-- jupyter notebooks with tutorials
+└── src/mantis/          <-- the main package
+    ├── adapters/        <-- adapters for multichannel time series
+    ├── architecture/    <-- foundation model architectures
+    └── trainer/         <-- a scikit-learn-like wrapper for feature extraction or fine-tuning
+```
+
+
+## License
+
+This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for more details.
+
+## Open-source Participation
+
+We would be happy to receive feedback and integrate any suggestion, so do not hesitate to contribute to this project by raising a GitHub issue or contacting us by email:
+
+ - Vasilii Feofanov - vasilii [dot] feofanov [at] huawei [dot] com
+
+
+## Citing Mantis 📚
+
+If you use Mantis in your work, please cite this technical report:
+
+```bibtex
+@article{feofanov2025mantis,
+  title={Mantis: Lightweight Calibrated Foundation Model for User-Friendly Time Series Classification},
+  author={Vasilii Feofanov and Songkang Wen and Marius Alonso and Romain Ilbert and Hongbo Guo and Malik Tiomoko and Lujia Pan and Jianfeng Zhang and Ievgen Redko},
+  journal={arXiv preprint arXiv:2502.15637},
+  year={2025},
+}
+```
+

mantis_tsfm-0.1.0/README.md

@@ -0,0 +1,172 @@
+# Mantis: Lightweight Calibrated Foundation Model for User-Friendly Time Series Classification
+
+<p align="center">
+  <img src="figures/mantis_logo_white_with_font.png" alt="Logo" height="300"/>
+</p>
+
+## Overview
+
+**Mantis** is an open-source time series classification foundation model implemented by [Huawei Noah's Ark Lab](https://huggingface.co/paris-noah).\
+The key features are:
+
+ - *Zero-shot feature extraction:* The model can be used in a frozen state to extract deep features and train a classifier on them.
+ - *Fine-tuning:* To achieve the highest performance, the model can be further fine-tuned for a new task.
+ - *Lightweight:* The model contains 8 million parameters, which allows it to be fine-tuned on a single GPU (even feasible on a CPU).
+ - *Calibration:* In our studies, we have shown that Mantis is the most calibrated foundation model for classification so far.
+ - *Adaptable to large-scale datasets:* For datasets with a large number of channels, we propose additional adapters that reduce memory requirements.
+
+<p align="center">
+  <img src="figures/zero-shot-exp-results.png" alt="Logo" height="300"/> 
+  
+  <img src="figures/fine-tuning-exp-results.png" alt="Logo" height="300"/>
+</p>
+
+Please find out technical report on [arXiv](https://arxiv.org/abs/2502.15637). Our pre-trained weights can be found on [Hugging Face](https://huggingface.co/paris-noah/Mantis-8M).
+Below we give instructions how the package can be installed and used.
+
+## Installation
+
+### Pip installation 
+
+> [!WARNING]
+> The package will be released to PyPI very soon. Meanwhile, please use editable mode intallation given below.
+> 
+
+```
+pip install mantis
+```
+
+### Editable mode using Poetry
+
+First, install Poetry and add the path to the binary file to your shell configuration file. 
+For example, on Linux systems, you can do this by running:
+```bash
+curl -sSL https://install.python-poetry.org | python3 -
+export PATH="/home/username/.local/bin:$PATH"
+```
+Now you can create a virtual environment that is based on one of your already installed Python interpreters.
+For example, if your default Python is 3.9, then create the environment by running:
+```bash
+poetry env use 3.9
+```
+Alternatively, you can specify a path to the interpreter. For example, to use an Anaconda Python interpreter:
+```bash
+poetry env use /path/to/anaconda3/envs/my_env/bin/python
+```
+If you want to run any command within the environment, instead of activating the environment manually, you can use `poetry run`:
+```bash
+poetry run <command>
+```
+For example, to install the dependencies and run tests:
+```bash
+poetry install
+poetry run pytest
+```
+If dependencies are not resolving correctly, try re-generating the lock file:
+```bash
+poetry lock
+poetry install
+```
+
+
+## Getting started
+
+Please refer to `getting_started/` folder to see reproducible examples of how the package can be used.
+
+Below we summarize the basic commands needed to use the package.
+
+### Initialization.
+
+To load our pre-trained model with 8M parameters from the Hugging Face, it is sufficient to run:
+
+``` python
+from mantis.architecture import Mantis8M
+
+network = Mantis8M(device='cuda')
+network = network.from_pretrained("paris-noah/Mantis-8M")
+```
+
+### Feature Extraction.
+
+We provide a scikit-learn-like wrapper `MantisTrainer` that allows to use Mantis as a feature extractor by running the following commands:
+
+``` python
+from mantis.trainer import MantisTrainer
+
+model = MantisTrainer(device='cuda', network=network)
+Z = model.transform(X) # X is your time series dataset
+```
+
+### Fine-tuning.
+
+If you want to fine-tune the model on your supervised dataset, you can use `fit` method of `MantisTrainer`:
+
+``` python
+from mantis.trainer import MantisTrainer
+
+model = MantisTrainer(device='cuda', network=network)
+model.fit(X, y) # y is a vector with class labels
+probs = model.predict_proba(X)
+y_pred = model.predict(X)
+```
+
+### Adapters.
+
+We have integrated into the framework the possibility to pass the input to an adapter before sending it to the foundation model. This may be useful for time series data sets with a large number of channels. More specifically, large number of channels may induce the curse of dimensionality or make model's fine-tuning unfeasible. 
+
+A straightforward way to overcome these issues is to use a dimension reduction approach like PCA:
+``` python
+from mantis.adapters import MultichannelProjector
+
+adapter = MultichannelProjector(new_num_channels=5, base_projector='pca')
+adapter.fit(X)
+X_transformed = adapter.transform(X)
+
+model = MantisTrainer(device='cuda', network=network)
+Z = model.transform(X_transformed)
+```
+
+Another wat is to add learnable layers before the foundation model and fine-tune them with the prediction head:
+``` python
+from mantis.adapters import LinearChannelCombiner
+
+model = MantisTrainer(device='cuda', network=network)
+adapter = LinearChannelCombiner(num_channels=X.shape[1], new_num_channels=5)
+model.fit(X, y, adapter=adapter, fine_tuning_type='adapter_head')
+```
+
+## Structure
+
+```
+├── data/                <-- two datasets for demonstration
+├── getting_started/     <-- jupyter notebooks with tutorials
+└── src/mantis/          <-- the main package
+    ├── adapters/        <-- adapters for multichannel time series
+    ├── architecture/    <-- foundation model architectures
+    └── trainer/         <-- a scikit-learn-like wrapper for feature extraction or fine-tuning
+```
+
+
+## License
+
+This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for more details.
+
+## Open-source Participation
+
+We would be happy to receive feedback and integrate any suggestion, so do not hesitate to contribute to this project by raising a GitHub issue or contacting us by email:
+
+ - Vasilii Feofanov - vasilii [dot] feofanov [at] huawei [dot] com
+
+
+## Citing Mantis 📚
+
+If you use Mantis in your work, please cite this technical report:
+
+```bibtex
+@article{feofanov2025mantis,
+  title={Mantis: Lightweight Calibrated Foundation Model for User-Friendly Time Series Classification},
+  author={Vasilii Feofanov and Songkang Wen and Marius Alonso and Romain Ilbert and Hongbo Guo and Malik Tiomoko and Lujia Pan and Jianfeng Zhang and Ievgen Redko},
+  journal={arXiv preprint arXiv:2502.15637},
+  year={2025},
+}
+```

mantis_tsfm-0.1.0/pyproject.toml

@@ -0,0 +1,54 @@
+[tool.poetry]
+name = "mantis-tsfm"
+version = "0.1.0"
+description = "Mantis: Lightweight Calibrated Foundation Model for User-Friendly Time Series Classification"
+authors = [
+    "Vasilii Feofanov <vasilii.feofanov@huawei.com>",
+    "Songkang Wen",
+    "Marius Alonso",
+    "Romain Ilbert",
+    "Hongbo Guo",
+    "Malik Tiomoko",
+    "Lujia Pan",
+    "Jianfeng Zhang",
+    "Ievgen Redko",
+]
+maintainers = [
+  "Vasilii Feofanov <vasilii.feofanov@huawei.com>",
+]
+license = "MIT"
+readme = "README.md"
+keywords = ["Time Series Foundation Model", "Classification", "Transformer"]
+classifiers = [
+  "Intended Audience :: Science/Research",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "License :: OSI Approved :: MIT License",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence"
+  
+]
+packages = [
+    { include = "mantis", from = "src" }
+]
+
+[tool.poetry.dependencies]
+python = "^3.9"
+einops = "^0.8"
+huggingface-hub = "^0.23"
+numpy = ">=1.23,<3.0"
+pandas = ">=1.5,<3.0"
+scikit-learn = "^1.2"
+torch = ">=1.12,<3.0"
+tqdm = "^4.64"
+safetensors = "^0.4"
+
+[tool.poetry.group.dev.dependencies]
+pytest = ">=7.1,<9.0"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"

mantis_tsfm-0.1.0/src/mantis/__init__.py

@@ -0,0 +1,7 @@
+"""Init file."""
+
+_submodules = [
+    "adapters",
+    "architecture",
+    "trainer",
+]

mantis_tsfm-0.1.0/src/mantis/adapters/__init__.py

@@ -0,0 +1,8 @@
+"""Init file for adapters.""" 
+
+from .projector import MultichannelProjector
+from .var_selector import VarianceBasedSelector
+from .diff_adapter import LinearChannelCombiner
+
+
+__all__ = ['MultichannelProjector', 'VarianceBasedSelector', 'LinearChannelCombiner']

mantis_tsfm-0.1.0/src/mantis/adapters/diff_adapter.py

@@ -0,0 +1,32 @@
+import torch
+
+from torch import nn
+
+
+class LinearChannelCombiner(nn.Module):
+    """
+    A differentiable adapter that implements a linear projector along the channel axis.
+    Given time series dataset with `num_channels`, it transforms it into a dataset with `new_num_channels`,
+    where each new channel is a linear combination of the original ones.
+    This adapter is a pytorch module, which can be trained together with the prediction head 
+    or during the full fine-tuning of Mantis.
+
+    Parameters
+    ----------
+    num_channels: int
+        The original number of channels in a time series dataset.
+    new_num_channels: int
+        The number of channels after transformation.
+    """
+    def __init__(self, num_channels, new_num_channels):
+        super().__init__()
+        self.num_channels = num_channels
+        self.new_num_channels = new_num_channels
+        self.transformation = nn.Linear(num_channels, new_num_channels)
+
+    def forward(self, x):
+        # transpose time and channel dimensions to apply linear layer
+        x_transposed = x.transpose(1, 2)
+        x_transformed = self.transformation(x_transposed)
+        # return the output transposing back the dimensions
+        return x_transformed.transpose(1, 2)

mantis_tsfm-0.1.0/src/mantis/adapters/projector.py

@@ -0,0 +1,60 @@
+import numpy as np
+
+from sklearn.decomposition import PCA, TruncatedSVD
+from sklearn.random_projection import SparseRandomProjection
+
+
+class MultichannelProjector:
+    """
+    A generic class to use various scikit-learn dimension reduction methods to reduce 
+    the number of channels in a multichannel time series dataset.
+    
+    Parameters
+    ----------
+    new_num_channels : int
+        The number of channels after projection.
+    patch_window_size : int, default=1
+        The size of the patch window. By default, it is equal to 1, i.e., no patching.
+    base_projector : str or object, default=None
+        The base projector to use. Can be 'pca', 'svd', 'rand', or a custom projector that accepts
+        `n_components` at the initialization and has `fit` and `transform` methods.
+    """
+    def __init__(self, new_num_channels, patch_window_size=1, base_projector=None):
+        # init dimensions
+        self.new_num_channels = new_num_channels
+        self.patch_window_size = patch_window_size
+        # init base projector 
+        self.base_projector = base_projector
+        n_components = patch_window_size * new_num_channels
+        if base_projector in [None, 'pca']:
+            self.base_projector_ = PCA(n_components=n_components)
+        elif base_projector == 'svd':
+            self.base_projector_ = TruncatedSVD(n_components=n_components)
+        elif base_projector == 'rand':
+            self.base_projector_ = SparseRandomProjection(n_components=n_components)
+        # you can give your own base_projector with fit() and transform() methods, and it should have the argument `n_components`.
+        else:
+            self.base_projector_ = base_projector(n_components=n_components)
+
+    def fit(self, x):
+        x_transposed = np.swapaxes(x, 1, 2)
+        
+        num_samples, seq_len, num_channels = x_transposed.shape
+        num_patches = seq_len // self.patch_window_size
+        assert num_patches * self.patch_window_size == seq_len
+
+        x_2d = x_transposed.reshape(num_samples * num_patches, self.patch_window_size * num_channels)
+        return self.base_projector_.fit(x_2d)
+
+    def transform(self, x):
+        x_transposed = np.swapaxes(x, 1, 2)
+
+        num_samples, seq_len, num_channels = x_transposed.shape
+        num_patches = seq_len // self.patch_window_size
+        assert num_patches * self.patch_window_size == seq_len
+
+        x_2d = x_transposed.reshape(num_samples * num_patches, self.patch_window_size * num_channels)
+
+        x_transformed = self.base_projector_.transform(x_2d)
+        x_transformed = x_transformed.reshape([num_samples, seq_len, self.new_num_channels])
+        return np.swapaxes(x_transformed, 1, 2)

mantis_tsfm-0.1.0/src/mantis/adapters/var_selector.py

@@ -0,0 +1,38 @@
+import numpy as np
+
+
+class VarianceBasedSelector:
+    """
+    Perform a filter feature selection approach to reduce the number of channels in a multichannel time series data set.
+    More specifically, it selects those channels that have the highest variance.
+
+    Parameters
+    ----------
+    new_num_channels: int 
+        The number of selected channels.
+    """
+    def __init__(self, new_num_channels):
+        self.new_num_channels = new_num_channels
+        self.support_ = None
+        
+    def fit(self, x):
+        # flatten the tensor to 2D
+        x_transposed = np.swapaxes(x, 1, 2)
+        num_samples, seq_len, num_channels = x_transposed.shape
+        x_2d = x_transposed.reshape(num_samples * seq_len, num_channels)
+
+        # calculate variances and select top features
+        variances = np.var(x_2d, axis=0)
+        
+        # select top features by variance
+        self.support_ = np.argsort(variances)[::-1][:self.new_num_channels]
+        return self.support_
+
+    def transform(self, x):
+        if self.support_ is None:
+            raise RuntimeError("You must call fit at least once before calling transform.")
+
+        # select features based on precomputed indices
+        selected_features = x[:, self.support_, :]
+
+        return selected_features

mantis_tsfm-0.1.0/src/mantis/architecture/__init__.py

@@ -0,0 +1,6 @@
+"""Init file for architecture.""" 
+
+from .architecture import Mantis8M
+
+
+__all__ = ['Mantis8M']