TemporalScope

<p align="center"> <img src="assets/temporalscope_github_banner.png" alt="TemporalScope Logo" > </p> <!-- --8<-- [start:HOME] --> <h3 align="center">Scientifically driven Model-Agnostic Temporal Feature Importance Analysis</h3> <p align="center"> <!-- Twitter Share Button --> <a href="https://twitter.com/intent/tweet?text=Explore%20TemporalScope%20-%20Model-Agnostic%20Temporal%20Feature%20Importance%20Analysis!&url=https://github.com/philip-ndikum/TemporalScope&via=philip_ndikum&hashtags=MachineLearning,TemporalAnalysis,OpenSource" target="_blank" style="text-decoration: none;"> <img src="https://img.shields.io/twitter/url/http/shields.io.svg?style=social&label=Tweet" alt="Tweet" style="height: 28px;"> </a> &nbsp; <!-- LinkedIn Share Button --> <a href="https://www.linkedin.com/sharing/share-offsite/?url=https://github.com/philip-ndikum/TemporalScope" target="_blank" style="text-decoration: none;"> <img src="https://img.shields.io/badge/Share%20on%20LinkedIn-0077B5?&logo=linkedin&logoColor=white&style=flat-square" alt="Share on LinkedIn" style="height: 28px;"> </a> &nbsp; <!-- Reddit Share Button --> <a href="https://www.reddit.com/submit?url=https://github.com/philip-ndikum/TemporalScope&title=Explore%20TemporalScope%20-%20Model-Agnostic%20Temporal%20Feature%20Importance%20Analysis" target="_blank" style="text-decoration: none;"> <img src="https://img.shields.io/badge/Share%20on%20Reddit-FF4500?&logo=reddit&logoColor=white&style=flat-square" alt="Share on Reddit" style="height: 28px;"> </a> &nbsp; <!-- GitHub Discussions Link --> <a href="https://github.com/philip-ndikum/TemporalScope/discussions" target="_blank" style="text-decoration: none;"> <img src="https://img.shields.io/badge/Discuss-GitHub%20Discussions-blue?style=flat-square&logo=github" alt="GitHub Discussions" style="height: 28px;"> </a> </p>

---

<div align="center"> <table> <tbody> <tr> <td><strong>Compatibility</strong></td> <td> <a href="https://img.shields.io/badge/python-3.10%2B-blue"> <img src="https://img.shields.io/badge/python-3.10%2B-blue" alt="Python Version"> </a> <a href="https://img.shields.io/badge/OS-Linux-blue"> <img src="https://img.shields.io/badge/OS-Linux-blue" alt="Linux Compatible"> </a> </td> </tr> <tr> <td><strong>Docs</strong></td> <td> <a href="https://temporalscope.readthedocs.io/en/latest/?badge=latest"> <img src="https://readthedocs.org/projects/temporalscope/badge/?version=latest" alt="Documentation Status"> </a> </td> </tr> <tr> <td><strong>Meta</strong></td> <td> <a href="https://docs.astral.sh/ruff/"> <img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json" alt="Ruff"> </a> <a href="https://www.mypy-lang.org/static/mypy_badge.svg"> <img src="https://www.mypy-lang.org/static/mypy_badge.svg" alt="Checked with mypy"> </a> <a href="https://img.shields.io/badge/License-Apache%202.0-green"> <img src="https://img.shields.io/badge/License-Apache%202.0-green" alt="License"> </a> </td> </tr> <tr> <td><strong>Build Tools</strong></td> <td> <a href="https://hatch.pypa.io/latest/"> <img src="https://img.shields.io/badge/%F0%9F%A5%9A-Hatch-4051b5.svg" alt="Hatch project"> </a> </td> </tr> <tr> <td><strong>CI/CD</strong></td> <td> <a href="https://results.pre-commit.ci/latest/github/philip-ndikum/TemporalScope/main"> <img src="https://results.pre-commit.ci/badge/github/philip-ndikum/TemporalScope/main.svg" alt="pre-commit.ci status"> </a> <a href="https://github.com/philip-ndikum/TemporalScope/actions/workflows/test.yml"> <img src="https://github.com/philip-ndikum/TemporalScope/actions/workflows/test.yml/badge.svg" alt="GitHub Actions"> </a> <a href="https://coveralls.io/github/philip-ndikum/TemporalScope"> <img src="https://coveralls.io/repos/github/philip-ndikum/TemporalScope/badge.svg" alt="Coverage Status"> </a> <a href="https://github.com/philip-ndikum/TemporalScope/actions/workflows/license-compliance.yml"> <img src="https://github.com/philip-ndikum/TemporalScope/actions/workflows/license-compliance.yml/badge.svg" alt="License and Dependency Check"> </a> </td> </tr> <tr> <td><strong>Security</strong></td> <td> <a href="https://www.bestpractices.dev/projects/9424"> <img src="https://www.bestpractices.dev/projects/9424/badge" alt="OpenSSF Best Practices"> </a> <a href="https://github.com/PyCQA/bandit"> <img src="https://img.shields.io/badge/security-bandit-yellow.svg" alt="Security: Bandit"> </a> </td> </tr> </tbody> </table> </div>

