Metadata-Version: 2.4
Name: QSignature
Version: 1.0.6
Summary: Data Physics Framework for Physical Systems
Author-email: Ahmad Muhammad <ahmadmuhammad325@gmail.com>, Salim Jibrin Danbatta <salimdambatta@gmail.com>, Muhammad Abubakar Isah <maisah@ticaret.edu.tr>, Ibrahim Yahaya Muhammad <ibrahimyahayamuhammad@gmail.com>, Sulaiman Sulaiman Ahmad <Sulaiman365@gmail.com>, Abdelrahman Ghozlan <aamghuzlan@gmail.com>, Ahmet Sait AlAli <saitnuclear@gmail.com>
Maintainer-email: Ahmad Muhammad <ahmadmuhammad325@gmail.com>, Salim Jibrin Danbatta <salimdambatta@gmail.com>
License: MIT License
Project-URL: Homepage, https://github.com/1030ahmad1030/QSignature
Project-URL: Repository, https://github.com/1030ahmad1030/QSignature
Project-URL: Documentation, https://qsignature.readthedocs.io
Project-URL: Issues, https://github.com/1030ahmad1030/QSignature/issues
Project-URL: Paper (ISDFS 2026), https://ieeexplore.ieee.org/document/11459049
Project-URL: Paper (Theorems), https://www.researchsquare.com/article/rs-8916580/v1
Keywords: signal-processing,time-series,dynamical-systems,classification,centroid,envelope,lambda,qspace,causal-inference,system-identification,data-physics,pdf-analysis,entropy,peak-detection
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: numpy>=1.21.0
Requires-Dist: scipy>=1.7.0
Requires-Dist: pandas>=1.3.0
Requires-Dist: matplotlib>=3.4.0
Requires-Dist: scikit-learn>=1.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=22.0.0; extra == "dev"
Requires-Dist: isort>=5.0.0; extra == "dev"
Requires-Dist: flake8>=5.0.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=5.0.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=1.0.0; extra == "docs"
Requires-Dist: sphinxcontrib-bibtex>=2.0.0; extra == "docs"
Requires-Dist: nbsphinx>=0.9.0; extra == "docs"
Dynamic: license-file

<p align="center">
  <img src="https://raw.githubusercontent.com/1030ahmad1030/QSignature/main/QSignature/QSignaturelogo.jpeg" alt="QSignature Logo" width="200"/>
</p>

# QSignature

**Data Physics Framework.**

