afrikana-analytics

Production-ready analytics toolkit for any operator managing customers, infrastructure, and growth decisions at scale

Built from real analytical work across African markets. Applicable to any subscription, usage-based, or network-deployment business — mobility, fintech, telecoms, utilities, logistics, or SaaS.

Covers the full data-to-decision stack: churn prediction, customer lifetime value, financial modelling, site deployment optimisation, and demand forecasting.

---

Installation

# From GitHub Packages
pip install afrikana-analytics

# From source
git clone https://github.com/Peterson-Muriuki/afrikana-analytics
cd afrikana-analytics
pip install -e .

---

Quick Start

from afrikana.churn    import ChurnScorer
from afrikana.ltv      import LTVCalculator
from afrikana.financial import FinancialModel
from afrikana.stations  import StationOptimizer
from afrikana.forecast  import DemandForecaster

# --- Churn prediction ---
scorer = ChurnScorer()
scorer.fit(customers_df)
at_risk = scorer.at_risk(customers_df, threshold=0.5)
print(f"At-risk customers: {len(at_risk)}")
print(scorer.feature_importances())

# --- Customer LTV ---
calc   = LTVCalculator(gross_margin=0.62)
result = calc.compute(customers_df)
print(calc.tier_summary(result))
print(calc.revenue_at_risk(result))

# --- Station financial model ---
model = FinancialModel(swap_price_usd=2.50, n_stations=20)
print(model.unit_economics())
print(model.breakeven())
print(model.dcf())
print(model.scenarios())
mc = model.monte_carlo(n_sims=2000)
print(f"NPV P50: ${mc['npv_p50']:,.0f}  Prob +ve NPV: {mc['prob_positive_npv']}%")

# --- Deployment optimisation ---
opt        = StationOptimizer()
candidates = opt.generate_grid((-1.286389, 36.817223), n=40)
scored     = opt.score(candidates, existing_stations_df)
print(opt.recommend(scored, top_n=5))

# --- Demand forecasting ---
fc       = DemandForecaster()
daily    = fc.prepare_daily(swap_events_df)
forecast = fc.predict(daily, periods=30)
print(fc.forecast_summary(forecast))

---

Modules

ChurnScorer

Gradient Boosting churn predictor for subscription/usage-based mobility businesses.

from afrikana.churn import ChurnScorer, ChurnScorerConfig

config = ChurnScorerConfig(n_estimators=200, verbose=True)
scorer = ChurnScorer(config)
scorer.fit(df)                       # trains and evaluates on held-out split
scored = scorer.score(df)           # adds churn_score [0-1] and churn_risk tier
at_risk = scorer.at_risk(df, 0.6)  # customers above threshold, sorted
scorer.feature_importances()        # what drives churn most
print(scorer.summary())             # {"auc": 0.82, "top_feature": "last_swap_days_ago", ...}

Required columns: swap_freq_monthly, last_swap_days_ago, tenure_months, monthly_revenue, churned (0/1 target)

---

LTVCalculator

Discounted survival-adjusted Customer Lifetime Value with Bronze/Silver/Gold tiers.

from afrikana.ltv import LTVCalculator

calc = LTVCalculator(gross_margin=0.62, discount_rate_annual=0.12, max_horizon_months=36)
df   = calc.compute(customers_df)      # adds ltv, ltv_tier, expected_lifetime
calc.tier_summary(df)                  # count, avg_ltv, total_ltv per tier
calc.segment_summary(df, "country")    # LTV by country / segment / city
calc.revenue_at_risk(df, threshold=0.5)

Required columns: churn_probability (or churn_score), monthly_revenue, tenure_months

---

FinancialModel

Full financial model for an EV swap station network.

from afrikana.financial import FinancialModel

model = FinancialModel(
    swap_price_usd=2.50,
    swaps_per_station_day=18,
    n_stations=20,
    gross_margin_pct=0.62,
    discount_rate_annual=0.12,
)

model.unit_economics()   # per-station P&L: revenue, EBITDA, NOPAT, contribution/swap
model.pl_projection()    # 36-month network P&L as DataFrame
model.cash_flow()        # operating CF, capex, FCF, cumulative cash
model.breakeven()        # swaps/day needed, margin of safety, payback period
model.dcf()              # NPV, IRR, ROI, terminal value
model.scenarios()        # Base / Bull / Bear comparison table
model.monte_carlo(2000)  # P10/P50/P90 NPV distribution, VaR 95%, prob +ve NPV

---

StationOptimizer

Multi-criteria deployment scorer for new swap station locations.

from afrikana.stations import StationOptimizer, OptimizerConfig

config = OptimizerConfig(
    weight_demand_density=0.30,
    weight_coverage_gap=0.25,
    weight_revenue_potential=0.25,
    weight_underserved=0.20,
)
opt = StationOptimizer(config)

candidates  = opt.generate_grid((-1.286, 36.817), n=40)  # synthetic grid
scored      = opt.score(candidates, existing_stations_df)
top5        = opt.recommend(scored, top_n=5)
stats       = opt.coverage_stats(scored)

Required columns in existing_stations_df: lat, lon, status

---

DemandForecaster

Holt-Winters time-series forecaster with confidence intervals.

from afrikana.forecast import DemandForecaster

fc       = DemandForecaster(seasonal_periods=7)
daily    = fc.prepare_daily(swap_events_df)
monthly  = fc.prepare_monthly(swap_events_df)
forecast = fc.predict(daily, periods=30)   # date, forecast, lower, upper
summary  = fc.forecast_summary(forecast)
peaks    = fc.peak_hours(swap_events_df)   # 24-row hour-of-day breakdown

---

Running the Demo

pip install -e .
python examples/spiro_demo.py

---

Running Tests

pip install -e ".[dev]"
pytest tests/ -v --cov=afrikana

---

Target Markets

Built for and tested against data patterns from:

Country	Cities	Currency
Kenya	Nairobi, Mombasa, Kisumu, Nakuru	KES
Nigeria	Lagos, Abuja, Kano, Port Harcourt	NGN
Rwanda	Kigali, Butare, Gisenyi	RWF
Uganda	Kampala, Entebbe, Jinja	UGX
Ghana	Accra, Kumasi, Tamale	GHS
Ethiopia	Addis Ababa, Dire Dawa	ETB

---

Author

Peterson Mutegi — Data Analyst · AI Engineer · Financial Engineer
Nairobi, Kenya · pitmuriuki@gmail.com
GitHub · [LinkedIn

Built on top of real analytical work for African EV mobility operations.

---

License

MIT — see LICENSE for details.