feat: add comprehensive repository structure

configs/default_config.yaml

@@ -0,0 +1,15 @@
+# Default System Configuration
+app:
+  title: "AnTiEnTRopY"
+  version: "1.0.0"
+  theme: "dark"
+  port: 8501
+
+ui:
+  colors:
+    primary: "#030d12"
+    accent: "#00e5a0"
+    text: "#e0e0e0"
+  fonts:
+    main: "IBM Plex Mono"
+    header: "DM Serif Display"

configs/hyperparameters.yaml

@@ -0,0 +1,26 @@
+# Algorithm Hyperparameters
+
+clock:
+  top_k_features: 5000
+  cv_folds: 5
+  alphas: [0.001, 0.01, 0.05, 0.1, 0.5, 1.0]
+  l1_ratios: [0.1, 0.5, 0.7, 0.9, 0.95, 1.0]
+
+entropy:
+  epsilon: 1e-10
+
+hrf:
+  pca_components: 200
+  n_neighbors: 5
+  omega_grid: [0.1, 1.0, 5.0, 10.0, 20.0, 50.0]
+  gamma_grid: [0.01, 0.1, 0.5, 1.0, 2.0]
+
+reversal:
+  young_percentile: 20
+  old_percentile: 20
+  intervention_sweep_steps: 20
+
+immortality:
+  monte_carlo_trials: 500
+  time_horizon: 30
+  delta_t: 0.5

configs/logging.yaml

@@ -0,0 +1,18 @@
+version: 1
+formatters:
+  simple:
+    format: '%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+handlers:
+  console:
+    class: logging.StreamHandler
+    level: INFO
+    formatter: simple
+    stream: ext://sys.stdout
+  file:
+    class: logging.FileHandler
+    level: DEBUG
+    formatter: simple
+    filename: logs/antientropy.log
+root:
+  level: INFO
+  handlers: [console, file]

data/README.md

@@ -0,0 +1,6 @@
+# Data Directory
+
+This directory contains the methylation datasets used by AnTiEnTRopY.
+
+- `raw/`: Raw CSV files containing age and beta values. Place your dataset here.
+- `processed/`: Intermediate matrices or filtered datasets generated by scripts.

data/data_dictionary.md

@@ -0,0 +1,10 @@
+# Data Dictionary
+
+Input files are expected to be in CSV format with the following schema:
+
+| Column Name | Data Type | Description | Range / Constraints |
+|---|---|---|---|
+| `age` | Float | The chronological age of the sample | $> 0$ |
+| `cg[0-9]{8}` | Float | Methylation beta value for the specified CpG site | $[0, 1]$ |
+
+**Missing Values:** Missing beta values are imputed to `0.5` by the system (representing maximum informational entropy).

docs/api_reference.md

@@ -0,0 +1,31 @@
+# API Reference
+
+This document outlines the core classes and functions in the AnTiEnTRopY library.
+
+## EpigeneticEntropy (`EnTRopY.py`)
+- `__init__(self, eps=1e-10)`
+- `calculate_entropy(self, beta_matrix)`
+- `calculate_moi(self, beta_matrix)`
+- `identify_drift_cpgs(self, beta_matrix, ages)`
+
+## BiologicalClock (`CloCk.py`)
+- `__init__(self, top_k=5000)`
+- `fit(self, beta_matrix, ages)`
+- `predict(self, beta_matrix)`
+- `calculate_ieaa(self, predicted_ages, chrono_ages)`
+
+## HRFEpigenetic (`HRF_EpIgEnEtIc.py`)
+- `__init__(self, d_components=200)`
+- `fit(self, beta_matrix, age_classes)`
+- `predict_resonance(self, query_vector)`
+- `spectral_decomposition(self, beta_vector)`
+
+## ReversalSimulator (`ReVeRsAL.py`)
+- `__init__(self, young_ref, old_ref)`
+- `simulate_intervention(self, beta_matrix, p_int)`
+- `generate_reversal_curve(self, max_p_int)`
+
+## ImmortalityEngine (`ImMoRtAlItY.py`)
+- `__init__(self, entropy_rate)`
+- `calculate_escape_velocity(self, reversal_curve, T_interval)`
+- `run_monte_carlo(self, initial_age, n_steps)`

docs/architecture.md

@@ -0,0 +1,12 @@
+# System Architecture
+
+## Core Modules
+1. **`AnTiEnTRopY.py`**: The main Streamlit orchestrator. Handles file uploads, parameters, and tab rendering.
+2. **`EnTRopY.py`**: Calculates Shannon entropy, Methylation Order Index (MOI), and identifies drifting CpGs.
+3. **`CloCk.py`**: Implements an ElasticNet-based biological age predictor.
+4. **`HRF_EpIgEnEtIc.py`**: A novel classifier using a Harmonic Resonance Field (HRF) approach and Fast Fourier Transform for spectral analysis.
+5. **`ReVeRsAL.py`**: Simulates partial epigenetic reprogramming by shifting high-drift CpGs towards young reference values.
+6. **`ImMoRtAlItY.py`**: Uses Monte Carlo simulations to model the conditions for "epigenetic escape velocity."
+
+## Data Flow
+Upload -> Preprocessing -> Clock Training -> Entropy Calculation -> HRF Classification -> Reversal Simulation -> Monte Carlo Projections -> Research Report Generation.

