Skip to content

docs: finish tutorials documentation #30

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
chaewon-research wants to merge 1 commit into
base: main
Choose a base branch
from
+38 −118
Open

docs: finish tutorials documentation #30

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
65 changes: 32 additions & 33 deletions docs/source/tutorials/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,47 +1,46 @@
========
Tutorials
========
=========

This section contains practical examples of using the Causation Entropy library.
This section provides practical examples and guides for using the ``causationentropy`` package for causal network discovery from time-series data.

.. toctree::
:maxdepth: 2

basic_usage

Interactive Notebooks
====================
Basic Usage
-----------

For interactive examples, check out our Jupyter notebooks:
Below is a self-contained example demonstrating how to discover a causal network from synthetic time-series data:

.. toctree::
:maxdepth: 1
:glob:
.. code-block:: python

notebooks/*
Create examples/basic_usage.rst:
import numpy as np
from causationentropy import discover_network

Basic Usage
===========
# 1. Generate synthetic data (X0 causes X1 at lag 1)
np.random.seed(42)
n_samples = 200
x0 = np.random.normal(0, 1, n_samples)
x1 = np.zeros(n_samples)

This example demonstrates the fundamental usage of the library.
for t in range(1, n_samples):
x1[t] = 0.7 * x0[t - 1] + 0.3 * np.random.normal()

Simple Example
==============
# Combine into a 2D array of shape (n_samples, n_variables)
data = np.column_stack([x0, x1])

.. code-block:: python
# 2. Run causal network discovery
network = discover_network(data, max_lag=2, n_shuffles=50)

from causationentropy import discover_network
# 3. Inspect discovered causal edges
for u, v, attrs in network.edges(data=True):
print(f"Discovered causal edge: {u} -> {v} (lag: {attrs.get('lag')})")

# Load your time series data (variables as columns, time as rows)
data = pd.read_csv('your_data.csv')
Interactive Notebooks
---------------------

# Discover causal network
network = discover_network(data, method='standard', max_lag=5)
The repository includes the following interactive Jupyter notebooks demonstrating different estimators and use cases:

.. figure:: ../_static/images/diagrams/basic_flow.png
:alt: Basic workflow diagram
:width: 600px
:align: center

The `discover_network` method returns a NetworkX MultiDiGraph object.
* `Quickstart Notebook <https://github.com/Center-For-Complex-Systems-Science/causationentropy/blob/main/notebooks/Quickstart.ipynb>`_ - Introductory workflow and basic network discovery.
* `Optimal Causation Entropy Tutorial <https://github.com/Center-For-Complex-Systems-Science/causationentropy/blob/main/notebooks/Optimal_Causation_Entropy_Tutorial.ipynb>`_ - Detailed walk-through of the oCSE algorithm.
* `Gaussian Causal Discovery Example <https://github.com/Center-For-Complex-Systems-Science/causationentropy/blob/main/notebooks/gaussian_causal_discovery_example.ipynb>`_ - Network discovery under Gaussian assumptions.
* `kNN Causal Discovery Example <https://github.com/Center-For-Complex-Systems-Science/causationentropy/blob/main/notebooks/knn_causal_discovery_example.ipynb>`_ - Nonparametric causal discovery using k-Nearest Neighbors.
* `Geometric kNN Causal Discovery Example <https://github.com/Center-For-Complex-Systems-Science/causationentropy/blob/main/notebooks/geometric_knn_causal_discovery_example.ipynb>`_ - Nonparametric estimation using geometric kNN entropy corrections.
* `KDE Causal Discovery Example <https://github.com/Center-For-Complex-Systems-Science/causationentropy/blob/main/notebooks/kde_causal_discovery_example.ipynb>`_ - Nonparametric causal discovery using Kernel Density Estimation.
* `Poisson Causal Discovery Example <https://github.com/Center-For-Complex-Systems-Science/causationentropy/blob/main/notebooks/poisson_causal_discovery_example.ipynb>`_ - Causal discovery for count and event data with Poisson dynamics.
91 changes: 6 additions & 85 deletions notebooks/geometric_knn_causal_discovery_example.ipynb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,21 +28,9 @@
},
{
"cell_type": "code",
"execution_count": 1,
"execution_count": null,
"metadata": {},
"outputs": [
{
"ename": "ModuleNotFoundError",
"evalue": "No module named 'causationentropy'",
"output_type": "error",
"traceback": [
"\u001b[0;31m---------------------------------------------------------------------------\u001b[0m",
"\u001b[0;31mModuleNotFoundError\u001b[0m Traceback (most recent call last)",
"Cell \u001b[0;32mIn[1], line 10\u001b[0m\n\u001b[1;32m 7\u001b[0m warnings\u001b[38;5;241m.\u001b[39mfilterwarnings(\u001b[38;5;124m'\u001b[39m\u001b[38;5;124mignore\u001b[39m\u001b[38;5;124m'\u001b[39m)\n\u001b[1;32m 9\u001b[0m \u001b[38;5;66;03m# Import causal discovery components\u001b[39;00m\n\u001b[0;32m---> 10\u001b[0m \u001b[38;5;28;01mfrom\u001b[39;00m\u001b[38;5;250m \u001b[39m\u001b[38;5;21;01mcausationentropy\u001b[39;00m\u001b[38;5;21;01m.\u001b[39;00m\u001b[38;5;21;01mcore\u001b[39;00m\u001b[38;5;21;01m.\u001b[39;00m\u001b[38;5;21;01mdiscovery\u001b[39;00m\u001b[38;5;250m \u001b[39m\u001b[38;5;28;01mimport\u001b[39;00m discover_network\n\u001b[1;32m 11\u001b[0m \u001b[38;5;28;01mfrom\u001b[39;00m\u001b[38;5;250m \u001b[39m\u001b[38;5;21;01mcausationentropy\u001b[39;00m\u001b[38;5;21;01m.\u001b[39;00m\u001b[38;5;21;01mdatasets\u001b[39;00m\u001b[38;5;21;01m.\u001b[39;00m\u001b[38;5;21;01msynthetic\u001b[39;00m\u001b[38;5;250m \u001b[39m\u001b[38;5;28;01mimport\u001b[39;00m linear_stochastic_gaussian_process\n\u001b[1;32m 13\u001b[0m \u001b[38;5;66;03m# Set plotting style\u001b[39;00m\n",
"\u001b[0;31mModuleNotFoundError\u001b[0m: No module named 'causationentropy'"
]
}
],
"outputs": [],
"source": [
"import numpy as np\n",
"import matplotlib.pyplot as plt\n",
Expand Down Expand Up @@ -387,39 +375,9 @@
},
{
"cell_type": "code",
"execution_count": 10,
"execution_count": null,
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"\n",
"DETAILED PERFORMANCE ANALYSIS\n",
"==================================================\n",
"\n",
"STANDARD METHOD:\n",
" Precision: 0.000\n",
" Recall: 0.000\n",
" F1-Score: 0.000\n",
" True Positives: 0\n",
" False Positives: 0\n",
" True Negatives: 15\n",
" False Negatives: 5\n",
" ROC-AUC: 0.500\n",
"\n",
"ALTERNATIVE METHOD:\n",
" Precision: 0.333\n",
" Recall: 0.400\n",
" F1-Score: 0.364\n",
" True Positives: 2\n",
" False Positives: 4\n",
" True Negatives: 11\n",
" False Negatives: 3\n",
" ROC-AUC: 0.567\n"
]
}
],
"outputs": [],
"source": [
"from sklearn.metrics import precision_score, recall_score, f1_score, confusion_matrix\n",
"\n",
Expand Down Expand Up @@ -493,46 +451,9 @@
},
{
"cell_type": "code",
"execution_count": 11,
"execution_count": null,
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"\n",
"============================================================\n",
"EXPERIMENT CONCLUSIONS - GAUSSIAN CAUSAL DISCOVERY\n",
"============================================================\n",
"\n",
"📊 DATA CHARACTERISTICS:\n",
" • Time series length: 200\n",
" • Number of variables: 5\n",
" • Ground truth edges: 5\n",
" • Data type: Linear stochastic Gaussian process\n",
"\n",
"🔍 DISCOVERY RESULTS:\n",
" • Standard method: 0 edges, AUC = 0.500\n",
" • Alternative method: 6 edges, AUC = 0.567\n",
"\n",
"🏆 BEST PERFORMING METHOD: ALTERNATIVE\n",
" • ROC-AUC Score: 0.567\n",
" • Edges discovered: 6\n",
"\n",
"💡 KEY INSIGHTS:\n",
" • Gaussian information method works well for linear stochastic processes\n",
" • Performance depends on coupling strength and data length\n",
" • Different discovery methods (standard vs alternative) may have trade-offs\n",
"\n",
"📝 NOTES:\n",
" • This experiment uses synthetic data with known ground truth\n",
" • Real-world performance may vary based on data characteristics\n",
" • Consider parameter tuning for optimal performance\n",
"\n",
"Experiment completed successfully! 🎉\n"
]
}
],
"outputs": [],
"source": [
"print(\"\\n\" + \"=\"*60)\n",
"print(\"EXPERIMENT CONCLUSIONS - GAUSSIAN CAUSAL DISCOVERY\")\n",
Expand Down