iperform 0.3.0

Monitor, Decide, act - with precise KPIs, smart alerts, and reliable forecasts. In a few lines code.

iperform - Performance Intelligence for Business & Data Teams

---

✍🏽 Autor

ILUNGA BUABUA Patrick

🇬🇧 Go to English | 🇫🇷 Aller au Français

🇬🇧 English

Monitor, Decide, act - with precise KPIs, smart alerts, and reliable forecasts. In a few lines code.

🚀 Overview

iperform is a Python package designed to turn your raw business data (Key Parameters - KPs) into actionable performance metrics (Key Performance Indicators - KPIs).

Built for business, marketing, finance, and data teams who need to :

• 📊 Monitor operational performance (WTD, MTD, YTD, ...),
• 📈 Detect critical variations and trigger alerts,
• 🔮 Forcast future trends using statistical models or business rules,
• 🧹 Clean and validation data (missing, outliers, anomalies, ...),
• 🖼️ Visualize KPIs and KPs clearly and impactfully.

💡 Advanced features as AI-powered forecasting (SARIMAX, LSTM, ...) or budgeting tools are in the SaaS/Premium edition iperform[saas].

✨ Core functionality

iperform provides a comprehensive set of functions to extract time series values and dynamic performance indicator for any given reference date - enabling real-time operational reporting and decision-making.

Key functions include :

• mtd() - Month-To-Date : Cumulative sum from the first day of the month up to reference date.
• ytd() - Year-To-Date : Cumulative sum from January 1st up to reference date.
• get_summary_day() - Returns 8+ dynamic KPIs for given day : curent value (D-Day), D-1, D-7, MTD, ∆ MTD, ... etc. -> Also available : get_summary_month(), get_summary_quarter() for higher-level reporting
• get_columns_day() - Generate dynamic column headers for daily dashbords based on the reference date.
• grand_trend_day() - Creates interactive visualizations to explore trends and anomalies.
• forecast_m() - Predicts the full-month total based on current MTD performance, using statistical extrapolation or business rules.

All functions are designed for plug-and-play analytics - turning raw time-series data into actionable business insights with minimal code.

📦 Installation

Install the iperform package via PyPI :

pip install iperform

🧩 Examples

import numpy as np
import pandas as pd
import iperform as ip

# Data
np.random.seed(1234)
date = pd.date_range("2023-01-01", periods=522, freq="D")
revenu = np.random.normal(50, 6.3, 522)
df = pd.DataFrame({"date": date, "revenu": revenu, "zone": "all_zone", "factor": "Orange"})

mtd() - Month-To-Date

Calculates the sum (or cumulative value) from the 1st of the month to the specified date.

result = ip.mtd(df=df, date="2023-01-15", value="revenu", zone="all_zone", cumul=False, decimal=2)
print(f"Revenu MTD on January 15 : {result} USD")
# Example of output - MTD on January 15 : 745.61 USD

forecast_m() - Monthly Forecasts

Estimates the monthly total by extrapolating the observed daily average.

projection = ip.forecast_m(data=df, date="2023-01-15", value="revenu", zone="all_zone", decimal=2)
print(f"Monthly forecast : {projection} USD")
# Example of output - Monthly forecast : 1540.93 USD

get_summary_day() - Daily summary (8 indicators)

Returns a list of 8 key indicators for a given date: daily value, previous day (D-1), previous week (D-7), MTD, growth rates, etc.

summary = ip.get_summary_day(df=df, date="2023-03-21", zone="all_zone", factor="Orange", value="revenu")
labels = ["D-7", "D-1", "D-Day", "∆ DoD", "∆ DoD-7", "MTD-1", "MTD", "∆ MTD"]
for label, val in zip(labels, summary):
    print(f"{label}: {val}")
# Example of output -
# D-7: 54.437
# D-1: 53.981
# D-Day: 50.249
# ∆ DoD: -0.069
# ∆ DoD-7: -0.077
# MTD-1: 1070.639
# MTD: 1067.452
# ∆ MTD: -0.003

get_summary_month() - Monthly summary (8 indicators)

Returns a list of 8 key indicators for a given month: current month, previous month, same month last year (Y-1), YTD, and growth rates (MoM, YoY, etc.).

summary_month = ip.get_summary_month(df=df, date="2024-04-30", factor="Orange",  value="revenu", decimal=2)
labels_month = ["M-12", "M-1", "M", "∆ SPLM", "∆ SPLY", "YTD-1", "YTD", "∆ YTD"]
for label, val in zip(labels_month, summary_month):
    print(f"{label}: {val}")