[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.19984222.svg)](https://doi.org/10.5281/zenodo.19984222)
[![PyPI version](https://badge.fury.io/py/QSignature.svg)](https://badge.fury.io/py/QSignature)
[![Documentation Status](https://readthedocs.org/projects/qsignature/badge/?version=latest)](https://qsignature.readthedocs.io/)

---

## 📖 Overview

**QSignature** is a **Data Physics framework** that extracts physical signatures from causal response data (R(t)). It transforms raw response data into diagnostic fingerprints that reveal the underlying physical regime, memory structure, dynamical properties and more.

**Key Capabilities:**
- **Assumption free** — No assumptions about system order, linearity, or excitation
- **Data-Driven** — Extracts Physics directly from response data R(t)
- **Domain agnostic** — Works for any causal response signal
- **Interpretable** — Every output has a physical meaning

---

## 🚀 Quick Start

```python
import numpy as np
from QSignature import compute_all, QPDF, QSpace, QSynthetic

# Generate synthetic data
t = np.linspace(0, 10, 1000)
R = QSynthetic.physical.exponential_step(t, tau=2.0, R_inf=1.0)

# Core analysis — timescales and ratios
results = compute_all(t, R)
print(f"τ_s = {results['tau_s']:.4f}")
print(f"τ_u = {results['tau_u']:.4f}")
print(f"Δ_su = {results['Delta_su']:.4f}")
print(f"ρ₂₃ = {results['rho_23']:.4f}")

# Full signature with PDF analysis
results = compute_all(t, R, return_pdf=True)
print(f"PDF Shape: {results['pdf_shape']}")
print(f"Entropy: {results['entropy']:.4f}")
print(f"Time Signature: {results['time_signature']['signature']}")
```

---

## 📦 Installation

```bash
pip install QSignature
```

For development installation:

```bash
git clone https://github.com/1030ahmad1030/QSignature.git
cd QSignature
pip install -e .
```

---

## 🧩 Modules

| Module | Description |
|:---|:---|
| **QSignature Core** | 8 timescale estimators, 3 higher moments, 18 diagnostic ratios |
| **QPDF** | Probability Density Function analysis (entropy, peaks, confidence) |
| **QSpace** | Universal landscape mapping and system classification |
| **QSynthetic** | Synthetic data generation from canonical systems |

---

## 📊 Core Estimators

### Timescales (8)
| Estimator | Definition | Meaning |
|:---|:---|:---|
| `τ_s` | Signed centroid (fallback) | Step-response specific |
| `τ_s2` | Signed centroid (pure) | Response-agnostic |
| `τ_s3` | Signed centroid (hybrid) | Best for oscillatory systems |
| `τ_u` | Unsigned centroid | Always positive, robust |
| `τ_2` | Step-response | Lag area |
| `τ_3` | Autocorrelation | Memory horizon |
| `τ_pole` | Spectral pole | Frequency domain |
| `τ_g` | Generalized persistence | State-based persistence |

### Higher Moments (3)
| Moment | Meaning |
|:---|:---|
| `τ_u2` | Variance (spread) |
| `τ_u3` | Skewness (asymmetry) |
| `τ_u4` | Kurtosis (tailedness) |

### Diagnostic Ratios (18)
| Category | Ratios |
|:---|:---|
| Oscillation & Direction | `Δ_su`, `Δ_su2`, `Δ_su3`, `R_su`, `R_su2`, `R_su3` |
| Memory Type | `ρ₁₃`, `ρ₁₃_s2`, `ρ₁₃_s3`, `ρᵤ₃`, `ρ₂₃` |
| Step Consistency | `ρ₁₂`, `ρ₁₂_s2`, `ρ₁₂_s3` |
| Shape Diagnostics | `κ_u`, `γ_u`, `β_u` |
| Shape vs Memory | `ρᵤ₂,₃`, `ρᵤ₃,₃`, `ρᵤ₄,₃` |

---

## 📈 Full Signature (64 Features)

```python
# Get everything — QSignature + QPDF + Time Signature
results = compute_all(t, R, return_pdf=True)

# Access all features
print(f"τ_s = {results['tau_s']:.4f}")
print(f"Δ_su = {results['Delta_su']:.4f}")
print(f"PDF Shape: {results['pdf_shape']}")
print(f"Entropy: {results['entropy']:.4f}")
print(f"Peaks: {results['n_peaks']}")
print(f"Time Signature: {results['time_signature']['signature']}")
```

---

## 📚 Documentation

- **Official Docs:** [https://qsignature.readthedocs.io/](https://qsignature.readthedocs.io/)
- **GitHub:** [https://github.com/1030ahmad1030/QSignature](https://github.com/1030ahmad1030/QSignature)
- **PyPI:** [https://pypi.org/project/QSignature/](https://pypi.org/project/QSignature/)

### Papers
- **QSignature 1.0 Framework:** [IEEE ISDFS 2026](https://ieeexplore.ieee.org/document/11459049)
- **Theorems for Environmental Signature:** [Research Square](https://www.researchsquare.com/article/rs-8916580/v1)

---

## 🛠️ Requirements

- Python >= 3.9
- numpy >= 1.21.0
- scipy >= 1.7.0
- pandas >= 1.3.0
- matplotlib >= 3.4.0
- scikit-learn >= 1.0.0

---

## 👥 Contributors

The QSignature framework was developed by:

| Name | Role | Affiliation |
|:---|:---|:---|
| **Ahmad Muhammad** | Lead Developer | Data Physics Research Group |
| **Salim Jibrin Danbatta** | Software Engineering | Uskudar University |
| **Muhammad Abubakar Isah** | Mathematics | Istanbul Ticaret Universitesi |
| **Ibrahim Yahaya Muhammad** | Theoretical & Computational Physics | KMUTT |
| **Sulaiman Sulaiman Ahmad** | Electrical Engineering | KFUPM |
| **Abdelrahman Ghozlan** | Physics and Materials Sciences | Qatar University |
| **Ahmet Sait ALALI** | Department of Physics | Istanbul Technical University, Istanbul, Turkiye |
| **Faiz Ahmed Mohammed Elfaki** | Mathematics and Statistics | Qatar University |
| **Asmau Abdullahi** | Physics and Materials Sciences | Qatar University |
| **Aisha Farida Ahmed** | Computer Science | Kano State Polytechnic, Nigeria |
| **Abdulsalam Ahmed Kawu** | Department of Physics | Federal University Kashere, Gombe, Nigeria |
| **DeepSeek AI** | Technical Guidance, Code Review & Documentation | DeepSeek AI |

---

## 📄 License

MIT License — see [LICENSE.txt](LICENSE.txt) for details.

---

## 📝 Citation

If you use QSignature in your research, please cite:

```bibtex
@inproceedings{qsignature2026_isdfs,
  title={QSignature 1.0: A Dynamical Regime Classification Framework for Causal Time Series Data},
  author={Muhammad, Ahmad and Danbatta, Salim Jibrin and Isah, Muhammad Abubakar and others},
  booktitle={IEEE ISDFS 2026},
  year={2026}
}
```
