Skip to content
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

Second round of changes to Andrew's feedback #157

Open
wants to merge 3 commits into
base: dev
Choose a base branch
from
Open

Second round of changes to Andrew's feedback #157

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
b5b5e6c
[fix] fix incorrect boolean check for GPU forwarding
jono3030 Dec 18, 2024
43cba02
[feat] add additional fn to check for Nvidia GPU with CUDA
jono3030 Dec 18, 2024
9ec6190
[feat] improve ACE documentation
Andrew-Clappison Dec 23, 2024
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
81 changes: 45 additions & 36 deletions docs/tutorials/workflows/ace_flow/ace_flow.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,14 +4,13 @@ ACE Workflow
**A**\ I-based **C**\ artography of **E**\ nsembles (**ACE**) pipeline highlights:

1. Cutting-edge vision transformer and CNN-based DL architectures trained on
very large LSFM datasets (`link to sample data <https://huggingface.co/datasets/AICONSlab/MIRACL/blob/dev/sample_data/ace/ace_sample_data_mode_2.zip>`__
and :ref:`refer to example section<example_anchor>`) to map brain-wide local/laminar neuronal activity.
very large LSFM datasets (:ref:`refer to example section<example_anchor>`)
to map brain-wide local/laminar neuronal activity.
2. Optimized cluster-wise statistical analysis with a threshold-free
enhancement approach to chart subpopulation-specific effects at the laminar
and local level, without restricting the analysis to atlas-defined regions
(`link to sample data <https://huggingface.co/datasets/AICONSlab/MIRACL/blob/dev/sample_data/ace/ace_sample_data_stats.zip>`__
and :ref:`refer to example section<example_anchor>`).
3. Modules for providing DL model uncertainty estimates and fine-tuning (in a future release).
(:ref:`refer to example section<example_anchor>`).
3. Modules for providing DL model uncertainty estimates and fine-tuning.
4. Interface with MIRACL registration.
5. Ability to map the connectivity between clusters of activations.

Expand All @@ -22,26 +21,9 @@ To install the ACE workflow, refer to the MIRACL installation guide:

- :doc:`Installation guide <../../../installation/installation>`

Video Tutorial
==============

`Video tutorial <https://www.youtube.com/playlist?list=PLZeAd6YsEkyhWsHuym5dTV2wjQ299ekm8>`_

- This video tutorial covers the following topics:
- MIRACL installation validation
- Download sample data
- Run ACE on a single subject (Mode 2) including deep learning
segmentation of cFos+ cells, registration, voxelization, and warping
- Analyze the results of the above step
- Run ACE cluster-wise statistical algorithm between two groups to map
local cell activation
- Analyze the results of the above step

.. TODO: update the tutorial link

.. note::

Make sure that you set the GPU option during installation using the ``-g`` flag.
Make sure that you set the GPU option during installation.
Once the installation is complete, enter the ``docker`` container using ``docker exec -it <CONTAINER_NAME> bash``
and run the ``nvidia-smi`` command to ensure your GPU is detected.

Expand Down Expand Up @@ -86,6 +68,23 @@ These models will be included by default in a future release once ACE is publish
files to the right location **outside** the docker container will make them
available inside the container.

Video Tutorial
==============

`Video tutorial <https://www.youtube.com/playlist?list=PLZeAd6YsEkyhWsHuym5dTV2wjQ299ekm8>`_

- This video tutorial covers the following topics:
- MIRACL installation validation
- Download sample data
- Run ACE on a single subject (Mode 2) including deep learning
segmentation of cFos+ cells, registration, voxelization, and warping
- Analyze the results of the above step
- Run ACE cluster-wise statistical algorithm between two groups to map
local cell activation
- Analyze the results of the above step

.. TODO: update the tutorial link


Main Inputs
============
Expand Down Expand Up @@ -347,8 +346,11 @@ Main outputs

.. _example_anchor:

Examples
========

Example of running ACE flow on multiple subjects (Mode 1):
==========================================================
----------------------------------------------------------

.. code-block::

Expand All @@ -360,8 +362,8 @@ Example of running ACE flow on multiple subjects (Mode 1):
--sa_resolution 1.4 1.4 5.0


Example of running ACE on single subject (Mode 2) (`link to sample data <https://huggingface.co/datasets/AICONSlab/MIRACL/resolve/dev/sample_data/ace/ace_sample_data_mode_2.zip>`__):
======================================================================================================================================================================================
Example of running ACE on single subject (Mode 2: Segmentation & Registration):
-------------------------------------------------------------------------------

