.. include:: ../../substitutions.rst

=======
Summary
=======

The ``postprocess.py`` command-line tool can be used to analyze the results generated by ``match_template.py``.

.. code-block:: bash

    postprocess.py --help

.. tab-set::

    .. tab-item:: Orientations

        The following will call 1,000 top-scoring peaks that are separated by at least 20 voxel from each other and 30 voxel from the boundaries. A tab-separated file *output.tsv* will be created in the process containing eight columns. The z, y and x column correspond to the translation, the euler_z, euler_y and euler_x column to the rotation used to obtain the column score. The detail column contains peak caller specific information.

        .. code-block:: bash

            postprocess.py \
                --input_file output.pickle \
                --output_prefix output \
                --output_format orientations \
                --min_distance 30 \
                --min_boundary_distance 20\
                --number_of_peaks 1000

        .. note::

            |project| uses a zyx convention, following the CCP4/MRC format. In `IMOD <https://bio3d.colorado.edu/imod/>`_ terms, a file read by :py:meth:`Density.from_file <tme.density.Density.from_file>` with data shape 500, 928, 960, will contain 960 columns, 928 rows and 500 sections. Similarly, the reported Euler angles are in intrinsic zyx convention (see :py:meth:`euler_to_rotationmatrix <tme.matching_utils.euler_to_rotationmatrix>`).

    .. tab-item:: Alignments

        The code below will call peaks analogously to *Orientations*, but additionally also applies the identified orientation to the template and writes it to disk using the naming pattern {output_prefix}_{index}.{extension}. Index 0 corresponds to the highest scoring orientation.

        .. code-block:: bash

            postprocess.py \
                --input_file output.pickle \
                --output_prefix output \
                --output_format alignment \
                --number_of_peaks 10

    .. tab-item:: Extraction

        The code below will call peaks analogously to *Orientations*, but additionally extract subsets centered around the peak with specified box size. The generated files follow the naming pattern {output_prefix}_{index}.mrc, where index 0 corresponds to the highest observed score.

        .. code-block:: bash

            postprocess.py \
                --input_file output.pickle \
                --output_prefix output \
                --output_format extraction \
                --min_distance 20 \
                --number_of_peaks 500 \
                --peak_caller PeakCallerMaximumFilter

    .. tab-item:: Relion

        This option will generate a `STAR <https://en.wikipedia.org/wiki/Self-defining_Text_Archive_and_Retrieval>`_ file and extract subtomograms which can be directly used input for reconstruction, refinement and downstream classification with `RELION <https://github.com/3dem/relion>`_. In terms of peak calling and subtomogram extraction, this option performs identical to the output_format ``extraction``. The output STAR file consists of an optics group block which contains informations about the imaging conditions, pixel size, and another data group with tab separated columns containing x, y, z coordinates (in voxels), a file path to the generated cropped subtomogram file, the Euler angles, namely rotation, tilt and psi.

        The output is compatible with RELION 4.0 and was tested with relion_reconstruct, and relion_refine_mpi.

        .. code-block:: bash

            postprocess.py \
                --input_file output.pickle \
                --output_prefix output \
                --output_format relion \
                --min_distance 20 \
                --number_of_peaks 1000 \
                -—wedge_mask mask.mrc

        .. note::

            Without a wedge mask or a fully fledged CTF, the averages computed by `RELION <https://github.com/3dem/relion>`_ might be overly distorted due to preferential alignment of subtomograms on the missing wedge (see :doc:`masking <../preprocessing/example>`).

    .. tab-item:: Average

        The code below will call peaks analogously to *Orientations*, and compute a simple average based on the identified orientations.

        .. code-block:: bash

            postprocess.py \
                --input_file output.pickle \
                --output_prefix average \
                --output_format average \
                --min_distance 20 \
                --number_of_peaks 500 \
                --peak_caller PeakCallerMaximumFilter