docs/installation_guide.md

@@ -0,0 +1,29 @@
+# Installation Guide
+
+## Prerequisites
+- Python 3.9+
+- pip (Python package manager)
+
+## Steps
+1. Clone the repository:
+   ```bash
+   git clone https://github.com/Devanik21/AnTiEnTRopY.git
+   cd AnTiEnTRopY
+   ```
+
+2. (Optional but recommended) Create a virtual environment:
+   ```bash
+   python -m venv venv
+   source venv/bin/activate  # On Windows: venv\Scripts\activate
+   ```
+
+3. Install dependencies:
+   ```bash
+   pip install -r requirements.txt
+   ```
+
+## Using Docker
+A `docker-compose.yml` is provided for containerized deployment:
+```bash
+docker-compose up --build
+```

docs/theory/mathematical_framework.md

@@ -0,0 +1,15 @@
+# Mathematical Framework
+
+This document details the mathematical models underlying the AnTiEnTRopY engines.
+
+## 1. Epigenetic Entropy
+The site-wise informational disorder is quantified by the binary Shannon entropy:
+$H(\beta) = -\beta \log_2(\beta) - (1-\beta) \log_2(1-\beta)$
+
+## 2. Harmonic Resonance Field (HRF)
+The resonance energy for class c is given by:
+$E_c(\mathbf{q}) = \sum_{i=1}^{k} \exp(-\gamma\|\mathbf{q} - \mathbf{x}^{(c)}_i\|_2^2) \cdot (1 + \cos(\omega_c\|\mathbf{q} - \mathbf{x}^{(c)}_i\|_2))$
+
+## 3. Escape Velocity Condition
+The system is at epigenetic escape velocity when the net biological age change per cycle is negative or zero:
+$\Delta a_{\text{net}}(p, T) = T - R(p) \le 0$

docs/user_manual.md

@@ -0,0 +1,14 @@
+# User Manual
+
+## Overview
+AnTiEnTRopY is an interactive Streamlit application. It takes a CSV of DNA methylation beta values and chronological ages, and outputs a suite of analyses across 6 main tabs.
+
+## Preparing Data
+Your input CSV must contain:
+1. An `age` column (chronological age in years).
+2. CpG site columns (e.g., `cg00000029`), where values are between 0 and 1.
+
+## Navigation
+1. **Upload Data:** Use the sidebar to upload your CSV file.
+2. **Parameters:** Adjust parameters such as top-K CpGs for the clock or intervention percentage.
+3. **Tabs:** Navigate through Biological Clock, Epigenetic Entropy, HRF Classifier, Reversal Simulator, Immortality Engine, and the Research Report to view different analyses.

models/README.md

@@ -0,0 +1,6 @@
+# Models Directory
+
+This directory stores serialized models and parameter weights.
+
+- `pretrained/`: Holds pre-trained weights for the Biological Clock or HRF Classifier.
+- `model_registry.json`: Tracks versions and metadata for models.

models/model_registry.json

@@ -0,0 +1,11 @@
+{
+  "models": [
+    {
+      "id": "clock_v1",
+      "type": "ElasticNetCV",
+      "description": "Baseline biological clock trained on 5000 high-variance CpGs.",
+      "file": "pretrained/clock_v1.pkl",
+      "created_at": "2024-05-20"
+    }
+  ]
+}

notebooks/01_exploratory_data_analysis.ipynb

@@ -0,0 +1,58 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Exploratory Data Analysis\n",
+    "\n",
+    "This notebook provides a template for loading and performing basic exploratory analysis on methylation data before running the AnTiEnTRopY engines."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import pandas as pd\n",
+    "import matplotlib.pyplot as plt\n",
+    "import seaborn as sns\n",
+    "\n",
+    "# plt.style.use('dark_background')"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Load data\n",
+    "# df = pd.read_csv('../data/raw/dataset.csv')\n",
+    "# df.head()"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.9.0"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 4
+}

notebooks/02_clock_calibration.ipynb

@@ -0,0 +1,60 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Clock Calibration\n",
+    "\n",
+    "Template for standalone training and evaluation of the ElasticNet Biological Clock."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import sys\n",
+    "import os\n",
+    "sys.path.append(os.path.abspath('..'))\n",
+    "\n",
+    "from CloCk import BiologicalClock\n",
+    "import pandas as pd"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Initialize and train clock\n",
+    "# clock = BiologicalClock(top_k=5000)\n",
+    "# ... load data ...\n",
+    "# metrics = clock.fit(beta_matrix, ages)"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.9.0"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 4
+}

notebooks/03_entropy_analysis.ipynb

@@ -0,0 +1,47 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Entropy Analysis\n",
+    "\n",
+    "Detailed exploration of Shannon entropy and Methylation Order Index (MOI)."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import sys\n",
+    "import os\n",
+    "sys.path.append(os.path.abspath('..'))\n",
+    "\n",
+    "from EnTRopY import EpigeneticEntropy"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.9.0"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 4
+}