.. note::

Expand All @@ -378,6 +380,8 @@ Example of running ACE on single subject (Mode 2) (`link to sample data <https:/
you want to download. For this tutorial, you will need to
download option ``1``.

Alternatively, download mode 2 sample data `here <https://huggingface.co/datasets/AICONSlab/MIRACL/resolve/dev/sample_data/ace/ace_sample_data_mode_2.zip>`_.

.. code-block::

$ miracl flow ace \
Expand All @@ -402,8 +406,8 @@ Example of running ACE on single subject (Mode 2) (`link to sample data <https:/
The user can also run the ACE segmentation module or the ACE cluster-wise analysis module separately.
Examples of running these modules separately are provided below.

Example of running only ACE segmentation module on one single subject (`link to sample data <https://huggingface.co/datasets/AICONSlab/MIRACL/resolve/dev/sample_data/ace/ace_sample_data_mode_2.zip>`__):
==========================================================================================================================================================================================================
Example of running ACE on one single subject (Mode 2: Segmentation Only):
-------------------------------------------------------------------------

.. note::

Expand All @@ -420,6 +424,8 @@ Example of running only ACE segmentation module on one single subject (`link to
you want to download. For this tutorial, you will need to
download option ``1``.

Alternatively, download mode 2 sample data `here <https://huggingface.co/datasets/AICONSlab/MIRACL/resolve/dev/sample_data/ace/ace_sample_data_mode_2.zip>`_.

.. code-block::

$ miracl seg ace \
Expand All @@ -429,8 +435,8 @@ Example of running only ACE segmentation module on one single subject (`link to
--sa_batch_size 2


Example of running only ACE cluster wise analysis on voxelized and warped segmentation maps (`link to sample data <https://huggingface.co/datasets/AICONSlab/MIRACL/resolve/dev/sample_data/ace/ace_sample_data_stats.zip>`__):
===============================================================================================================================================================================================================================
Example of running only ACE cluster wise analysis on voxelized and warped segmentation maps:
--------------------------------------------------------------------------------------------

.. note::

Expand All @@ -447,13 +453,15 @@ Example of running only ACE cluster wise analysis on voxelized and warped segmen
you want to download. For this tutorial, you will need to
download option ``2``.

.. code-block::
Alternatively, download stats sample data `here <https://huggingface.co/datasets/AICONSlab/MIRACL/resolve/dev/sample_data/ace/ace_sample_data_stats.zip>`_.

$ miracl stats ace \
--control ./ctrl/ \
--treated ./treated/ \
--sa_output_folder ./output_dir \
--rwc_voxel_size 25
.. code-block::

$ miracl stats ace \
--control ./ctrl/ \
--treated ./treated/ \
--sa_output_folder ./output_dir \
--rwc_voxel_size 25

More information on the ``miracl stats ace`` function can be found
:doc:`here <../../stats/ace_cluster/ace_cluster>`.
Expand Down Expand Up @@ -509,3 +517,4 @@ and hyperparameters for the fine-tuning process.

The script will output the fine-tuned model weights in the output directory. The
user can then :ref:`use this model to run the ACE workflow above<model_directory_specification>`.

28 changes: 27 additions & 1 deletion install.sh
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -348,6 +348,30 @@ function parse_args() {
# DOCKER COMPOSE #
##################

#!/bin/bash

function check_gpu() {
# Check if nvidia-smi is available (NVIDIA driver installed)
if ! command -v nvidia-smi &> /dev/null; then
echo "ERROR: nvidia-smi command not found. Make sure the NVIDIA driver and CUDA are installed."
exit 1
fi

# Check if any GPUs are detected by nvidia-smi
gpu_count=$(nvidia-smi --query-gpu=count --format=csv,noheader,nounits)

if [[ "$gpu_count" -gt 0 ]]; then
echo "Found $gpu_count Nvidia GPU(s) on your system."

# Optionally: Check if CUDA is supported
cuda_version=$(nvidia-smi --query-gpu=driver_version --format=csv,noheader,nounits)
echo "CUDA supported with driver version $cuda_version."
else
echo "No Nvidia GPUs found or GPUs are not accessible."
exit 1
fi
}

function populate_docker_compose() {
# Generate docker-compose.yml file
cat >docker-compose.yml <<EOF
Expand All @@ -364,7 +388,9 @@ services:
shm_size: ${shm_mem}
EOF

if [[ $gpu ]]; then
if [[ "${gpu}" == true ]]; then

check_gpu

cat >>docker-compose.yml <<EOF
deploy:
Expand Down