Updated docs

Author: maurerv

doc/quickstart/postprocessing/summary.rst

@@ -4,7 +4,7 @@
 Summary
 =======
 
-The ``postprocess.py`` tool analyzes results generated by ``match_template.py`` to identify and characterize top-scoring peaks from template matching.
+The ``postprocess.py`` tool processes the output of  ``match_template.py`` to identify the highest-scoring orientations (peaks). Depending on the downstream use case, different ``output-format`` options are available and outlined below.
 
 .. code-block:: bash
 
@@ -14,76 +14,74 @@ The ``postprocess.py`` tool analyzes results generated by ``match_template.py``
 
     From version 0.3.0 onwards, postprocessing supports advanced multi-input and background correction. Multiple input files can be specified to distinguish between different macromolecular species, with corresponding class identifiers made available in orientations and RELION output formats. Additionally, multiple background corrections can be applied simultaneously via ``--background-file``, enabling users to account for various noise sources beyond single backgrounds (e.g., from ``--scramble-phases``) and incorporate complex cellular environments such as membrane backgrounds.
 
-Depending on the subequent use case, different ``output-format`` options are available and outlined below.
-
 .. tab-set::
 
     .. tab-item:: Orientations
 
-        A tab-separated file *output.tsv* will be created in the process containing eight columns. The x, y and z column correspond to the translation, the euler_x, euler_y and euler_z column to the rotation used to obtain the column score. The detail column contains peak caller specific information.
+        Create a tab-separated file containing x, y, z translations, euler_x, euler_y and euler_z Euler angles in counter-clockwise zyz format, corresponding score and peak caller details.
 
         .. code-block:: bash
 
             postprocess.py \
                 --input-file output.pickle \
-                --output-prefix output \
                 --output-format orientations \
                 --mask-edges \
                 --min-boundary-distance 20 \
                 --num-peaks 1000
 
     .. tab-item:: Relion 4 / 5
 
-        These options generate `STAR <https://en.wikipedia.org/wiki/Self-defining_Text_Archive_and_Retrieval>`_ files compatible with `RELION <https://github.com/3dem/relion>`_ 4 and 5. Both formats contain particle coordinates, Euler angles, scores, and source file references in a format that RELION can directly import. The coordinates and angles are identical to output_format ``orientations``. The created files differ in version headers and in the coordinate system. Relion 4 uses voxel coordinates, Relion 5 centers coordinates and scales them by the voxel size.
+        Create a `STAR <https://en.wikipedia.org/wiki/Self-defining_Text_Archive_and_Retrieval>`_ file compatible with `RELION <https://github.com/3dem/relion>`_ 4 and 5. Relion 4 uses voxel coordinates, Relion 5 centers coordinates and scales them by the voxel size. The version difference is reflected in the header.
 
         .. code-block:: bash
 
             postprocess.py \
                 --input-file output.pickle \
-                --output-prefix output \
                 --output-format relion4 \
                 --mask-edges \
                 --min-boundary-distance 20 \
+                --clockwise-angles \
                 --num-peaks 1000
 
+        .. note::
+
+            RELION expects ``--clockwise-angles``, which need to be multiplied with negative one to be compatible with our format again.
+
 
     .. 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.
+        Transform template into identified orientations and write the output to disk as ``{output_prefix}_{index}.{extension}``. Index 0 corresponds to the top-scoring peak. This format is useful for assessing the result of fitting templates to maps.
 
         .. code-block:: bash
 
             postprocess.py \
                 --input-file output.pickle \
-                --output-prefix output \
                 --output-format alignment \
                 --mask-edges \
                 --min-boundary_distance 20 \
                 --num-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.
+        Extract subvolumes around identified peaks and write the output to disk as ``{output_prefix}_{index}.{extension}``. Index 0 corresponds to the top-scoring peak. This format is useful for assessing the result of particle picking.
 
         .. code-block:: bash
 
             postprocess.py \
                 --input-file output.pickle \
-                --output-prefix output \
                 --output-format extraction \
                 --mask-edges \
                 --min-boundary-distance 20 \
                 --num-peaks 100
 
     .. tab-item:: Average
 
-        The code below will call peaks analogously to *Orientations*, and compute a simple average based on the identified orientations.
+        Compute an average of subvolumes based on identified peaks.
 
         .. code-block:: bash
 
             postprocess.py \
                 --input-file output.pickle \
-                --output-prefix average \
                 --output-format average \
                 --mask-edges \
                 --min-boundary-distance 20 \
@@ -92,19 +90,19 @@ Depending on the subequent use case, different ``output-format`` options are ava
 
     .. tab-item:: Pickle
 
-        The code below will apply background correction, and create a new pickle file containing the corrected scores. The output is intended for visual assessment of the normalization procedure, and can be reused for postprocessing.
+        Create a new pickle file incorporating input files and backgrounds. The output can be used for visual assessment of the normalization procedure and be reused for ``postprocess.py``. The created pickle file can not be used to distinguish between different entities presented by different input files.
 
         .. code-block:: bash
 
             postprocess.py \
                 --input-file output.pickle \
-                --output-prefix output_new \
+                --output-prefix output_norm \
                 --output-format pickle \
                 --background-file background1.pickle background2.pickle
 
 .. note::
 
-    Orientations are following the conventions outlined in [1]_. We use a right-handed coordinate system with orthogonal X, Y and Z axes. Euler angles are expressed using intrinsic ZYZ convention, with the first rotation around the Z-axis, the second around the new Y-axis and the third around the new Z-axis (see :py:meth:`euler_to_rotationmatrix <tme.rotations.euler_to_rotationmatrix>`). The default orientation is the z-unit vector (0, 0, 1).
+    Orientations are following the conventions outlined in [1]_. We use a right-handed coordinate system with orthogonal X, Y and Z axes. Euler angles are expressed counter-clockwise using intrinsic ZYZ convention, with the first rotation around the Z-axis, the second around the new Y-axis and the third around the new Z-axis (see :py:meth:`euler_to_rotationmatrix <tme.rotations.euler_to_rotationmatrix>`). The default orientation is the z-unit vector (0, 0, 1).
 
 
 References