# Example of output -
# M-12: 1487.24
# M-1: 1514.23
# M: 1474.21
# ∆ SPLM: 0.01
# ∆ SPLY: -0.01
# YTD-1: 6025.71
# YTD: 5942.99
# ∆ YTD: -0.01

get_columns_day() - Generation of column titles (Daily dashboard)

Generates column names for a daily dashboard, based on a reference date.

# Generate the titles for January 15, 2023
columns = get_column_day(date_ref="2023-01-15")
print("Column headers :")
print(columns)
# Example of output -
# Column headers :
# ['KPIs', '8-janv.', '14-janv.', '15-janv.', '∆ DoD', '∆ SDLW', 'MTD-1', 'MTD', '∆ MTD']

get_columns_day() + get_summay_day() - Generation of Daily dashboard

Create a dashboard with dynamic column name.

date_ref = "2023-03-21"
columns = ip.get_column_day(date_ref)[1:9]
summary_day = ip.get_summary_day(df=df, date=date_ref, zone="all_zone", factor="Orange", value="revenu", decimal=3)
df_summary = pd.DataFrame([summary_day], columns=columns)
print(df_summary)
# Example of output -
# 14-mars  20-mars  21-mars  ∆ DoD  ∆ SDLW     MTD-1       MTD  ∆ MTD
#  54.437   53.981   50.249 -0.069  -0.077  1070.639  1067.452 -0.003

c_rate() - Relative change

Computes the percentage change of value x relative to value y.

# Absolute difference (even if y=0)
print(ip.c_rate(x=100, y=0, abs=True))
# Example of output - 100.0

# Normalization: compare February (28d) vs January (31d), reduced to 30d
print(ip.c_rate(x=280, y=310, abs=False, nx=28, ny=31, nn=30))
# Example of output - 0.0

📄 Documentation

See documentation and notebooks Report a bug or request a feature : GitHub Issues

Contribute

All contributions are welcome ! Whether it's to fix a bug, add a new feature, or improve the documentation.

Consult the file CONTRIBUTING.md to begin with.

Contact

• Github : https://github.com/ipatriqIP/iperform
• Auteur : [e-mail]
• Licence : MIT

🇫🇷 Français

Piloter, décider, agir - avec des KPIs précis, des alertes intélligentes, et des prévisions fiables. En quelques lignes de code.

🚀 Présentation

iperform est un package Python conçu pour transformer vos données brutes (Key Parameters - KPs) en indicateurs actionnables (Key Performance Indicators - KPIs).

Il s'adresse aux équipes business, marketing, finance et data qui doivent :

• 📊 Piloter la performance opérationnelle (WTD, MTD, YTD, ...),
• 📈 Détecter les variations critiques et les alertes,
• 🔮 Prédire les tendances futures avec des modèles statistiques ou des règles métier,
• 🧹 Nettoyer et fiabiliser les données (valeurs manquates, aberrantes, ...),
• 🖼️ Visualiser les KPIs et KPs de façon claire et impactante.

💡 Les fonctionnalités avancées telles que la modélisation IA (SARIMAX, LSTM, ...) ou des outils d'élaboration du budget sont dans l'édition SaaS/Premium iperform[saas].

✨ Fonctionnalité de base

iperform propose un ensemble complet de fonctions pour extraire les valeurs d'une série temporelle et calculer des indicateurs de performance dynamiques pour toute date de référence donnée - permettant un reporting opérationnel en temps réel et une prise de décision éclairée.

Fonctions clés :

• mtd() - Month-To-Date (MTD) : Somme cumulative depuis le premier jour du mois jusqu'à la date de référence.
• ytd() - Year-To-Date : (YTD) : Somme cumulative depuis le 1er janvier jusqu'à date de référence.
• get_summary_day() - Retourne 8+ indicateurs dynamiques pour une journée donnée : valeur du Jour-J (J-7, J-1, MTD, ...). -> Aussi disponible : get_summary_month(), get_summary_quarter()... pour des vues mensuelles ou trimestrielles.
• get_columns_day() : Génère les noms des colonnes pour un tableau de bord quotidien, basés sur la date de référence.
• graph_trend_day() : Crée des visualisations interactives pour explorer les tendances et détecter les anomalies.
• forecast_m() : Estime le total du mois en cours à partir de la performance MTD, via l'extrapolation statistique ou règles métier.

Toutes les fonctions sont conçues pour une analyse plug-and-play - transformant vos données brutes en insights actionables, en quelques lignes de code.

📦 Installation

Installation du package iperform via PyPI :

pip install iperform

🧩 Examples

import numpy as np
import pandas as pd
import iperform as ip

# Data
np.random.seed(1234)
date = pd.date_range("2023-01-01", periods=522, freq="D")
revenu = np.random.normal(50, 6.3, 522)
df = pd.DataFrame({"date": date, "revenu": revenu, "zone": "all_zone", "factor": "Orange"})

