leopard-em 0.0.3a0

Location & Orientation of Particles using Two-Dimensional Template Matching

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.

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 with Pydantic models (see online documentation for examples and use cases). Alternatively, configurations can be set in YAML files and loaded into the MatchTemplateManager object. The example YAML configuration file acts as a template for configuring your own runs. Once configured with the proper paths, parameters, etc., the program can run as follows:

from leopard_em.pydantic_models import MatchTemplateManager

YAML_CONFIG_PATH = "path/to/mt_config.yaml"
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. Once configured with the proper paths, parameters, etc., the program can run as follows:

from leopard_em.pydantic_models import RefineTemplateManager

YAML_PATH = "/path/to/rt_config.yaml"
ORIENTATION_BATCH_SIZE = 80

def main():
    rt_manager = RefineTemplateManager.from_yaml(YAML_PATH)
    rt_manager.run_refine_template(
        output_dataframe_path="/path/to/refined_results.csv",
        orientation_batch_size=ORIENTATION_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.