Leopard-EM: Python based template matching

Leopard-EM (Location & oriEntatiOn of PARticles found using two-Dimensional tEmplate Matching) is a python package for running two-dimensional template matching (2DTM) on cryo-EM images. Check out the online documentation for more details about using, configuring, and analyzing data from the Leopard-EM Python package.

Basic Installation

The newest released version of the package can be installed from PyPI using pip:

pip install leopard-em

Usage

Template Matching

Inputs to the template matching programs can be configured through a YAML file or a set of Python objects. The example YAML configuration file acts as a template for configuring your own runs with more details on configuring and running 2DTM on the programs section of the documentation. We also provide a default match_template.py script with some additional detail, but a compacted version of this script is shown below. Once configured with the proper paths, parameters, etc., the program can run as follows:

from leopard_em.pydantic_models.managers import MatchTemplateManager

YAML_CONFIG_PATH = "/path/to/match-template-configuration.yaml"
DATAFRAME_OUTPUT_PATH = "/path/to/match-template-results.csv"
ORIENTATION_BATCH_SIZE = 32

def main():
    mt_manager = MatchTemplateManager.from_yaml(YAML_CONFIG_PATH)
    mt_manager.run_match_template(ORIENTATION_BATCH_SIZE)
    df = mt_manager.results_to_dataframe()
    df.to_csv("/path/to/results.csv")

# NOTE: invoking from `if __name__ == "__main__"` is necessary
# for proper multiprocessing/GPU-distribution behavior
if __name__ == "__main__":
    main()

Template Refinement

Particle orientations and locations can be refined using the RefineTemplateManager objects after a template matching run. The RefineTemplateManager is similarly a set of Pydantic models capable of configuration via YAML files. The example YAML configuration file acts as a template for configuring your own runs. We also provide a default refine_template.py script with some additional detail, but a compacted version of this script is shown below. Once configured with the proper paths, parameters, etc., the program can run as follows:

from leopard_em.pydantic_models.managers import RefineTemplateManager

YAML_CONFIG_PATH = "/path/to/refine-template-configuration.yaml"
DATAFRAME_OUTPUT_PATH = "/path/to/refine-template-results.csv"
PARTICLE_BATCH_SIZE = 80

def main():
    rt_manager = RefineTemplateManager.from_yaml(YAML_CONFIG_PATH)
    rt_manager.run_refine_template(DATAFRAME_OUTPUT_PATH, PARTICLE_BATCH_SIZE)

if __name__ == "__main__":
    main()

Installation for Development

The package can be installed from source in editable mode with the optional development libraries via pip.

git clone https://github.com/Lucaslab-Berkeley/Leopard-EM.git
cd Leopard-EM
pip install -e '.[dev,test, docs]'

Further information on development and contributing to the repo can be found in our online documentation.