-
Ensure Git and Anaconda (or Miniconda) are installed on your machine.
-
If you wish to run the Segment Anything model on GPU, ensure CUDA is installed on your machine. CUDA is not necessary if you wish to only run Segment Anything on your machine's CPU.
-
Clone this repository:
git clone https://github.com/r-karimi/vesicle-picker.git
-
Enter this repository:
cd vesicle-picker
-
Create a clean conda virtual environment.
conda create -n vesicle-picker conda activate vesicle-picker conda install pip
-
Edit the
pyproject.toml
file in the base directory to install the correction version of PyTorch, PyTorch vision, and PyTorch audio for your machine. These instructions differ based on whether you are installing PyTorch for CPU or GPU usage.-
Visit the PyTorch installation page and select the appropriate options, ensuring that Pip is selected as the package manager and CPU is selected as the compute platform. Note the given install command, but do not run it.
-
Modify
install-pytorch
inpyproject.toml
with the install command noted above:# Example: CPU install-pytorch = "pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu"
-
Note your version of CUDA and Python by running:
nvcc --version python --version
-
Browse the PyTorch wheels to find the appropriate versions of PyTorch, PyTorch vision, and PyTorch audio for your installed versions of CUDA and Python (e.g.
cu118
for CUDA 11.8 andcp39
for Python 3.9). -
Modify the
install-pytorch
command inpyproject.toml
to match these versions:# Example: Python 3.9.X and CUDA 11.8 install-pytorch = "pip install torch==2.1.1+cu118 torchvision==0.16.1+cu118 torchaudio==2.1.1+cu118 -f https://download.pytorch.org/whl/torch_stable.html"
-
-
Install
vesicle-picker
and dependencies:pip install . poe install-pytorch
-
Download the Segment Anything model weights and place them in the
vesicle-picker
repository. We recommend trying with the ViT-L model weights first. -
Modify csparc_login.ini to match your active CryoSPARC instance from which micrographs will be imported into Vesicle Picker and into which particle locations will be exported.
Before processing your own dataset, we recommend working through the introductory Jupyter notebook find_vesicles.ipynb
. This notebook describes how the program imports data residing in CryoSPARC and describes each step of the processing pipeline.
To process your own dataset, follow the steps below:
-
Import your movies, then perform patch motion correction and patch CTF estimation.
-
Curate your motion corrected micrographs.
-
Note the project ID, workspace ID, and job ID of your Curate Exposures job.
-
Find the optimal mask pre-processing and postprocessing parameters for your data by importing a test micrograph using the
find_vesicles.ipynb
Jupyter notebook. We note in our paper that a combination of roundness and area postprocessing filters are sufficient to obtain high precision and recall in the task of finding synaptic vesicles. If these are sufficient for your dataset as well, then the parameters that need to be set by the user are as follows.-
$\sigma_{space}$ ,$\sigma_{colour}$ , and$d$ for the bilateral filter. -
$roundness_{min}$ for the roundness filter. -
$area_{min}$ and$area_{max}$ for the area filter. -
$r_{dilation}$ or$r_{erosion}$ for particle picks offset from the membrane edge. - Box size to control the density of the picks.
There are a variety of other postprocessing filters that can be applied to your data as well. These filters are commented out in
parameters/filter_vesicles.ini
by default. More information about the various postprocessing methods implemented in this library can be found invesicle_picker/postprocessing.py
. -
-
Find vesicles by modifying the
find_vesicles.ini
parameter file with your desired parameters, ensuring to fill in the correct CryoSPARC information. Also make sure to fill in your CryoSPARC login information, usingcsparc_login.ini
as a template. Finally, indicate an appropriate output directory for the detected vesicles. These will be stored in Python.pkl
files. We have pre-filled this parameter file with a reasonable set of starting parameters.When you're ready, run the
find_vesicles.py
script. The script takes a file path to the parameters file as its only argument:python find_vesicles.py parameters/find_vesicles.ini
-
Filter the found vesicles by modifying the
filter_vesicles.ini
parameter file, uncommenting the types of filters that you want to use and setting their minimum and maximum values. Ensure to set the input directory for this script as the output directory offind_vesicles.py
. Again, we have pre-filled this parameter file with a reasonable set of starting parameters.When you're ready, run
filter_vesicles.py
:python filter_vesicles.py parameters/filter_vesicles.ini
-
Generate particle picks by modifying the
generate_picks.ini
parameter file. Set the workspace into which the vesicle picks will be exported. Set the dilation or erosion radius if desired, and set box size parameter to control the density of picks. We recommend picking with a high density and removing duplicate particles later in CryoSPARC. Ensure to set the input directory for this script as the output directory offilter_vesicles.py
.Run
generate_picks.py
:python generate_picks.py parameters/generate_picks.ini
Once this script has finished executing, you should see a collection of
.pkl
files in the output directory of this script, as well as a new, completed job in CryoSPARC called Vesicle Picks. This job will be used for downstream processing in CryoSPARC.
-
Extract particles from the micrographs that were used as input to
find_vesicles.py
. We recommend extracting with a box size 2x to 3x larger than the box size used to generate picks. -
Proceed with downstream analysis in CryoSPARC, such as 2D classification and Ab initio reconstruction.
-
We recommend experimenting with different model architectures and downsampling factors to find a good trade-off between accuracy and speed when processing a full dataset. We have found that perfect recall when finding vesicles is usually unnecessary for obtaining a structure. A small set of high-quality vesicles are usually more informative than vesicles mixed in with junk, so don't be afraid of stringently filtering your vesicles.
-
If you're able to generate good 2D classes of a membrane protein complex with Vesicle Picker, these particles can be used for template matching and training a Topaz model to obtain a larger and more well-centered particle stack for subsequent 3D reconstruction and refinement.
-
When performing 2D classification, particularly when searching for small membrane proteins and protein complexes, we found that it is important to perform at least 40 iterations of expectation-maximization. We also typically increase the batchsize per class to 150 or 200. Finally, we almost always see better results when we disable the
Recenter 2D classes
parameter. -
We typically iterate 2D classification and selection of promising 2D classes several times. In early iterations, we enable the
Force Max over poses/shifts
parameter to efficiently classify large numbers of particles. In later iterations, where images of proteins in membranes are enriched, we typical disable theForce Max over poses/shifts
parameter to better resolve low SNR particles within membranes.
Karimi, R., Coupland, C. E. & Rubinstein, J. L. Vesicle Picker: A tool for efficient identification of membrane protein complexes in vesicles. bioRxiv 2024.07.15.603622 (2024) doi:10.1101/2024.07.15.603622.