This repository contains all code for the sequential ML pipeline of the paper Genetically encoded barcodes for correlative volume electron microscopy.
Pretrained models can be found as release artifacts here. They are automatically downloaded and cached when needed by the code.
You can install the project with scripts and all dependencies by running
pip install emcaps
Notes:
-
It is recommended to use a new virtual environment for this.
-
If you encounter PyTorch issues with this setup, please install PyTorch manually following the official instructions
-
If you want to use the napari-based GUI, you will also need to install one of qtpy's supported Qt backends, for example PyQt5:
pip install pyqt5
This has to be done manually since none of the backends is compatible with all platforms and pip can't auto-select an optimal one.
First obtain the project sources (either clone or download zip and extract) and cd
to the project root.
If you want to install all dependencies and the package itself with pip
, just run
pip install .
Alternatively, if you want to install the dependencies with conda
, run the following commands:
conda env create -f environment.yml
conda activate emcaps
pip install .
All scripts can be executed from the project root directory using python3 -m
, for example:
$ python3 -m emcaps.inference.segment -h
Alternatively you can use the entry points provided by the pip installation:
$ emcaps-segment -h
These entry points just require raw images and don't require GPU resources. Labels are not needed.
$ emcaps-encari
or
$ python3 -m emcaps.analysis.encari
$ emcaps-segment segment.inp_path=<PATH_TO_FILE_OR_FOLDER>
or
$ python3 -m emcaps.inference.segment segment.inp_path=<PATH_TO_FILE_OR_FOLDER>
The following steps require a local copy of the official dataset or a dataset in the same structure. A GPU is highly recommended.
$ emcaps-splitdataset
or
$ python3 -m emcaps.utils.splitdataset
$ emcaps-segtrain
or
$ python3 -m emcaps.training.segtrain
Segment and optionally also perform particle-level classification if a model is available, render output visualizations (colored classification overlays etc.) and compute segmentation metrics.
$ emcaps-segment
or
$ python3 -m emcaps.inference.segment
For a usage example featuring config sweeps, see _scripts/seg_cls_test.sh
Based on segmentation (from a model or human annotation), extract particle-centered image patches and store them as separate files in addition to metadata. The resulting patch dataset can be used for training models for patch-based classification. In addition, A random sample of the validation patches is prepared for evaluation of human and model-based classification evaluation.
$ emcaps-patchifyseg
or
$ python3 -m emcaps.inference.patchifyseg
Requires the outputs of patchifyseg
(see above).
$ emcaps-patchtrain
or
$ python3 -m emcaps.training.patchtrain
Requires the outputs of patchifyseg
(see above).
$ emcaps-patcheval
or
$ python3 -m emcaps.inference.patcheval
For a usage example featuring config sweeps, see _scripts/patcheval.sh
Requires the outputs of patchifyseg
(see above).
$ emcaps-averagepatches
or
$ python3 -m emcaps.analysis.averagepatches
We are using a common configuration system for the runnable code, based on Hydra and OmegaConf.
A central default config file with explanatory comments is located at conf/conf.yaml
.
It is written to be as automatic and minimal as possible, but it can still be necessary to change some of the values for experiments or adapting to a different system.
For the syntax of such yaml-based config files please refer to the OmegaConf docs on access and manipulation and variable interpolation
For running hydra-enabled code with custom configuration you can either point to a different config file with the -cp
CLI flag or change config values directly on the CLI using Hydra's override syntax
If you want to train own models and/or do quantitative evaluation on the official data, please find the data here and extract it to ~/emc/emcapsulin
.
For more details see top-level docstrings in each file.