Update README.md

README.md

@@ -1,13 +1,143 @@
 ---
 license: mit
-library_name: mantis
-tags:
-- time-series-foundation-model
-- pytorch_model_hub_mixin
-- model_hub_mixin
-pipeline_tag: time-series-foundation-model
 ---
 
-This model has been pushed to the Hub using the [PytorchModelHubMixin](https://huggingface.co/docs/huggingface_hub/package_reference/mixins#huggingface_hub.PyTorchModelHubMixin) integration:
-- Library: https://huggingface.co/paris-noah/Mantis-8M/tree/main
-- Docs: [More Information Needed]
+# Mantis: Lightweight Calibrated Foundation Model for User-Friendly Time Series Classification
+
+<p align="center">
+  <img src="https://github.com/vfeofanov/mantis/blob/main/figures/mantis_logo_white_with_font.png" alt="Logo" height="300"/>
+</p>
+
+## Overview
+
+**MANTIS** is an open-source python package with a pre-trained time series classification foundation model implemented by Huawei Noah's Ark Lab.
+
+This is a repository the model checkpoint. Please refer to the [GitHub](https://github.com/vfeofanov/mantis/tree/main) repository of the package and 
+the technical report on arxiv for more details.
+
+## 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/`](https://github.com/vfeofanov/mantis/tree/main/getting_started) 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 from the HuggingFace, 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')
+```
+
+## Citing Mantis 📚
+
+If you use Mantis in your work, please cite this technical report:
+
+```bibtex
+@misc{feofanov2024mantis,
+      title={TODO}, 
+      author={TODO},
+      year={2024},
+      eprint={TODO},
+      archivePrefix={arXiv},
+      primaryClass={stat.ML},
+      url={TODO}, 
+}
+```