CL-3D

Contrastive learning using 3D context of stacked brain sections.

Quickstart

Install the cl_3d package

Clone the cl-3d repository and install it as editable packge:

git clone https://jugit.fz-juelich.de/inm-1/bda/personal/aoberstrass/projects/cl-3d.git
cd cl-3d
pip install -e .

The installation requires Python 3.10 and the GCC, OpenMPI and LibTIFF packages.

On Ubuntu you can install the packages as:

sudo apt install build-essential libtiff-dev libopenmpi-dev

install them using conda:

conda install gxx_linux-64==9.3.0 anaconda::openmpi conda-forge::pylibtiff

or load the corresponding modules when working on the Jülich Supercomputing facility:

ml Stages/2024
ml load GCC/12.3.0 OpenMPI/4.1.5 LibTIFF/.4.5.0

Training

For local debugging (not on a compute node) start the script as

HYDRA_FULL_ERROR=1 python scripts/train.py debug=step

or submit a job to the development partition on the JSC:

sbatch scripts/dev_jureca.sbatch default

For full-scale training submit the job as

sbatch scripts/train_jureca.sbatch default

In both cases default can be replaced with an experiment configuration under configs/experiment.

Inference

To apply a trained model to unseen sections use python scripts/apply-encoder.py with a path to the checkpoint of a trained model for --ckpt.

Project Organization

├── configs                              <- Hydra configuration files
│   ├── callbacks                               <- Callbacks configs
│   ├── datamodule                              <- Datamodule configs
│   ├── debug                                   <- Debugging configs
│   ├── experiment                              <- Experiment configs
│   ├── hparams_search                          <- Hyperparameter search configs
│   ├── local                                   <- Local configs
│   ├── log_dir                                 <- Logging directory configs
│   ├── logger                                  <- Logger configs
│   ├── model                                   <- Model configs
│   ├── trainer                                 <- Trainer configs
│   │
│   ├── test.yaml                               <- Main config for testing
│   └── train.yaml                              <- Main config for training
│
├── environment                          <- Computing environment
│   ├── requirements                            <- Python packages and JSC modules requirements
│   │
│   ├── activate.sh                             <- Activation script
│   ├── config.sh                               <- Environment configurations
│   ├── create_kernel.sh                        <- Jupyter Kernel script
│   └── setup.sh                                <- Environment setup script
│
├── logs
│   ├── experiments                      <- Logs from experiments
│   ├── slurm                            <- Slurm outputs and errors
│   └── tensorboard/mlruns/...           <- Training monitoring logs
|
├── models                               <- Trained and serialized models, model predictions
|
├── notebooks                            <- Jupyter notebooks
|
├── scripts                              <- Scripts used in project
│   ├── train_juwels.sbatch                     <- Submit job to slurm on JUWELS
│   ├── test.py                                 <- Run testing
│   └── train.py                                <- Run training
│
├── src/cl_3d                            <- Source code
│   ├── datamodules                             <- Lightning datamodules
│   ├── models                                  <- Lightning models
│   ├── utils                                   <- Utility scripts
│   │
│   ├── testing_pipeline.py
│   └── training_pipeline.py
│
├── .coveragerc                          <- Configuration for coverage reports of unit tests.
├── .gitignore                           <- List of files/folders ignored by git
├── .pre-commit-config.yaml              <- Configuration of pre-commit hooks for code formatting
├── setup.cfg                            <- Configuration of linters and pytest
├── LICENSE.txt                          <- License as chosen on the command-line.
├── pyproject.toml                       <- Build configuration. Don't change! Use `pip install -e .`
│                                           to install for development or to build `tox -e build`.
├── setup.cfg                            <- Declarative configuration of your project.
├── setup.py                             <- [DEPRECATED] Use `python setup.py develop` to install for
│                                           development or `python setup.py bdist_wheel` to build.
└── README.md

DataLad

To retrieve the training data run

datalad get datasets/vervet1818-3d-pairs/

or

datalad get --reckless=ephemeral datasets/vervet1818-3d-pairs

if you just want to link to the data on a remote without copying the files. Additional sources of submodules are specified as datalad.get.subdataset-source-candidate in .datalad/config (See the doc).

Please note that access to the data can only be provided on request.

cscratch

To use cscratch on JSC run

ime-ctl -i --block -K data/subdataset/path/*

to make data available from cscratch and

export HDF5_USE_FILE_LOCKING='FALSE'

to disable file locking.

How to Cite

When using this work in your research, please cite it as follows:

@article{oberstrass2024,
  title = {Self-{{Supervised Representation Learning}} for {{Nerve Fiber Distribution Patterns}} in {{3D-PLI}}},
  author = {Oberstrass, Alexander and Muenzing, Sascha E. A. and Niu, Meiqi and {Palomero-Gallagher}, Nicola and Schiffer, Christian and Axer, Markus and Amunts, Katrin and Dickscheid, Timo},
  year = {2024},
  journal = {Imaging Neuroscience},
  issn = {2837-6056},
  doi = {https://doi.org/10.1162/imag_a_00351},
}