# tisc: pytorch-time-series-classification
[](https://badge.fury.io/py/tisc)
[](https://pepy.tech/project/tisc)
[](https://pepy.tech/project/tisc)
[](https://pepy.tech/project/tisc)
Simple model creation and training framework for <b>ti</b>me <b>s</b>eries <b>c</b>lassification in Pytorch.
## What can you do with tisc?
<b>`tisc` is a simple framework for time series classification in Pytorch.</b>
- You can create a Pytorch model for time series classification with just one function.
- You can choose the model from many supported models.
- You can train the model with just one method.
- You can evaluate or predict with the trained model with just one method.
## Setup
### 1. Install tisc
```bash
pip install tisc
```
### 2. Install Pytorch
If Pytorch is not installed to your environment, you have to install Pytorch that matches your environment from the official website: [https://pytorch.org/get-started/locally/](https://pytorch.org/get-started/locally/)
example (this command is for my environment):
```bash
pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118
```
## Usage
### 0. Prepare the dataset / dataloader
#### Time series data
The time series data should be a 3D tensor with the shape of `(number_of_samples, timestep, dimentions)`.
For example, if you have a dataset with 1000 samples, each sample has 20 timesteps, and each timestep has 100 dimentions, the shape of the dataset should be `(1000, 20, 100)`.
The label should be a 1D tensor with the shape of `(number_of_samples,)`.
For example, if you have a dataset with 1000 samples, the shape of the label should be `(1000,)`.
```python
import torch
# The shape of the time series data should be (number_of_samples, timestep, dimentions)
print(train_data.shape) # (1000, 20, 100)
# The shape of the label should be (number_of_samples,)
print(train_label.shape) # (1000,)
```
#### Dataset
`tisc` supports the dataset that is a subclass of `torch.utils.data.Dataset`.
The dataset should return a tuple of `(data, label)` in the `__getitem__` method.
You can use `TensorDataset` from `torch.utils.data` to create a dataset from the time series data and the label easily.
```python
import torch
from torch.utils.data import TensorDataset
# Prepare the dataset with TensorDataset
train_dataset = TensorDataset(train_data, train_label)
val_dataset = TensorDataset(val_data, val_label)
test_dataset = TensorDataset(test_data, test_label)
# Check the type of the dataset
print(type(train_dataset)) # <class 'torch.utils.data.dataset.TensorDataset'>
```
#### Dataloader
You have to use `torch.utils.data.DataLoader` to load the dataset.
```python
import torch
from torch.utils.data import DataLoader
# Prepare the dataset
train_loader = DataLoader(train_dataset, batch_size=512, shuffle=True)
val_loader = DataLoader(val_dataset, batch_size=512, shuffle=False)
test_loader = DataLoader(test_dataset, batch_size=512, shuffle=False)
# Check the type of the dataloader
print(type(train_loader)) # <class 'torch.utils.data.dataloader.DataLoader'>
```
### 1. Create a classifier
You can create a classifier with the `build_classifier` function.
The `build_classifier` function returns a `tisc.Classifier` object.
A `Classifier` object contains the model, the optimizer, the loss function, and the training and evaluation methods.
When you create a classifier, you have to pass the following arguments:
- `model_name`: The name of the model. The model should be one of the supported models. (e.g., `'LSTM'`, `'BiLSTM'`, `'Transformer'`)
- `timestep`: The number of timesteps in the time series data.
- `dimentions`: The number of dimentions in each timestep.
- `num_classes`: The number of classes in the dataset.
```python
import tisc
# Create a classifier
classifier = tisc.build_classifier(model_name='LSTM',
timestep=20,
dimentions=100,
num_classes=10)
# Check the type of the classifier
print(type(classifier)) # <class 'tisc.Classifier'>
```
### 2. Train the classifier
You can train the classifier with the `train` method.
The `train` method requires the following arguments:
- `epochs`: The number of epochs to train the classifier.
- `train_loader`: The dataloader for the training dataset.
you can pass `val_loader` to train the classifier with validation.
```python
classifier.train(train_loader, epochs=100)
# If the `val_loader` argument is passed, you can train the classifier with validation.
classifier.train(train_loader, val_loader=val_loader, epochs=100)
```
### 3. Evaluate the classifier
You can evaluate the classifier with the `evaluate` method.
The `evaluate` method requires the following arguments:
- `test_loader`: The dataloader for the test dataset.
The `evaluate` method can return the classification report and the confusion matrix if you pass the `return_report` and `return_confusion_matrix` arguments as `True`.
If `with_best_model` argument is `True`, the classifier will use the best model that marked the best result about the model saving strategy.
```python
classifier.evaluate(test_loader,
return_report=True,
return_confusion_matrix=True,
with_best_model=True)
```
## Supported models
The models that can be used in version 0.1.0:
- LSTM
- BiLSTM
- Transformer
and more! (More models will be added.)
Raw data
{
"_id": null,
"home_page": "https://github.com/Yutsuro/pytorch-time-series-classification",
"name": "tisc",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "Pytorch Time-Series-Classification LSTM BiLSTM Transformer Machine-Learning Deep-Learning AI Artificial-Intelligence",
"author": "Yutsuro",
"author_email": "Yuki@utsu.ro",
"download_url": "https://files.pythonhosted.org/packages/c9/ee/bf07aafd3577440177afa7ce3767bc1ec2bd32914cb6af934d42049c4ac1/tisc-0.1.0.tar.gz",
"platform": null,
"description": "# tisc: pytorch-time-series-classification\r\n\r\n\r\n\r\n[](https://badge.fury.io/py/tisc)\r\n\r\n[](https://pepy.tech/project/tisc)\r\n\r\n[](https://pepy.tech/project/tisc)\r\n\r\n[](https://pepy.tech/project/tisc)\r\n\r\n\r\n\r\nSimple model creation and training framework for <b>ti</b>me <b>s</b>eries <b>c</b>lassification in Pytorch.\r\n\r\n\r\n\r\n## What can you do with tisc?\r\n\r\n\r\n\r\n<b>`tisc` is a simple framework for time series classification in Pytorch.</b>\r\n\r\n\r\n\r\n- You can create a Pytorch model for time series classification with just one function.\r\n\r\n- You can choose the model from many supported models.\r\n\r\n- You can train the model with just one method.\r\n\r\n- You can evaluate or predict with the trained model with just one method.\r\n\r\n\r\n\r\n## Setup\r\n\r\n\r\n\r\n### 1. Install tisc\r\n\r\n```bash\r\n\r\npip install tisc\r\n\r\n```\r\n\r\n\r\n\r\n### 2. Install Pytorch\r\n\r\n\r\n\r\nIf Pytorch is not installed to your environment, you have to install Pytorch that matches your environment from the official website: [https://pytorch.org/get-started/locally/](https://pytorch.org/get-started/locally/)\r\n\r\n\r\n\r\nexample (this command is for my environment):\r\n\r\n```bash\r\n\r\npip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118\r\n\r\n```\r\n\r\n\r\n\r\n## Usage\r\n\r\n\r\n\r\n### 0. Prepare the dataset / dataloader\r\n\r\n\r\n\r\n#### Time series data\r\n\r\n\r\n\r\nThe time series data should be a 3D tensor with the shape of `(number_of_samples, timestep, dimentions)`.\r\n\r\n\r\n\r\nFor example, if you have a dataset with 1000 samples, each sample has 20 timesteps, and each timestep has 100 dimentions, the shape of the dataset should be `(1000, 20, 100)`.\r\n\r\n\r\n\r\nThe label should be a 1D tensor with the shape of `(number_of_samples,)`.\r\n\r\n\r\n\r\nFor example, if you have a dataset with 1000 samples, the shape of the label should be `(1000,)`.\r\n\r\n\r\n\r\n```python\r\n\r\nimport torch\r\n\r\n\r\n\r\n# The shape of the time series data should be (number_of_samples, timestep, dimentions)\r\n\r\nprint(train_data.shape) # (1000, 20, 100)\r\n\r\n\r\n\r\n# The shape of the label should be (number_of_samples,)\r\n\r\nprint(train_label.shape) # (1000,)\r\n\r\n```\r\n\r\n\r\n\r\n#### Dataset\r\n\r\n\r\n\r\n`tisc` supports the dataset that is a subclass of `torch.utils.data.Dataset`. \r\n\r\n\r\n\r\nThe dataset should return a tuple of `(data, label)` in the `__getitem__` method.\r\n\r\n\r\n\r\nYou can use `TensorDataset` from `torch.utils.data` to create a dataset from the time series data and the label easily.\r\n\r\n\r\n\r\n```python\r\n\r\nimport torch\r\n\r\nfrom torch.utils.data import TensorDataset\r\n\r\n\r\n\r\n# Prepare the dataset with TensorDataset\r\n\r\ntrain_dataset = TensorDataset(train_data, train_label)\r\n\r\nval_dataset = TensorDataset(val_data, val_label)\r\n\r\ntest_dataset = TensorDataset(test_data, test_label)\r\n\r\n\r\n\r\n# Check the type of the dataset\r\n\r\nprint(type(train_dataset)) # <class 'torch.utils.data.dataset.TensorDataset'>\r\n\r\n```\r\n\r\n\r\n\r\n#### Dataloader\r\n\r\n\r\n\r\nYou have to use `torch.utils.data.DataLoader` to load the dataset.\r\n\r\n\r\n\r\n```python\r\n\r\nimport torch\r\n\r\nfrom torch.utils.data import DataLoader\r\n\r\n\r\n\r\n# Prepare the dataset\r\n\r\ntrain_loader = DataLoader(train_dataset, batch_size=512, shuffle=True)\r\n\r\nval_loader = DataLoader(val_dataset, batch_size=512, shuffle=False)\r\n\r\ntest_loader = DataLoader(test_dataset, batch_size=512, shuffle=False)\r\n\r\n\r\n\r\n# Check the type of the dataloader\r\n\r\nprint(type(train_loader)) # <class 'torch.utils.data.dataloader.DataLoader'>\r\n\r\n```\r\n\r\n### 1. Create a classifier\r\n\r\n\r\n\r\nYou can create a classifier with the `build_classifier` function.\r\n\r\n\r\n\r\nThe `build_classifier` function returns a `tisc.Classifier` object.\r\n\r\n\r\n\r\nA `Classifier` object contains the model, the optimizer, the loss function, and the training and evaluation methods.\r\n\r\n\r\n\r\nWhen you create a classifier, you have to pass the following arguments:\r\n\r\n\r\n\r\n- `model_name`: The name of the model. The model should be one of the supported models. (e.g., `'LSTM'`, `'BiLSTM'`, `'Transformer'`)\r\n\r\n- `timestep`: The number of timesteps in the time series data.\r\n\r\n- `dimentions`: The number of dimentions in each timestep.\r\n\r\n- `num_classes`: The number of classes in the dataset.\r\n\r\n\r\n\r\n```python\r\n\r\nimport tisc\r\n\r\n\r\n\r\n# Create a classifier\r\n\r\nclassifier = tisc.build_classifier(model_name='LSTM',\r\n\r\n timestep=20,\r\n\r\n dimentions=100,\r\n\r\n num_classes=10)\r\n\r\n\r\n\r\n# Check the type of the classifier\r\n\r\nprint(type(classifier)) # <class 'tisc.Classifier'>\r\n\r\n```\r\n\r\n\r\n\r\n### 2. Train the classifier\r\n\r\n\r\n\r\nYou can train the classifier with the `train` method.\r\n\r\n\r\n\r\nThe `train` method requires the following arguments:\r\n\r\n\r\n\r\n- `epochs`: The number of epochs to train the classifier.\r\n\r\n- `train_loader`: The dataloader for the training dataset.\r\n\r\n\r\n\r\nyou can pass `val_loader` to train the classifier with validation.\r\n\r\n\r\n\r\n```python\r\n\r\nclassifier.train(train_loader, epochs=100)\r\n\r\n\r\n\r\n# If the `val_loader` argument is passed, you can train the classifier with validation.\r\n\r\nclassifier.train(train_loader, val_loader=val_loader, epochs=100)\r\n\r\n```\r\n\r\n\r\n\r\n### 3. Evaluate the classifier\r\n\r\n\r\n\r\nYou can evaluate the classifier with the `evaluate` method.\r\n\r\n\r\n\r\nThe `evaluate` method requires the following arguments:\r\n\r\n\r\n\r\n- `test_loader`: The dataloader for the test dataset.\r\n\r\n\r\n\r\nThe `evaluate` method can return the classification report and the confusion matrix if you pass the `return_report` and `return_confusion_matrix` arguments as `True`.\r\n\r\n\r\n\r\nIf `with_best_model` argument is `True`, the classifier will use the best model that marked the best result about the model saving strategy. \r\n\r\n\r\n\r\n```python\r\n\r\nclassifier.evaluate(test_loader,\r\n\r\n return_report=True,\r\n\r\n return_confusion_matrix=True,\r\n\r\n with_best_model=True)\r\n\r\n```\r\n\r\n\r\n\r\n## Supported models\r\n\r\n\r\n\r\nThe models that can be used in version 0.1.0:\r\n\r\n\r\n\r\n- LSTM\r\n\r\n- BiLSTM\r\n\r\n- Transformer\r\n\r\n\r\n\r\nand more! (More models will be added.)\r\n\r\n\r\n\r\n",
"bugtrack_url": null,
"license": "Apache",
"summary": "Simple model creation and training framework for time series classification in Pytorch",
"version": "0.1.0",
"project_urls": {
"Homepage": "https://github.com/Yutsuro/pytorch-time-series-classification"
},
"split_keywords": [
"pytorch",
"time-series-classification",
"lstm",
"bilstm",
"transformer",
"machine-learning",
"deep-learning",
"ai",
"artificial-intelligence"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "5e7b07129c5832b2086612a7e8e522d739d592536a690f16e0d985257299e11d",
"md5": "6f45140620274170f8f6ddb62949bef7",
"sha256": "b338206a11b4e6df9c539ad1a3e71e90b411341a8447d6bdf9994416c1bb459d"
},
"downloads": -1,
"filename": "tisc-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6f45140620274170f8f6ddb62949bef7",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 17183,
"upload_time": "2024-04-14T01:03:44",
"upload_time_iso_8601": "2024-04-14T01:03:44.081509Z",
"url": "https://files.pythonhosted.org/packages/5e/7b/07129c5832b2086612a7e8e522d739d592536a690f16e0d985257299e11d/tisc-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c9eebf07aafd3577440177afa7ce3767bc1ec2bd32914cb6af934d42049c4ac1",
"md5": "ef9ff845aa005ac1022da9a8f0cd318e",
"sha256": "04545ee2239d793be0c5b01b0fe507f769ccf700bbe7372e50b6b44f4cf3c751"
},
"downloads": -1,
"filename": "tisc-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "ef9ff845aa005ac1022da9a8f0cd318e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 17349,
"upload_time": "2024-04-14T01:03:45",
"upload_time_iso_8601": "2024-04-14T01:03:45.923758Z",
"url": "https://files.pythonhosted.org/packages/c9/ee/bf07aafd3577440177afa7ce3767bc1ec2bd32914cb6af934d42049c4ac1/tisc-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-14 01:03:45",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Yutsuro",
"github_project": "pytorch-time-series-classification",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "matplotlib",
"specs": [
[
">=",
"3.8.3"
]
]
},
{
"name": "numpy",
"specs": [
[
">=",
"1.19.5"
],
[
"<",
"2.0"
]
]
},
{
"name": "scikit_learn",
"specs": [
[
">=",
"1.4.1"
]
]
},
{
"name": "seaborn",
"specs": [
[
">=",
"0.13.2"
]
]
}
],
"lcname": "tisc"
}
JSON