TemporalScope is an open-source Python package designed to bridge the gap between scientific research and practical industry applications for analyzing the temporal dynamics of feature importance in AI & ML time series models. Developed in alignment with Linux Foundation standards and licensed under Apache 2.0, it builds on tools such as Boruta-SHAP and SHAP, using modern window partitioning algorithms to tackle challenges like non-stationarity and concept drift.

TemporalScope is an open-source Python package designed to bridge the gap between scientific research and practical industry applications for analyzing the temporal dynamics of feature importance in AI & ML time series models. Developed in alignment with Linux Foundation standards and licensed under Apache 2.0, it builds on tools such as Boruta-SHAP and SHAP, using modern window partitioning algorithms to tackle challenges like non-stationarity and concept drift.

This package is flexible and extensible, supporting frameworks like Pandas, Polars, Modin, Dask, and PyArrow via native Narwhals compatibility. Additionally, the optional Clara LLM modules (etymology from the word Clarity) are intended to serve as a model-validation tool to support explainability efforts (XAI).

NOTE: TemporalScope is currently in beta and pre-release phase, so some installation methods may not work as expected on all platforms.

<!-- --8<-- [end:HOME] -->

Table of Contents

• Installation
• Usage
  • Industrial Academic Applications
• Development Roadmap & Changelog
• Contributing
  • Collaborators
  • Contributors
• Cite this Project
• License, Limitations, and Legal Notice

Installation

<!-- --8<-- [start:INSTALLATION] -->

WARNING: TemporalScope is currently in beta, so some installation methods may not work as expected on all platforms.

TemporalScope can be installed using the following methods:

1. via pip (recommended): You can install the core package using pip:

   $ pip install temporalscope
   

2. with conda: For conda users, install via conda-forge:

   $ conda install -c conda-forge temporalscope
   

3. git clone and setup (advanced): If you prefer the latest development version, follow these steps to clone the repository and set up the project using Hatch:

   $ git clone https://github.com/philip-ndikum/TemporalScope.git
   $ cd TemporalScope
   $ hatch shell
   

   This process clones the repository, navigates to the project directory, and uses Hatch to create and activate a virtual environment with the project installed in development mode.

<!-- --8<-- [end:INSTALLATION] -->

Usage

<!-- --8<-- [start:USAGE] -->

You can use TemporalScope with the following steps:

1. Import TemporalScope: Start by importing the package.
2. Select Backend (Optional): TemporalScope defaults to using Pandas as the backend. However, you can specify other backends like Dask, Modin, or CuDF.
3. Load Data: Load your time series data into the TimeSeriesData class, specifying the time_col and optionally the id_col.
4. Apply a Feature Importance Method: TemporalScope defaults to using a Random Forest model from scikit-learn if no model is specified. You can either:
   • A. Use a pre-trained model: Pass a pre-trained model to the method.
   • B. Train a Random Forest model within the method: TemporalScope handles model training and application automatically.
5. Analyze and Visualize Results: Interpret the results to understand how feature importance evolves over time or across different phases.

Now, let's refine the code example using a random forest model and an academic dataset. We'll use the California housing dataset as a simple example since it's well-known and accessible.

import polars as pl
import pandas as pd
from statsmodels.datasets import macrodata

from temporalscope.core.temporal_data_loader import TimeFrame
from temporalscope.partitioning.naive_partitioner import NaivePartitioner
from temporalscope.core.temporal_model_trainer import TemporalModelTrainer

# 1. Load the dataset using Pandas (or convert to Polars)
macro_df = macrodata.load_pandas().data
macro_df['time'] = pd