Add tutorial notebook showcasing coefficient computation and metadata correlation

README.md

@@ -73,17 +73,13 @@ cd ccc-gpu
 
 #### 2. Setup Environment with conda-lock
 
-This process uses a temporary environment to manage the conda-lock installation, keeping your base environment clean:
+This process uses [pipx](https://pipx.pypa.io/stable/) to install conda-lock in an isolated environment, keeping your base environment clean:
 
 > **Why conda-lock?** We use conda-lock to ensure **reproducible installations** across different systems. Unlike regular `environment.yml` files, conda-lock provides exact version pins for all packages and their dependencies, preventing version conflicts and ensuring you get the same environment that was tested during development.
 
 ```bash
-# Create temporary environment for conda-lock
-conda create -n ccc-gpu-setup python=3.10 -y  # or: mamba create -n ccc-gpu-setup python=3.10 -y
-conda activate ccc-gpu-setup
-
-# Install conda-lock in temporary environment
-conda install --channel=conda-forge conda-lock -y  # or: mamba install --channel=conda-forge conda-lock -y
+# Install conda-lock using pipx (installs in isolated environment)
+pipx install conda-lock
 
 # Create the main ccc-gpu environment from lock file
 conda-lock install --name ccc-gpu conda-lock.yml  # or: conda-lock install --name ccc-gpu conda-lock.yml --conda mamba
@@ -95,32 +91,6 @@ conda activate ccc-gpu
 pip install .
 ```
 
-#### 3. Optional: Clean up temporary environment
-
-Once installation is complete, you can optionally remove the temporary setup environment:
-
-```bash
-# Remove temporary environment (optional)
-conda deactivate  # Make sure you're not in ccc-gpu-setup
-conda remove -n ccc-gpu-setup --all -y  # or: mamba remove -n ccc-gpu-setup --all -y
-```
-
-#### Alternative: Install conda-lock in base environment
-
-If you prefer to install conda-lock directly in your base environment:
-
-```bash
-# Option 1: Using pip
-pip install conda-lock
-
-# Option 2: Using conda
-conda install --channel=conda-forge conda-lock -y  # or: mamba install --channel=conda-forge conda-lock -y
-
-# Then create environment directly
-conda-lock install --name ccc-gpu conda-lock.yml  # or: conda-lock install --name ccc-gpu conda-lock.yml --conda mamba
-conda activate ccc-gpu
-pip install .
-```
 
 > **Note**: If you prefer to use Mamba for faster package resolution, you can install MiniForge which includes Mamba:
 > ```bash
@@ -139,6 +109,10 @@ bash ./scripts/run_tests.sh python
 ```
 
 ## Usage
+### End-to-End Tutorial
+
+You can find a tutorial showing simplified analysis steps for those we used in our paper in this [notebook](nbs/99-tutorials/05-walkthrough-with-gtex-data.ipynb) using the GTEx v8 data.
+
 
 ### Basic Usage
 
@@ -161,35 +135,16 @@ correlation = ccc(x, y)
 print(f"CCC coefficient: {correlation:.3f}")
 ```
 
-### Controlling Debug Logging
-
-By default, CCC-GPU runs silently without debug output. You can enable detailed logging (including CUDA device information, memory usage, and processing details) using the `CCC_GPU_LOGGING` environment variable:
-
-```bash
-# Run with default behavior (no debug output)
-python your_script.py
-
-# Enable debug logging for troubleshooting
-CCC_GPU_LOGGING=1 python your_script.py
-
-# Or set it for the session
-export CCC_GPU_LOGGING=1
-python your_script.py
-```
-
-This is particularly useful for:
-- Debugging GPU memory issues
-- Understanding CUDA device utilization
-- Monitoring batch processing performance
-- Troubleshooting installation problems
-
 ### Working with Gene Expression Data
 
 CCC-GPU is particularly useful for genomics applications:
 
 ```python
 import pandas as pd
-from ccc.coef import ccc
+# New CCC-GPU implementation import
+from ccc.coef.impl_gpu import ccc
+# Original CCC implementation import
+# from ccc.coef.impl import ccc
 
 # Load gene expression data
 # Assume genes are in columns, samples in rows
@@ -217,6 +172,28 @@ for i, j in zip(top_indices[0], top_indices[1]):
 
 Refer to the original CCC Repository for more usage examples: [https://github.com/greenelab/ccc](https://github.com/greenelab/ccc)
 
+### Controlling Debug Logging
+
+By default, CCC-GPU runs silently without debug output. You can enable detailed logging (including CUDA device information, memory usage, and processing details) using the `CCC_GPU_LOGGING` environment variable:
+
+```bash
+# Run with default behavior (no debug output)
+python your_script.py
+
+# Enable debug logging for troubleshooting
+CCC_GPU_LOGGING=1 python your_script.py
+
+# Or set it for the session
+export CCC_GPU_LOGGING=1
+python your_script.py
+```
+
+This is particularly useful for:
+- Debugging GPU memory issues
+- Understanding CUDA device utilization
+- Monitoring batch processing performance
+- Troubleshooting installation problems
+
 ## Performance Benchmarks
 
 CCC-GPU provides significant performance improvements over CPU-only implementations:

docs/source/installation.rst

@@ -65,19 +65,15 @@ Install from source using the provided conda-lock environment:
 2. Setup Environment with conda-lock
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-This process uses a temporary environment to manage the conda-lock installation, keeping your base environment clean:
+This process uses pipx to install conda-lock in an isolated environment, keeping your base environment clean:
 
 .. note::
    **Why conda-lock?** We use conda-lock to ensure **reproducible installations** across different systems. Unlike regular ``environment.yml`` files, conda-lock provides exact version pins for all packages and their dependencies, preventing version conflicts and ensuring you get the same environment that was tested during development.
 
 .. code-block:: bash
 
-    # Create temporary environment for conda-lock
-    conda create -n ccc-gpu-setup python=3.10 -y  # or: mamba create -n ccc-gpu-setup python=3.10 -y
-    conda activate ccc-gpu-setup
-
-    # Install conda-lock in temporary environment
-    conda install --channel=conda-forge conda-lock -y  # or: mamba install --channel=conda-forge conda-lock -y
+    # Install conda-lock using pipx (installs in isolated environment)
+    pipx install conda-lock
 
     # Create the main ccc-gpu environment from lock file
     conda-lock install --name ccc-gpu conda-lock.yml  # or: conda-lock install --name ccc-gpu conda-lock.yml --conda mamba
@@ -88,21 +84,23 @@ This process uses a temporary environment to manage the conda-lock installation,
     # Install the package from source
     pip install .
 
-3. Optional: Clean up temporary environment
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. note::
+   If you don't have pipx installed, you can install it with ``pip install pipx`` or follow the `pipx installation guide <https://pypa.github.io/pipx/installation/>`_.
+
+3. Optional: Remove conda-lock
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Once installation is complete, you can optionally remove the temporary setup environment:
+If you no longer need conda-lock after installation, you can remove it:
 
 .. code-block:: bash
 
-    # Remove temporary environment (optional)
-    conda deactivate  # Make sure you're not in ccc-gpu-setup
-    conda remove -n ccc-gpu-setup --all -y  # or: mamba remove -n ccc-gpu-setup --all -y
+    # Remove conda-lock (optional)
+    pipx uninstall conda-lock
 
 Alternative: Install conda-lock in base environment
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-If you prefer to install conda-lock directly in your base environment:
+If you prefer to install conda-lock directly in your base environment instead of using pipx:
 
 .. code-block:: bash