diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b9ad244..13c2fbd 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -293,10 +293,10 @@ Contributions should respect the modular structure: ``` neuro-coherence-framework/ ├── simulations/ # Core computational models -├── analysis/ # Data analysis tools -├── visualization/ # Plotting and visualization -├── tools/ # Utilities and calculators -├── docs/ # Documentation +├── analysis/ # Data analysis tools (EEG, fMRI, integration) +├── data/ # Data generation and resources +├── docs/ # Documentation, summaries, and figures +├── examples/ # Usage examples and demos └── tests/ # Test suite ``` diff --git a/README.md b/README.md index 3aa85ca..5df544e 100644 --- a/README.md +++ b/README.md @@ -244,9 +244,6 @@ neuro-coherence-framework/ ├── LICENSE # MIT License ├── CONTRIBUTING.md # Contribution guidelines ├── CITATION.cff # Citation format -├── CI_SETUP_COMPLETE.md # CI configuration notes -├── IMPLEMENTATION_SUMMARY.md # Implementation status -├── WORKFLOW_SUMMARY.md # Workflow documentation │ ├── setup.py # Package setup ├── setup.cfg # Setup configuration @@ -255,9 +252,27 @@ neuro-coherence-framework/ │ ├── docs/ # Documentation │ ├── CI.md # CI/CD documentation -│ └── theoretical-framework/ # Theory & mathematical foundations -│ ├── 02-neuro-coherence-function.md -│ └── 03-operators.md +│ ├── CI_SETUP_COMPLETE.md # CI configuration notes +│ │ +│ ├── theoretical-framework/ # Theory & mathematical foundations +│ │ ├── 02-neuro-coherence-function.md +│ │ └── 03-operators.md +│ │ +│ ├── summaries/ # Analysis & summary documents +│ │ ├── AI_PERSPECTIVE_ANALYSIS.md # AI analysis of framework +│ │ ├── FINDINGS_SUMMARY.md # Repository findings +│ │ ├── IMPLEMENTATION_SUMMARY.md # Implementation status +│ │ ├── READING_GUIDE.md # Guide to understanding the repo +│ │ └── WORKFLOW_SUMMARY.md # Workflow documentation +│ │ +│ └── figures/ # Generated visualizations +│ ├── longitudinal_analysis.png +│ ├── multimodal_comparison.png +│ ├── operator_correlations.png +│ ├── parameter_sensitivity.png +│ ├── perturbation_experiment.png +│ ├── quickstart_results.png +│ └── recovery_comparison.png │ ├── simulations/ # Computational Models │ └── core/ # Core implementations @@ -301,18 +316,9 @@ neuro-coherence-framework/ │ ├── full_analysis.py # Complete workflow │ └── custom_simulation.py # Customization guide │ -├── .github/ # GitHub automation -│ └── workflows/ -│ └── ci.yml # Continuous integration -│ -└── *.png # Generated visualizations - ├── longitudinal_analysis.png - ├── multimodal_comparison.png - ├── operator_correlations.png - ├── parameter_sensitivity.png - ├── perturbation_experiment.png - ├── quickstart_results.png - └── recovery_comparison.png +└── .github/ # GitHub automation + └── workflows/ + └── ci.yml # Continuous integration ``` --- @@ -354,7 +360,7 @@ Its purpose is to test **computational predictions**, not propose treatment. - Multimodal biomarker integration - Simulation architecture -(Diagrams live in `visualization/figures/`.) +(Generated diagrams are stored in `docs/figures/`.) --- diff --git a/CI_SETUP_COMPLETE.md b/docs/CI_SETUP_COMPLETE.md similarity index 100% rename from CI_SETUP_COMPLETE.md rename to docs/CI_SETUP_COMPLETE.md diff --git a/longitudinal_analysis.png b/docs/figures/longitudinal_analysis.png similarity index 100% rename from longitudinal_analysis.png rename to docs/figures/longitudinal_analysis.png diff --git a/multimodal_comparison.png b/docs/figures/multimodal_comparison.png similarity index 100% rename from multimodal_comparison.png rename to docs/figures/multimodal_comparison.png diff --git a/operator_correlations.png b/docs/figures/operator_correlations.png similarity index 100% rename from operator_correlations.png rename to docs/figures/operator_correlations.png diff --git a/parameter_sensitivity.png b/docs/figures/parameter_sensitivity.png similarity index 100% rename from parameter_sensitivity.png rename to docs/figures/parameter_sensitivity.png diff --git a/perturbation_experiment.png b/docs/figures/perturbation_experiment.png similarity index 100% rename from perturbation_experiment.png rename to docs/figures/perturbation_experiment.png diff --git a/docs/figures/quickstart_results.png b/docs/figures/quickstart_results.png new file mode 100644 index 0000000..17b0b88 Binary files /dev/null and b/docs/figures/quickstart_results.png differ diff --git a/recovery_comparison.png b/docs/figures/recovery_comparison.png similarity index 100% rename from recovery_comparison.png rename to docs/figures/recovery_comparison.png diff --git a/AI_PERSPECTIVE_ANALYSIS.md b/docs/summaries/AI_PERSPECTIVE_ANALYSIS.md similarity index 100% rename from AI_PERSPECTIVE_ANALYSIS.md rename to docs/summaries/AI_PERSPECTIVE_ANALYSIS.md diff --git a/FINDINGS_SUMMARY.md b/docs/summaries/FINDINGS_SUMMARY.md similarity index 100% rename from FINDINGS_SUMMARY.md rename to docs/summaries/FINDINGS_SUMMARY.md diff --git a/IMPLEMENTATION_SUMMARY.md b/docs/summaries/IMPLEMENTATION_SUMMARY.md similarity index 99% rename from IMPLEMENTATION_SUMMARY.md rename to docs/summaries/IMPLEMENTATION_SUMMARY.md index 706ad85..bb2cf8e 100644 --- a/IMPLEMENTATION_SUMMARY.md +++ b/docs/summaries/IMPLEMENTATION_SUMMARY.md @@ -106,7 +106,7 @@ Depressive Ψ (mean): 0.1815 - Episode highlighting **Generated Figures** (7 total): -1. `quickstart_results.png` - 4-panel overview +1. `docs/figures/quickstart_results.png` - 4-panel overview 2. `perturbation_experiment.png` - Multiple perturbations 3. `parameter_sensitivity.png` - 4-parameter analysis 4. `recovery_comparison.png` - Recovery rates diff --git a/READING_GUIDE.md b/docs/summaries/READING_GUIDE.md similarity index 94% rename from READING_GUIDE.md rename to docs/summaries/READING_GUIDE.md index 1158c8e..d64d6f6 100644 --- a/READING_GUIDE.md +++ b/docs/summaries/READING_GUIDE.md @@ -82,13 +82,13 @@ Bipolar disorder = coherence breakdown, not just chemical imbalance **Visual Evidence:** Look at the generated PNG files: -1. `quickstart_results.png` - Basic Ψ across states -2. `longitudinal_analysis.png` - Temporal dynamics -3. `parameter_sensitivity.png` - Operator impacts -4. `multimodal_comparison.png` - EEG + fMRI integration -5. `perturbation_experiment.png` - Recovery curves -6. `recovery_comparison.png` - Healing dynamics -7. `operator_correlations.png` - How operators relate to Ψ +1. `docs/figures/quickstart_results.png` - Basic Ψ across states +2. `docs/figures/longitudinal_analysis.png` - Temporal dynamics +3. `docs/figures/parameter_sensitivity.png` - Operator impacts +4. `docs/figures/multimodal_comparison.png` - EEG + fMRI integration +5. `docs/figures/perturbation_experiment.png` - Recovery curves +6. `docs/figures/recovery_comparison.png` - Healing dynamics +7. `docs/figures/operator_correlations.png` - How operators relate to Ψ **Then Read:** - `FINDINGS_SUMMARY.md` to understand what you're seeing @@ -216,7 +216,7 @@ Each PNG file corresponds to an example script. See `examples/README.md` for whi ### **Sequence A: Quick Understanding (30 minutes)** 1. `FINDINGS_SUMMARY.md` (10 min) 2. `README.md` - skim key sections (10 min) -3. Look at `quickstart_results.png` (2 min) +3. Look at `docs/figures/quickstart_results.png` (2 min) 4. `AI_PERSPECTIVE_ANALYSIS.md` - Executive Summary (8 min) ### **Sequence B: Evaluation for Research (1 hour)** @@ -282,7 +282,7 @@ Neuro-Coherence-Framework/ ├── 📁 tests/ ← Test suite ├── 📁 data/synthetic/ ← Data generators │ -└── 📊 *.png ← Generated results +└── 📁 docs/figures/ ← Generated visualizations ├── quickstart_results.png ├── longitudinal_analysis.png └── ... (7 total) diff --git a/WORKFLOW_SUMMARY.md b/docs/summaries/WORKFLOW_SUMMARY.md similarity index 100% rename from WORKFLOW_SUMMARY.md rename to docs/summaries/WORKFLOW_SUMMARY.md diff --git a/examples/custom_simulation.py b/examples/custom_simulation.py index daf2c17..37239b0 100644 --- a/examples/custom_simulation.py +++ b/examples/custom_simulation.py @@ -65,8 +65,8 @@ def run_perturbation_experiment(): ax.grid(alpha=0.3) plt.tight_layout() - plt.savefig("perturbation_experiment.png", dpi=150) - print("Saved: perturbation_experiment.png\n") + plt.savefig("docs/figures/perturbation_experiment.png", dpi=150) + print("Saved: docs/figures/perturbation_experiment.png\n") def run_parameter_sensitivity(): @@ -139,8 +139,8 @@ def run_parameter_sensitivity(): ax.legend() plt.tight_layout() - plt.savefig("parameter_sensitivity.png", dpi=150) - print("Saved: parameter_sensitivity.png\n") + plt.savefig("docs/figures/parameter_sensitivity.png", dpi=150) + print("Saved: docs/figures/parameter_sensitivity.png\n") def run_recovery_comparison(): @@ -181,8 +181,8 @@ def run_recovery_comparison(): ax.grid(alpha=0.3) plt.tight_layout() - plt.savefig("recovery_comparison.png", dpi=150) - print("Saved: recovery_comparison.png\n") + plt.savefig("docs/figures/recovery_comparison.png", dpi=150) + print("Saved: docs/figures/recovery_comparison.png\n") def run_operator_correlation(): @@ -255,8 +255,8 @@ def run_operator_correlation(): ax.grid(alpha=0.3) plt.tight_layout() - plt.savefig("operator_correlations.png", dpi=150) - print("Saved: operator_correlations.png\n") + plt.savefig("docs/figures/operator_correlations.png", dpi=150) + print("Saved: docs/figures/operator_correlations.png\n") def main(): @@ -276,10 +276,10 @@ def main(): print("=" * 60) print() print("Generated files:") - print(" - perturbation_experiment.png") - print(" - parameter_sensitivity.png") - print(" - recovery_comparison.png") - print(" - operator_correlations.png") + print(" - docs/figures/perturbation_experiment.png") + print(" - docs/figures/parameter_sensitivity.png") + print(" - docs/figures/recovery_comparison.png") + print(" - docs/figures/operator_correlations.png") print() diff --git a/examples/full_analysis.py b/examples/full_analysis.py index 25e18c9..14d6ae7 100644 --- a/examples/full_analysis.py +++ b/examples/full_analysis.py @@ -176,8 +176,8 @@ def compare_healthy_vs_bipolar(): ax.grid(axis="y", alpha=0.3) plt.tight_layout() - plt.savefig("multimodal_comparison.png", dpi=150) - print("\nSaved: multimodal_comparison.png") + plt.savefig("docs/figures/multimodal_comparison.png", dpi=150) + print("\nSaved: docs/figures/multimodal_comparison.png") return results @@ -259,8 +259,8 @@ def longitudinal_analysis(): ax.grid(alpha=0.3) plt.tight_layout() - plt.savefig("longitudinal_analysis.png", dpi=150) - print("Saved: longitudinal_analysis.png") + plt.savefig("docs/figures/longitudinal_analysis.png", dpi=150) + print("Saved: docs/figures/longitudinal_analysis.png") def main(): @@ -291,8 +291,8 @@ def main(): print("Analysis Complete!") print("=" * 60) print("\nGenerated files:") - print(" - multimodal_comparison.png") - print(" - longitudinal_analysis.png") + print(" - docs/figures/multimodal_comparison.png") + print(" - docs/figures/longitudinal_analysis.png") print() diff --git a/examples/quickstart.py b/examples/quickstart.py index d6bf7ed..72528cf 100644 --- a/examples/quickstart.py +++ b/examples/quickstart.py @@ -163,7 +163,7 @@ def main(): plt.tight_layout() # Save figure - output_file = "quickstart_results.png" + output_file = "docs/figures/quickstart_results.png" plt.savefig(output_file, dpi=150, bbox_inches="tight") print(f" Figure saved to: {output_file}") print() diff --git a/quickstart_results.png b/quickstart_results.png deleted file mode 100644 index f96627f..0000000 Binary files a/quickstart_results.png and /dev/null differ