mtd() - Month-To-Date

Calcule la somme cumulative depuis le 1er jour du mois en cours jusqu'à la date de référence.

result = ip.mtd(df=df, date="2023-01-15", value="revenu", zone="all_zone", cumul=False, decimal=2)
print(f"Revenu MTD au 15 janvier : {result} USD")
# Exemple de sortie - MTD au 15 Janvier : 745.61 USD

forecast_m() - Projection mensuelle

Estime le total mensuel à partir de la performance MTD.

projection = ip.forecast_m(data=df, date="2023-01-15", value="revenu", zone="all_zone", decimal=2)
print(f"Projection mensuelle : {projection} USD")
# Exemple de sortie - Projection mensuelle : 1540.93 USD

get_summary_day() - Résumé journalier (8 indicateurs)

Retourne une liste de 8 indicateurs pour une date donnée : valeur du jour, jour J-1, même jour de la semaine passée (D-7), MTD, variations, etc.

summary = ip.get_summary_day(df=df, date="2023-03-21", zone="all_zone", factor="Orange", value="revenu")
labels = ["D-7", "D-1", "D-Day", "∆ DoD", "∆ DoD-7", "MTD-1", "MTD", "∆ MTD"]
for label, val in zip(labels, summary):
    print(f"{label}: {val}")
# Exemple de sortie  -
# D-7: 54.437
# D-1: 53.981
# D-Day: 50.249
# ∆ DoD: -0.069
# ∆ DoD-7: -0.077
# MTD-1: 1070.639
# MTD: 1067.452
# ∆ MTD: -0.003

get_summary_month() - Résumé mensuel (8 indicateurs)

Returne une liste de 8 indicateurs pour un mois donné : mois en cours, mois dernier, même mois de l'année passé, YTD, variations (MoM, YoY, etc.).

summary_month = ip.get_summary_month(df=df, date="2024-04-30", factor="Orange",  value="revenu", decimal=2)
labels_month = ["M-12", "M-1", "M", "∆ SPLM", "∆ SPLY", "YTD-1", "YTD", "∆ YTD"]
for label, val in zip(labels_month, summary_month):
    print(f"{label}: {val}")
# Exemple de sortie -
# M-12: 1487.24
# M-1: 1514.23
# M: 1474.21
# ∆ SPLM: 0.01
# ∆ SPLY: -0.01
# YTD-1: 6025.71
# YTD: 5942.99
# ∆ YTD: -0.01

get_columns_day() - Génération des entêtes du dashbord journalier

Génère les noms des colonnes pour un dashbord journalier, basée sur la date de référence.

# Generate the titles for January 15, 2023
columns = get_column_day(date_ref="2023-01-15")
print("Colonnes du dashbord :")
print(columns)
# Exemple de sortie -
# Colonnes du dashbord :
# ['KPIs', '8-janv.', '14-janv.', '15-janv.', '∆ DoD', '∆ SDLW', 'MTD-1', 'MTD', '∆ MTD']

get_columns_day() + get_summay_day() - Génération d'un dashbord journalier

Crée un dashbord avec les noms de colonnes dynamiques.

date_ref = "2023-03-21"
columns = ip.get_column_day(date_ref)[1:9]
summary_day = ip.get_summary_day(df=df, date=date_ref, zone="all_zone", factor="Orange", value="revenu", decimal=3)
df_summary = pd.DataFrame([summary_day], columns=columns)
print(df_summary)
# Exemple de sortie -
# 14-mars  20-mars  21-mars  ∆ DoD  ∆ SDLW     MTD-1       MTD  ∆ MTD
#  54.437   53.981   50.249 -0.069  -0.077  1070.639  1067.452 -0.003

c_rate() - Variation relative

Calcule la variation entre de la valeur x par rapport à y.

# Différence absolue (même si y=0)
print(ip.c_rate(x=100, y=0, abs=True))
# Exemple de sortie - 100.0

# Normalisation: compare Février (28j) vs Janvier (31j), réduit à 30j
print(ip.c_rate(x=280, y=310, abs=False, nx=28, ny=31, nn=30))
# Exemple de sortie - 0.0

📄 Documentation

Voir la documentation et notebooks Signale un bug ou demande une fonctionnalité : GitHub Issues

Contribuer

Toute contribution est la bienvenue ! Que ce soit pour corriger une erreur, ajouter une fonction, ou améliorer la documentation.

Consulte le fichier CONTRIBUTING.md pour commencer.

Contact

• Github : https://github.com/ipatriqIP/iperform
• Auteur : [e-mail]
• Licence : MIT