Tsallis entropy-KETEWS

ZENODO DEPOSIT — METADATA AND DESCRIPTION
==========================================
Use this text exactly in the Zenodo form fields.

TITLE:
------
KATEWS: KDE-Adaptive Tsallis Early-Warning System for African Equity
Markets — Code and Data Reproducibility Scripts

AUTHORS:
--------
Moroke, Ntebogang Dinah
  Affiliation: North-West University, Faculty of Economic and
               Management Sciences, Mafikeng Campus, South Africa
  ORCID: 0000-0001-8545-1860

RESOURCE TYPE:
--------------
Software

DESCRIPTION (paste this into the Description box):
---------------------------------------------------
This repository contains the source code and data reproducibility
scripts for the KATEWS (KDE-Adaptive Tsallis Early-Warning System)
framework, developed for the detection of extreme market events in
African equity markets.

KATEWS is a three-stage early-warning system that resolves three
structural limitations of existing entropy-based EWS: (1) it employs
a Hill-estimator-guided adaptive kernel density estimator that
calibrates separate bandwidths for the body and tail regions of the
return distribution; (2) it drives the Tsallis entropic index q(t)
dynamically via an exponentially weighted moving average of squared
returns, making the system more sensitive during volatile regimes;
and (3) it determines the alert threshold via peaks-over-threshold
generalised Pareto distribution fitting on training-period entropy
exceedances.

The framework is validated on daily returns from three African equity
market proxies spanning 2003 to 2025: the Johannesburg Stock Exchange
(EZA ETF, N=5,760), the Nigerian Exchange (NGE ETF, N=2,767), and the
Egyptian Exchange (COMI.CA, N=5,772). Across eleven crisis episodes
(2008 GFC, 2015 commodity shock, 2020 COVID-19, 2022 Fed rate shock),
KATEWS achieves an average lead time of 9.8 trading days at an 11.2%
false-positive rate, compared to 3.6 days for fixed-bandwidth
KDE-Tsallis and 1.0 day for GARCH.

FILES INCLUDED:

  KATEWS_data_download.py
    Downloads all three market return series (EZA, NGE, COMI.CA)
    from Yahoo Finance via yfinance. Run this script first. The
    script verifies the key distributional statistics against the
    paper's Table 1 (N, volatility, skewness, excess kurtosis).
    Market data are not included in this repository because they
    are proprietary to Yahoo Finance and the underlying exchanges;
    the script provides full reproducibility.

  KATEWS_analysis.py
    Full KATEWS analysis pipeline. Reproduces all parameter
    estimates (Hill tail index, adaptive bandwidths, dynamic
    entropic index, GPD threshold), performance metrics (lead
    times, false-positive rates), statistical tests
    (Diebold-Mariano, paired t-test, Wilcoxon signed-rank,
    bootstrap confidence intervals), and saves all intermediate
    arrays (.npy) and results (JSON) to ./katews_outputs/.

HOW TO REPRODUCE:

  Step 1: Install dependencies
    pip install numpy pandas scipy statsmodels arch matplotlib
            scikit-learn yfinance

  Step 2: Download data
    python KATEWS_data_download.py

  Step 3: Run analysis
    python KATEWS_analysis.py

  Expected outputs (verified against paper):
    JSE: lead=10.0d FPR=10.9%
    NGX: lead=13.3d FPR=10.4%
    EGX: lead=7.0d  FPR=11.6%
    Average: lead=9.8d FPR=11.2%

NOTE ON DATA:
  The market return data (EZA, NGE, COMI.CA) are sourced from Yahoo
  Finance and cannot be redistributed under Yahoo Finance terms of
  service. Any researcher can reproduce the exact datasets by running
  KATEWS_data_download.py with Python 3.12 and yfinance >= 1.4.0.

This code is associated with a manuscript currently under review.
The repository will be updated with the full citation upon acceptance.

KEYWORDS:
---------
Tsallis entropy; adaptive kernel density estimation; early-warning
system; financial crisis detection; African equity markets; Hill
estimator; extreme value theory; JSE; NGX; EGX; GARCH; nonparametric

LICENCE:
--------
MIT

ACCESS:
-------
Open Access

RELATED IDENTIFIERS (add after acceptance):
-------------------------------------------
Is supplement to: [DOI of published paper — add when available]

VERSION NOTES:
--------------
v1.0 — Initial deposit, 25 May 2026.
Corresponds to manuscript submitted to Applied Stochastic Models
in Business and Industry on 25 May 2026.