First Steps
======================

.. _firststeps:
    :title: First Steps

CryoLike computes the likelihood of given cryo-EM images ("Images")
having been generated by a specific 3D map or model. It does this
by taking projections of that model ("Templates") for known poses,
and comparting them to the images.

Typical CryoLike usage requires four steps:

- Set CryoLike parameters
- Create known-pose templates from input model files (in
  ``mrc``, ``mrcs``, ``maps``, or ``pdb`` format)
- Create images from cryo-EM particle files (in
  ``CryoSparc`` or ``Starfile`` format)
- Run the likelihood computation using the Templates and Images

CryoLike provides functions for each of these four tasks. The full
range of options will be discussed in detail in
the :doc:`tutorials section </tutorials/tutorials>`.

This page walks you through a few scripts that demonstrate
basic usage. Successfully running the example scripts also
confirms that the CryoLike library has been installed correctly.

The scripts can be found
in the ``example`` directory of the CryoLike repository. They
operate on a small dataset that is distributed
with this repository in the ``example/data`` directory.


Example Usage
----------------

To try your first CryoLike processing, run the following scripts
in order. Before running, ``cd`` into the ``example`` directory.
If you installed CryoLike in a virtual environment, be sure to
activate it before running the examples. In the command lines
below, we assume your
environment's python interpreter is invoked through the
``python3`` command; this may vary slightly on your system.

- The :doc:`first script</examples/set_image_parameters>`
  creates an image-parameters file and stores it
  in ``example/output/templates/parameters.npz``.

  The image parameters file stores
  information about the image dimensions and discretization grid
  used to represent both template and image files. For a
  comparison to be well-founded, template and image data need to
  have compatible dimensions and discretizations.

  To create the parameter file, run:

  .. code-block:: console

   (venv) $ python3 set_image_parameters_example.py

- The :doc:`second script</examples/make_templates>`
  reads the PDB files distributed with the repository
  in ``example/data/pdb``, converts them into Templates, and saves
  them in a user-defined output directory (which we have specified as
  ``example/output/templates/`` for this example).

  To create the templates, run:

  .. code-block:: console

   (venv) $ python3 make_templates_from_inputs_example.py

- The :doc:`third script</examples/convert_particle_stacks>`
  reads particle stacks from ``particles.mrcs``
  and ``particle_data.star`` (distributed in ``example/data/particles/``),
  converts them into CryoLike-format Image stacks, and saves them
  in a user-defined output directory (``example/output/particles/``).

  To convert the images, run:

  .. code-block:: console

   (venv) $ python3 convert_particle_stacks_example.py

- The :doc:`final script</examples/run_likelihood>` compares
  the image stacks and templates, and computes
  the likelihoods in the ``example/output/likelihood`` directory tree:

.. code-block:: console

   (venv) $ python3 run_likelihood_example.py

If the examples run successfully, you can find all output files under
the ``example/output`` directory.

Our example also includes a script to plot results. To create the plot,
run the following command:

.. code-block:: console

   (venv) $ python3 plot_example.py

Output plots will also be located under the ``output/likelihood`` directory.


Data Sources
---------------

.. _data_sources:

Data used in the examples and test cases are retrieved
from the following sources:

- EMPIAR-10026
- EMD: 2788
- PDB ID: 1UAO
- PDB ID: 4V1W

Detailed Tutorials
---------------------

For example usages in different scenarios, see the
:doc:`tutorials section </tutorials/tutorials>`.