Skip to main content

PyTOM's GPU template matching module as an independent package

Project description

test-badge

GPU template matching for cryo-ET

GPU template matching, originally developed in PyTom, as a standalone python package that can be run from the command line.

Requires

miniconda3
nvidia-cuda-toolkit

Installation

There are 2 options for creating a conda environment. We recommend option (1) which will later allow cupy to build against a system installed cuda-toolkit. Compared to option (2) this can give an almost two-fold speedup:

  1. (recommended) Create a new python 3 environment:

    conda create -n pytom_tm python=3
    
  2. Create a new environment with a prebuild cupy version and complete CUDA-toolkit. This is more reliable, but takes more disk space and has less optimal performance.

    conda create -n pytom_tm -c conda-forge python=3 cupy cuda-version=11.8
    

Once the environment is created, activate it:

conda activate pytom_tm

Then clone the repository and install it with pip (building cupy can take a while!):

git clone https://github.com/SBC-Utrecht/pytom-match-pick.git
cd pytom-match-pick
python -m pip install '.[plotting]'

The installation above also adds the optional dependencies [matplotlib, seaborn] which are required to run pytom_estimate_roc.py. They are not essential to the core template matching functionality, so for some systems (such as certain cluster environments) it might be desirable to skip them. In that case remove [plotting] from the pip install command:

python -m pip install .

Tests

To run the unittests:

cd tests
python -m unittest discover

If cupy is not correctly installed, this should raise some errors:

python -c "import cupy as cp; a = cp.zeros((100,100))"

To solve cupy installation issues, please check the cupy docs. It might be solved by installing a specific build compatible with the installed cuda toolkit.

Usage

Detailed usage instructions are available on the wiki: https://github.com/SBC-Utrecht/pytom-match-pick/wiki

Also, a tutorial can be found on the same wiki: https://github.com/SBC-Utrecht/pytom-match-pick/wiki/Tutorial

The following scripts are available to run with --help to see parameters:

  • create a template from an mrc file containing a density map: pytom_create_template.py --help
  • create a mask for template matching: pytom_create_mask.py --help
  • run template matching with the mask (.mrc) and template (.mrc) on a tomogram (.mrc): pytom_match_template.py --help
  • extract candidates from a job file (.json) created in the template matching output folder: pytom_extract_candidate.py --help
  • estimate an ROC curve from a job file (.json): pytom_estimate_roc.py --help
  • merge multiple star files to a single starfile: pytom_merge_stars.py --help

Contributing

Contributions to the project are very welcome! Feel free to make a pull request or suggest an implementation in the issues. For PR's we will gladly give you feedback on how to integrate the code.

Citation

For a reference on GPU accelerated template matching in tomograms please see the IJMS publication.

@Article{ijms241713375,
    AUTHOR = {Chaillet, Marten L. and van der Schot, Gijs and Gubins, Ilja and Roet, Sander and Veltkamp, Remco C. and Förster, Friedrich},
    TITLE = {Extensive Angular Sampling Enables the Sensitive Localization of Macromolecules in Electron Tomograms},
    JOURNAL = {International Journal of Molecular Sciences},
    VOLUME = {24},
    YEAR = {2023},
    NUMBER = {17},
    ARTICLE-NUMBER = {13375},
    URL = {https://www.mdpi.com/1422-0067/24/17/13375},
    ISSN = {1422-0067},
    DOI = {10.3390/ijms241713375}
}

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pytom-match-pick-0.4.3.tar.gz (2.3 MB view hashes)

Uploaded Source

Built Distribution

pytom_match_pick-0.4.3-py3-none-any.whl (2.3 MB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page