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.

Important

If you use Leopard-EM in your research, please include these linked references: Citation (bottom of this page).

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 = 8

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.

Citation

If you use Leopard-EM in your research, please include the following citations in your biblography:

• Leopard-EM Manuscript

@article{Giammar:rr5256,
  author = "Giammar, Matthew D. and Dickerson, Joshua L. and Hall, Laina N. and Lucas, Bronwyn A.",
  title = "{{\it Leopard-EM}: an extensible 2D template-matching package to accelerate {\it in situ} structural biology}",
  journal = "Acta Crystallographica Section D",
  year = "2026",
  volume = "82",
  number = "1",
  pages = "30--42",
  month = "Jan",
  doi = {10.1107/S2059798325009982},
  url = {https://doi.org/10.1107/S2059798325009982},
}