KnowIt: Deep Time Series Modeling and Interpretation

KnowIt (Knowledge discovery in time series data) is a flexible framework for building deep time series models and interpreting them. It is implemented as a Python toolkit, with source code and documentation available from https://must-deep-learning.github.io/KnowIt. It imposes minimal assumptions about task specifications and decouples the definition of dataset, deep neural network architecture, and interpretability technique through well defined interfaces. This ensures the ease of importing new datasets, custom architectures, and the definition of different interpretability paradigms while maintaining on-the-fly modeling and interpretation of different aspects of a user’s own time series data. KnowIt aims to provide an environment where users can perform knowledge discovery on their own complex time series data through building powerful deep learning models and explaining their behavior. With ongoing development, collaboration and application our goal is to make this a platform to progress this underexplored field and produce a trusted tool for deep time series modeling.

💡 Research Summary

**
The paper introduces KnowIt, an open‑source Python toolkit designed to streamline the entire workflow of deep learning‑based time‑series modeling and interpretation. KnowIt separates dataset handling, neural‑network architecture definition, and interpretability techniques into well‑specified interfaces, allowing users to import new datasets, plug in custom models, and apply a growing suite of explanation methods without rewriting core code.

The authors first formalize the class of time‑series problems that KnowIt addresses. By defining a “prediction point,” users can specify arbitrary input and output time delays and component selections, enabling classic tasks such as autoregressive forecasting, multi‑step prediction, and strictly causal modeling. Although the internal models operate on fixed‑length windows, variable‑length inputs are accommodated through padding, truncation, sliding windows, and optional stateful training where hidden states are carried across batches. This design balances flexibility with the practical constraints of deep‑learning frameworks.

A set of six default architectures is provided: a plain Multilayer Perceptron (MLP) as a non‑temporal baseline; Temporal Convolutional Network (TCN) with dilated causal convolutions for short‑term high‑frequency patterns; a non‑causal CNN variant; standard LSTM for sequential processing; LSTMv2, which adds layer normalization, residual connections, and stateful capabilities for more stable long‑range learning; and a Temporal Fusion Transformer (TFT) that incorporates variable selection, gating, LSTM encoding, and interpretable multi‑head attention. Users may also supply custom architectures that conform to the same input‑output shape contract, ensuring seamless integration.

Interpretability is a core focus. KnowIt leverages the Captum library to provide feature‑attribution methods such as DeepLift, DeepLiftShap, and Integrated Gradients. Attributions are computed for any chosen prediction point and can be aggregated across time steps or features to reveal importance patterns and interactions. The toolkit stores these results in a structured “experiment output directory,” facilitating downstream analysis and visualization. The authors note that future work will extend visualization capabilities and incorporate additional paradigms (e.g., Shapley values, counterfactuals).

The software architecture consists of three primary modules plus a top‑level orchestrator:

1. Data Module – Ingests raw data (CSV, Parquet, JSON, etc.) into pandas DataFrames, performs sampling, splitting, scaling, and writes the processed dataset to disk as partitioned Parquet files with accompanying metadata.
2. Trainer Module – Wraps PyTorch Lightning to train models, handling dataloaders, checkpointing, metric logging, and optional hyper‑parameter sweeps. Sweeps can be logged to Weights & Biases for automated experiment tracking.
3. Interpreter Module – Takes a trained model and the prepared dataset, runs Captum attribution algorithms, and saves interpretation artifacts.

The typical user workflow follows three stages: data import, model building, and interpretation. During model building, users may manually tune a single model or launch a hyper‑parameter sweep; the best model can be automatically selected and stored. After training, the interpreter can be invoked to explain random predictions, best‑performing points, or any user‑defined subset. All artifacts—including custom datasets, model checkpoints, sweep logs, and interpretation outputs—are organized under the experiment directory for reproducibility.

In a comparative analysis, the authors benchmark KnowIt against other popular time‑series libraries such as GluonTS, Darts, and Kats. While these alternatives support deep models and hyper‑parameter optimization, none place interpretability at the forefront. Some provide intrinsically interpretable models or limited Shapley‑based explanations, but KnowIt uniquely offers a unified platform where any deep model can be interpreted using a standardized attribution pipeline, and where the interpretability component is designed to evolve alongside the modeling stack.

The paper concludes that KnowIt fills a critical gap in the time‑series ecosystem by coupling powerful deep‑learning models with robust, extensible interpretability tools. Its modular design encourages community contributions, and its focus on transparency makes it especially valuable for high‑risk domains such as healthcare, finance, and engineering where model accountability is essential. Ongoing development aims to broaden the suite of explanation techniques, improve visualization, and maintain compatibility with emerging deep‑learning architectures, positioning KnowIt as a trusted, future‑proof platform for deep time‑series analysis.