<img src="./design/sequifier.png">
### one-to-one and many-to-one autoregression made easy
Sequifier enables sequence classification or regression for time based sequences using transformer models, via CLI.
The specific configuration of preprocessing, which takes a single or multi-variable columnar data file and creates
training, validation and test sequences, training, which trains a transformer model, and inference, which calculates
model outputs for data (usually the test data from preprocessing), is done via configuration yaml files.
\
\
\
## Overview
The sequifier package enables:
- the extraction of sequences for training
- the configuration and training of a transformer classification or regression model
- using multiple input and output sequences
- inference on data with a trained model
## Other materials
If you want to first get a more specific understanding of the transformer architecture, have a look at
the [Wikipedia article.](https://en.wikipedia.org/wiki/Transformer_(machine_learning_model))
If you want to see a benchmark on a small synthetic dataset with 10k cases, agains a random forest,
an xgboost model and a logistic regression, check out [this notebook.](./documentation/demos/benchmark-small-data.ipynb)
## Complete example how to build and apply a transformer sequence classifier with sequifier
1. create a conda environment with python >=3.9 activate and run
```console
pip install sequifier
```
2. create a new project folder (at a path referred to as `PROJECT PATH` later) and a `configs` subfolder
3. copy default configs from repository for preprocessing, training and inference
4. adapt preprocess config to take the path to the data you want to preprocess and set `project_path` to`PROJECT PATH`
5. run
```console
sequifier preprocess --config_path=[PROJECT PATH]/configs/preprocess.yaml
```
6. the preprocessing step outputs a "data driven config" at `[PROJECT PATH]/configs/ddconfigs/[FILE NAME]`. It contains the number of classes found in the data, a map of classes to indices and the oaths to train, validation and test splits of data. Adapt the `dd_config` parameter in `train-on-preprocessed.yaml` and `infer.yaml` in to the path `[PROJECT PATH]/configs/ddconfigs/[FILE NAME]`and set `project_path` to `PROJECT PATH` in both configs
7. run
```console
sequifier train --config_path=[PROJECT PATH]/configs/train-on-preprocessed.yaml
```
8. adapt `data_path` in `infer.yaml`
9. run
```console
sequifier infer --config_path=[PROJECT PATH]/configs/infer.yaml
```
10. find your predictions at `[PROJECT PATH]/outputs/predictions/sequifier-default-best-predictions.csv`
## More detailed explanations of the three steps
#### Preprocessing of data into sequences for training
The preprocessing step is designed for scenarios where for timeseries or timeseries-like data,
the prediction of the next data point of one or more variables from prior values of these
variables and (optionally) other variables is of interest.
This step presupposes input data with three columns: "sequenceId" and "itemPosition", and a column
with the variable that is the prediction target.
"sequenceId" separates different sequences and the itemPosition column
provides values that enable sequential sorting. Often this will simply be a timestamp.
You can find an example of the preprocessing input data at [documentation/example_inputs/preprocessing_input.csv](./documentation/example_inputs/preprocessing_input.csv)
The data can then be processed and split into training, validation and testing datasets of all
valid subsequences in the original data with the command:
```console
sequifier preprocess --config_path=[CONFIG PATH]
```
The config path specifies the path to the preprocessing config and the project
path the path to the (preferably empty) folder the output files of the different
steps are written to.
The default config can be found on this path:
[configs/preprocess.yaml](./configs/preprocess.yaml)
#### Configuring and training the sequence classification model
The training step is executed with the command:
```console
sequifier train --config_path=[CONFIG PATH]
```
If the data on which the model is trained DOES NOT come from the preprocessing step, the flag
```console
--on-unprocessed
```
should be added.
If the training data does not come from the preprocessing step, both train and validation
data have to take the form of a csv file with the columns "sequenceId", "subsequenceId", "col_name", [SEQ LENGTH], [SEQ LENGTH - 1],...,"1", "target".
You can find an example of the preprocessing input data at [documentation/example_inputs/training_input.csv](./documentation/example_inputs/training_input.csv)
The training step is configured using the config. The two default configs can be found here:
[configs/train.yaml](./configs/train.yaml)
depending on whether the preprocessing step was executed.
#### Inferring on test data using the trained model
Inference is done using the command:
```console
sequifier infer --config_path=[CONFIG PATH]
```
and configured using a config file. The default version can be found here:
[configs/infer.yaml](./configs/infer.yaml)
Raw data
{
"_id": null,
"home_page": "https://github.com/0xideas/sequifier",
"name": "sequifier",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.9",
"maintainer_email": null,
"keywords": "transformer, sequence classification, machine learning, sequence, sequence modelling, nlp, language, language modelling, torch, pytorch",
"author": "Leon Luithlen",
"author_email": "leontimnaluithlen@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/16/aa/b83169ec14f7a3793c189f130241381809d136f288eef49443afa4f5f69a/sequifier-2.1.0.tar.gz",
"platform": null,
"description": "<img src=\"./design/sequifier.png\">\n\n\n### one-to-one and many-to-one autoregression made easy\n\nSequifier enables sequence classification or regression for time based sequences using transformer models, via CLI.\nThe specific configuration of preprocessing, which takes a single or multi-variable columnar data file and creates\ntraining, validation and test sequences, training, which trains a transformer model, and inference, which calculates\nmodel outputs for data (usually the test data from preprocessing), is done via configuration yaml files.\n\n\\\n\\\n\\\n## Overview\nThe sequifier package enables:\n - the extraction of sequences for training\n - the configuration and training of a transformer classification or regression model\n - using multiple input and output sequences\n - inference on data with a trained model\n\n\n## Other materials \nIf you want to first get a more specific understanding of the transformer architecture, have a look at\nthe [Wikipedia article.](https://en.wikipedia.org/wiki/Transformer_(machine_learning_model))\n\nIf you want to see a benchmark on a small synthetic dataset with 10k cases, agains a random forest,\nan xgboost model and a logistic regression, check out [this notebook.](./documentation/demos/benchmark-small-data.ipynb)\n\n\n## Complete example how to build and apply a transformer sequence classifier with sequifier\n\n1. create a conda environment with python >=3.9 activate and run\n```console\npip install sequifier\n```\n2. create a new project folder (at a path referred to as `PROJECT PATH` later) and a `configs` subfolder\n3. copy default configs from repository for preprocessing, training and inference\n4. adapt preprocess config to take the path to the data you want to preprocess and set `project_path` to`PROJECT PATH`\n5. run \n```console\nsequifier preprocess --config_path=[PROJECT PATH]/configs/preprocess.yaml\n```\n6. the preprocessing step outputs a \"data driven config\" at `[PROJECT PATH]/configs/ddconfigs/[FILE NAME]`. It contains the number of classes found in the data, a map of classes to indices and the oaths to train, validation and test splits of data. Adapt the `dd_config` parameter in `train-on-preprocessed.yaml` and `infer.yaml` in to the path `[PROJECT PATH]/configs/ddconfigs/[FILE NAME]`and set `project_path` to `PROJECT PATH` in both configs\n7. run\n```console\nsequifier train --config_path=[PROJECT PATH]/configs/train-on-preprocessed.yaml\n```\n8. adapt `data_path` in `infer.yaml`\n9. run\n```console\nsequifier infer --config_path=[PROJECT PATH]/configs/infer.yaml\n```\n10. find your predictions at `[PROJECT PATH]/outputs/predictions/sequifier-default-best-predictions.csv`\n\n\n## More detailed explanations of the three steps\n#### Preprocessing of data into sequences for training\n\nThe preprocessing step is designed for scenarios where for timeseries or timeseries-like data,\nthe prediction of the next data point of one or more variables from prior values of these\nvariables and (optionally) other variables is of interest.\n\nThis step presupposes input data with three columns: \"sequenceId\" and \"itemPosition\", and a column\nwith the variable that is the prediction target.\n\"sequenceId\" separates different sequences and the itemPosition column\nprovides values that enable sequential sorting. Often this will simply be a timestamp.\nYou can find an example of the preprocessing input data at [documentation/example_inputs/preprocessing_input.csv](./documentation/example_inputs/preprocessing_input.csv)\n\nThe data can then be processed and split into training, validation and testing datasets of all\nvalid subsequences in the original data with the command:\n\n```console\nsequifier preprocess --config_path=[CONFIG PATH]\n```\n\nThe config path specifies the path to the preprocessing config and the project\npath the path to the (preferably empty) folder the output files of the different\nsteps are written to.\n\nThe default config can be found on this path:\n\n[configs/preprocess.yaml](./configs/preprocess.yaml)\n\n\n\n#### Configuring and training the sequence classification model\n\nThe training step is executed with the command:\n\n```console\nsequifier train --config_path=[CONFIG PATH]\n```\n\nIf the data on which the model is trained DOES NOT come from the preprocessing step, the flag\n\n```console\n--on-unprocessed\n```\n\nshould be added.\n\nIf the training data does not come from the preprocessing step, both train and validation\ndata have to take the form of a csv file with the columns \"sequenceId\", \"subsequenceId\", \"col_name\", [SEQ LENGTH], [SEQ LENGTH - 1],...,\"1\", \"target\".\nYou can find an example of the preprocessing input data at [documentation/example_inputs/training_input.csv](./documentation/example_inputs/training_input.csv)\n\nThe training step is configured using the config. The two default configs can be found here:\n\n[configs/train.yaml](./configs/train.yaml)\n\ndepending on whether the preprocessing step was executed.\n\n\n#### Inferring on test data using the trained model\n\nInference is done using the command:\n\n```console\nsequifier infer --config_path=[CONFIG PATH]\n```\n\nand configured using a config file. The default version can be found here:\n\n[configs/infer.yaml](./configs/infer.yaml)\n\n\n",
"bugtrack_url": null,
"license": "BSD 3-Clause",
"summary": "Train a transformer model with the command line",
"version": "2.1.0",
"project_urls": {
"Homepage": "https://github.com/0xideas/sequifier",
"Repository": "https://github.com/0xideas/sequifier"
},
"split_keywords": [
"transformer",
" sequence classification",
" machine learning",
" sequence",
" sequence modelling",
" nlp",
" language",
" language modelling",
" torch",
" pytorch"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "2919eb89d8115056124b8a97b184b4fde31131ebad35d9e9dfb0a51ff3d0a299",
"md5": "7e6ab3c42a0a65852d4588077f248415",
"sha256": "00ccdf4c8d09500776a358eb8571af17a110acbbb4b43f343775f37a932e6ec1"
},
"downloads": -1,
"filename": "sequifier-2.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7e6ab3c42a0a65852d4588077f248415",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.9",
"size": 25725,
"upload_time": "2024-05-01T11:32:16",
"upload_time_iso_8601": "2024-05-01T11:32:16.515067Z",
"url": "https://files.pythonhosted.org/packages/29/19/eb89d8115056124b8a97b184b4fde31131ebad35d9e9dfb0a51ff3d0a299/sequifier-2.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "16aab83169ec14f7a3793c189f130241381809d136f288eef49443afa4f5f69a",
"md5": "bddfef30e16adbe3ea44594872846c8f",
"sha256": "4e9197177f24b29384062a1d82d12ae5f1db1c291c9ac6b340057fcf4d7f2fdc"
},
"downloads": -1,
"filename": "sequifier-2.1.0.tar.gz",
"has_sig": false,
"md5_digest": "bddfef30e16adbe3ea44594872846c8f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.9",
"size": 22184,
"upload_time": "2024-05-01T11:32:18",
"upload_time_iso_8601": "2024-05-01T11:32:18.367890Z",
"url": "https://files.pythonhosted.org/packages/16/aa/b83169ec14f7a3793c189f130241381809d136f288eef49443afa4f5f69a/sequifier-2.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-01 11:32:18",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "0xideas",
"github_project": "sequifier",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "sequifier"
}
JSON
