Knowledge discovery in time series data

KnowIt (Knowledge discovery In Time series data) is an extendable toolkit to build and interpret deep time series models. It is developed in Python and uses PyTorch Lightning for model building and Captum for model interpreting.

Installation

• Clone the KnowIt directory locally
• Create a conda environment with the provided KnowIt/environment.yml file
• Installation package TBD

Usage overview

```python

Import the KnowIt module

from knowit import KnowIt

Instantiate a KnowIt object linked to an output directory

KI = KnowIt(customexpdir='myoutputpath')

Define your dataset

dataargs = {'name': 'synth2', 'task': 'regression', 'incomponents': ['x1', 'x2', 'x3', 'x4'], 'outcomponents': ['x5'], 'inchunk': [-32, 0], 'outchunk': [0, 0], 'splitportions': [0.6, 0.2, 0.2], 'batchsize': 64}

Define your architecture

arch_args = {'task': 'regression', 'name': 'MLP'}

Define your trainer

trainerargs = {'lossfn': 'mseloss', 'optim': 'Adam', 'maxepochs': 10, 'learning_rate': 0.01, 'task': 'regression'}

Train your model

KI.trainmodel(modelname='mynewmodelname', kwargs={'data': dataargs, 'arch': archargs, 'trainer': trainerargs})

Generate model predictions

KI.generatepredictions(modelname='mynewmodelname', kwargs={'predictor': {'predictionset': 'valid'}})

Interpret model predictions

KI.interpretmodel(modelname='mynewmodelname', kwargs={'interpreter': {'interpretationmethod': 'DeepLift', 'interpretation_set': 'valid', 'selection': 'random', 'size': 100}}) ```

Current Features

• Flexible problem class definition allows facilitating various time series modeling tasks, including: uni- and multivariate, single- and multistep, time series regression, classification, forecasting, and detection.
• A growing list of default deep time series architectures. Currently includes: MLP, CNN, TCN, and LSTM.
• Convenient entry points to import custom architectures (PyTorch based) and custom dataset (Pandas based).
• Automated data management (storing, splitting, scaling, sampling, loading, padding etc.) of complex time series data.
• Convenient feature attribution extraction and storage.
• Hyperparameter tuning through Pytorch Lightning and Weights and Biases API.
• Extendable design for additional future training and interpretability paradigms.

Current Limitations

• Data is assumed to be equidistantly sampled and time-indexed time series data. Gaps are removed during preprocessing to construct contiguous blocks of data for model training.
• Data is stored on and loaded from disk in contiguous slices. These slices have to fit into memory.

Coming soon

• Adding Transformer-based models to default architectures
• Package installation options
• Testbench for synthetic data experimentation
• Additional feature attribution visualizations

We are open to any suggestions.

Citation

If you make use of KnowIt, we kindly request that you cite it with the provided citation file.

Acknowledgements

This project is made possible due to funding and support from: - MUST Deep Learning - North-West University (NWU), South Africa - National Institute for Theoretical & Computational Sciences (NITheCS), South Africa - Centre for Artificial Intelligence Research (CAIR), South Africa - National Research Foundation (NRF), South Africa

Contributors: - Marthinus Wilhelmus Theunissen (tiantheunissen@gmail.com) - Randle Rabe (randlerabe@gmail.com) - Harmen Potgieter (potgieterharmen@gmail.com)