| Compatibility |
|
| Docs |
|
| Meta |
|
| Build Tools |
|
| CI/CD |
|
| Security |
|
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.
- Installation
- Usage
- Development Roadmap & Changelog
- Contributing
- Cite this Project
- License, Limitations, and Legal Notice
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:
-
via pip (recommended): You can install the core package using pip:
$ pip install temporalscope -
with conda: For conda users, install via conda-forge:
$ conda install -c conda-forge temporalscope -
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.
You can use TemporalScope with the following steps:
- Import TemporalScope: Start by importing the package.
- Select Backend (Optional): TemporalScope defaults to using Pandas as the backend. However, you can specify other backends like Dask, Modin, or CuDF.
- Load Data: Load your time series data into the
TimeSeriesDataclass, specifying thetime_coland optionally theid_col. - 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.
- 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.date_range(
start='1959-01-01',
periods=len(macro_df),
freq='Q'
)
# Convert the Pandas DataFrame to a Polars DataFrame
macro_df_polars = pl.DataFrame(macro_df)
# 2. Initialize the TimeFrame object with the data
economic_tf = TimeFrame(
df=macro_df_polars,
time_col='time',
target_col='realgdp',
backend='pl', # Using Polars as the backend
)
# 3. Apply Partitioning Strategy (like sklearn's train_test_split)
partitioner = NaivePartitioner(economic_tf)
partitioned_data = partitioner.apply() # Returns a list of partitioned dataframes
# 4. Train and evaluate the model using the partitioned data
model_trainer = TemporalModelTrainer(
partitioned_data=partitioned_data, # Directly passing the partitioned data
model=None, # Use the default model (LightGBM)
model_params={
'objective': 'regression',
'boosting_type': 'gbdt',
'metric': 'rmse',
'verbosity': -1
}
)
# 5. Execute the training and evaluate
results = model_trainer.train_and_evaluate()
# Output predictions and metrics
for partition_name, predictions in results.items():
print(f"Predictions for {partition_name}:")
print(predictions[:5]) # Display first 5 predictionsDISCLAIMER: The following use cases are provided for academic and informational purposes only. TemporalScope is intended to support research and development in understanding temporal dynamics in feature importance. These examples are not intended as guidance for industrial applications without further validation and expert consultation. The use of TemporalScope in any industrial or production environment is at the user's own risk, and the developers disclaim any liability for such use. Please refer to the License and Legal Notice for further details.
| Sector | Use Case | Impact |
|---|---|---|
| Finance | Quantitative Investing: Understanding how the importance of financial indicators, such as interest rates or stock volatility, changes across different market cycles. | Enhances quantitative investment strategies by identifying which indicators are most predictive in various market conditions, thereby improving risk management and investment decisions. |
| Healthcare | Patient Outcome Prediction: Tracking how various patient data features, such as age, vital signs, and medical history, contribute to health outcomes at different stages of treatment or disease progression. | Facilitates the creation of personalized treatment plans by identifying critical factors at specific stages, leading to improved patient outcomes and optimized healthcare resources. |
| Energy | Load Forecasting: Analyzing how the importance of variables such as weather conditions, time of day, and historical consumption data evolves in predicting energy demand. | Improves energy load forecasting by adapting to changing conditions, leading to more efficient energy distribution and reduced operational costs. |
| Retail | Customer Behavior Analysis: Understanding how customer preferences and purchasing behaviors change over time, influenced by factors such as seasonal trends, promotions, and economic conditions. | Enables retailers to optimize inventory management, marketing strategies, and pricing models by identifying the most influential factors driving sales in different periods. |
For more detailed examples from sectors like engineering and other scientific applications, please refer to the SCIENTIFIC_LITERATURE.md.
For detailed test, security, and deployment workflows as defined by OpenSSF Best Practices, please refer to CONTRIBUTING.md. TemporalScope follows Semantic Versioning (SemVer), a versioning system that conveys the scope of changes introduced in each new release. Each version is represented in the form MAJOR.MINOR.PATCH, where major releases introduce significant or breaking changes, minor releases add backward-compatible functionality, and patch releases are used for bug fixes or minor improvements. Below is the planned roadmap outlining feature development and milestones over the next 12–18 months. This roadmap is subject to change based on user feedback, emerging research, and community contributions.
TemporalScope was conceived independently by Philip Ndikum, Serge Ndikum, and Kane Norman and has since been open-sourced to the broader academic and developer community. As the software continues to grow and evolve, it relies heavily on the active participation and contributions of its users. We encourage contributions from developers, researchers, and data scientists who are passionate about advancing open-source tools. Whether you are interested in extending the package’s functionality, fixing bugs, or improving documentation, your contributions are vital to the project’s ongoing success.
For detailed guidelines on how to contribute, please refer to our CONTRIBUTING.md. By working together, we can ensure that TemporalScope remains an innovative and reliable tool, continuously refined through community collaboration.
Thank you to all of these people who have contributed to TemporalScope!
|
Sylvester Cardorelle |
Kane Norman |
Philip Ndikum |
serge-ndikum |
|
Philip Ndikum |
Kane Norman |
Sylvester Cardorelle |
If you use TemporalScope in your research, please consider citing it:
@software{ndikum2024temporalscope,
author = {Ndikum, Philip and Ndikum, Serge and Norman, Kane},
title = {TemporalScope: Model-Agnostic Temporal Feature Importance Analysis},
year = {2024},
version = {0.1.0},
publisher = {GitHub},
url = {https://github.com/philip-ndikum/TemporalScope}
}TemporalScope is primarily an academic tool designed for research and informational purposes. Practitioners and users of this software are strongly encouraged to consult the accompanying scientific literature to fully understand the theoretical limitations, assumptions, and context of the techniques implemented within this package. Furthermore, use of this software falls under "as-is" software as defined by the Apache License 2.0 provided in this repository.
By using this package, you agree to comply with the terms and conditions set forth in the Apache License 2.0.
THIS SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING FROM, OUT OF, OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
THIS SOFTWARE IS INTENDED FOR ACADEMIC AND INFORMATIONAL PURPOSES ONLY. IT SHOULD NOT BE USED IN PRODUCTION ENVIRONMENTS OR FOR CRITICAL DECISION-MAKING WITHOUT PROPER VALIDATION. ANY USE OF THIS SOFTWARE IS AT THE USER'S OWN RISK.