#############################
Import/export tomography data
#############################

1 Import tomography data in star format
=======================================


.. attention::
    Importing data from Relion to ``pyp`` requires enabling **FlipYZ** and **FlipZ** when running Relion Import Tomograms job. If not, particle coordinates won't be converted correctly. 

Requirements
------------

- Absolute path to star file from 3D refinement jobs (``*_data.star``)
- Absolute path to star file from Import Tomograms job (``ImportTomo/{job_id}/tomograms.star``)
- Absolute path to Relion project folder
- Tilt-series files in correct relative path as indicated in the tomogram star file
- Corresponding tilt-series parameter files (``*.xf``, ``*.tlt`` and ``*.com``) in the same folder with tilt-series files

.. note::
    * ``*.xf, *.tlt`` are alignment parameters, which are required for each tilt-series.
    * ``*.com`` is optional. If they are not present, we would assume **NO** x or z shift applied to the tomograms. This might affect the outcome of particle coordinate conversion.


Procedure
---------

To import tomography data from Relion:

.. code-block:: bash

    # creat an empty folder for importing
    mkdir demo_import

    cd demo_import

    # run import
    rlp -import_refine_star "/path/to/run_it000_data.star"  \
        -import_tomo_star "/path/to/tomograms.star"         \
        -import_relion_path "/path/to/relion/project"       \
        -import_read_star                                   \
        -scope_pixel 1.35                                   \
        -scope_voltage 300                                  \
        -data_path "/path/to/tiltseries/folder/*.mrc"       \
        -data_mode tomo


Running the command above will generate particle alignment parameter file (``pyp_update_volumes.txt``) and metadata (``meta/*.pkl``).
We suggest you to run an iteration of ``csp`` to make sure they are correctly converted.

.. code-block:: bash

    csp -refine_parfile="$(pwd)/pyp_update_volumes.txt"     \
        -refine_model="/path/to/relion/map"                 \
        -particle_mw 200                                    \
        -particle_rad 150                                   \
        -extract_box 256                                    \
        -extract_bin 1                                      \
        -refine_skip                                        \
        -refine_iter 2                                      \
        -refine_maxiter 2


2 Export tomography data in star format
=======================================

Requirements
------------

- A parfile generated by running csp (``frealign/maps/export_demo_r01_02.par.bz2``)
- Metadata generated by running tomo preprocessing (``meta/*.pkl``)

Procedure
---------

To export data from ``pyp`` to Relion:

.. code-block:: bash

    # go to pyp project directory
    cd demo_export

    # simply run export relion command
    csp -export_enable                              \
        -export_parfile "path_to_your_parfile"      \
        -export_location "path_to_export_location"

After completing the procedure above, tomogram star file (``demo_export_tomograms.star``) and refinement star file (``demo_export_particles.star``) will be produced in the ``relion`` folder.
It's ready to run Relion from `Import Coordinates <https://relion.readthedocs.io/en/release-4.0/STA_tutorial/ImportCoords.html>`_ using the star files we just generated.