How tergelitu/teda-v1 works
Project type & purpose (what you’re diagramming)
This repo is a Python analytics library/package (not a service). Its purpose is Temporal Exploratory Data Analysis and feature drift monitoring over time, offering functions that:
• compute feature summary metrics (missingness, uniqueness, volatility, correlation)
• track drift (PSI) monthly
• detect structural breaks (ruptures)
• track feature importance evolution (RF/XGBoost)
• decompose series into trend/seasonality/residual (HP filter via statsmodels)
File structure analysis (what components exist)
From the tree:
• teda/ — the actual Python package
• teda/__init__.py — defines the public API surface (what import teda as te exposes)
• teda/features.py — appears to contain core implementations of the features listed in the README (overview_table, PSI, PCA plot, change points, importance, HP filter plots)
• pyproject.toml — packaging/build metadata (dependencies, versioning, distribution)
• README.md — functional scope and user-facing API
• .gitignore, LICENSE — not architectural
This implies a relatively simple internal architecture: single-module core with multiple functions, mediated by __init__.py.
README-derived architecture clues (stack & runtime)
• pandas/numpy: data handling + numeric ops (central)
• plotly (+ ipywidgets): interactive visual outputs, notebook UX
• scikit-learn: preprocessing/PCA, RandomForest
• xgboost: feature importance evolution
• ruptures: changepoint detection algorithms (PELT/Binseg/Dynp)
• statsmodels: HP filter decomposition
User / Consumer Environment
• “Data Scientist / ML Engineer”
• “Jupyter Notebook / Python Script”
• teda-demo.ipynb (example consumer)
Inputs
• “Dataset (pandas DataFrame)”
• includes date_col, optional target_col, optional exclude_cols
• Optional: “Configuration/Parameters”
• thresholds (PSI), model choice (ruptures algorithm), etc.
TEDA Package (the library itself)
Inside a boundary labeled teda:
• Public API layer: teda/__init__.py
• exposes: overview_table, plot_monthly_psi, plot_monthly_pca, detect_change_points, plot_monthly_importance, plot_monthly_trend
• Core implementation: teda/features.py
• implement the computation + plotting
• “Temporal aggregation (monthly)”
• “Feature stats & drift metrics”
• “Modeling (PCA / RF / XGB)”
• “Changepoint detection”
• “Trend decomposition (HP filter)”
External Dependencies (libraries)
• pandas/numpy (used by essentially every function)
• plotly (+ ipywidgets) for visualizations
• scikit-learn (PCA, RandomForest, preprocessing)
• xgboost (importance evolution model)
• ruptures (changepoint detection)
• statsmodels (HP filter)
Outputs
• “Tables / DataFrames” (overview outputs, metrics tables)
• “Plots / Interactive Figures” (plotly)
• “Warnings/Threshold alerts” (PSI threshold warnings)
Model the interactions as a call/dataflow pipeline:
User/Notebook → calls Public API (__init__.py) → delegates to features.py → uses pandas/numpy and the specialized libs → returns:
• a DataFrame-like table and/or
• a plotly Figure rendered in notebook and/or
• warning signals (threshold flags)
Critically, show that the DataFrame is the central artifact flowing through:
• preprocessing (exclude cols, parse date)
• monthly aggregation
• metric/model computations
• visualization
Architectural patterns / design principles
• Library / functional API: functions are the unit of composition (not long-running services).
• Thin public API, thick implementation module: __init__.py re-exports core functions; features.py contains logic.
• Pipeline stages repeated across features:
• “time aggregation” → “computation” → “visualization/report”
• Dependency-driven capability modules:
• drift (PSI) ↔ stats
• PCA ↔ scikit-learn
• breakpoints ↔ ruptures
• importance ↔ sklearn/xgboost
• trend ↔ statsmodels
• PSI tracking: pandas/numpy (PSI implementation), plotly (line chart), warning thresholds
• PCA 3D: scikit-learn PCA, plotly 3D scatter, monthly means + distance calc
• Change points: ruptures (PELT/Binseg/Dynp), plotly markers
• Feature importance evolution: RandomForest (sklearn) / XGBoost, rolling/monthly training, plotly
• HP filter: statsmodels HP filter, plotly decomposition plots
• Overview table: pandas/numpy stats + correlation with target
Tier 1 (Consumer + Input)
• Jupyter Notebook / Python Script (teda-demo.ipynb)
→ DataFrame (pandas)
Tier 2 (TEDA internals)
• teda package boundary
• __init__.py (Public API)
→ features.py (Implementations)
• shared step: “Monthly aggregation”
Tier 3 (Dependencies + Output)
• Dependencies: pandas/numpy, plotly/ipywidgets, sklearn, xgboost, ruptures, statsmodels
• Outputs: “Overview Table (DataFrame)”, “PSI Time Series Plot”, “3D PCA Plot + Distance Bars”, “Breakpoint Plot”, “Importance Evolution Plot”, “Trend/Seasonality/Residual Plot”
This will be the most accurate representation given the small codebase and the README-defined API.