diff --git a/docs/source/tutorials/index.rst b/docs/source/tutorials/index.rst index 118aa4d..fba96b4 100644 --- a/docs/source/tutorials/index.rst +++ b/docs/source/tutorials/index.rst @@ -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 `_ - Introductory workflow and basic network discovery. +* `Optimal Causation Entropy Tutorial `_ - Detailed walk-through of the oCSE algorithm. +* `Gaussian Causal Discovery Example `_ - Network discovery under Gaussian assumptions. +* `kNN Causal Discovery Example `_ - Nonparametric causal discovery using k-Nearest Neighbors. +* `Geometric kNN Causal Discovery Example `_ - Nonparametric estimation using geometric kNN entropy corrections. +* `KDE Causal Discovery Example `_ - Nonparametric causal discovery using Kernel Density Estimation. +* `Poisson Causal Discovery Example `_ - Causal discovery for count and event data with Poisson dynamics. \ No newline at end of file diff --git a/notebooks/geometric_knn_causal_discovery_example.ipynb b/notebooks/geometric_knn_causal_discovery_example.ipynb index 1dd1e48..7d25479 100644 --- a/notebooks/geometric_knn_causal_discovery_example.ipynb +++ b/notebooks/geometric_knn_causal_discovery_example.ipynb @@ -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", @@ -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", @@ -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",