.. _`app:chimeraRigidFit`:

ChimeraX Rigid Fit protocol
===========================

Protocol designed to manually fit atomic structures to electron density
maps in *Scipion* by using *ChimeraX*. If *map* and *model* are quite close, e.g. after
running *PHENIX dock in map* protocol, automatic fitting is also possible.
Fitted atomic structures generated by using this protocol can be saved
in *Scipion* after executing specific *ChimeraX* commands.

-  | Requirements to run this protocol and visualize results:

   -  | *Scipion* plugin: **scipion-em**

   -  | *Scipion* plugin: **scipion-em-chimera**

-  | *Scipion* menu:
   | *Model building -> Rigid fitting* (:numref:`model_building_app_protocol_chimera_1` (A))

   .. figure:: Images_appendix/Fig116.svg
      :alt: Protocol **chimerax-rigid fit**. A: Protocol location in *Scipion* menu. B: Protocol form.
      :name: model_building_app_protocol_chimera_1
      :align: center
      :width: 90.0%

      Protocol **chimerax-rigid fit**. A: Protocol location in *Scipion* menu. B: Protocol form.

-  | Protocol form parameters (:numref:`model_building_app_protocol_chimera_1` (B)):

   -  | *Input* section

      -  | *Input Volume*: Mandatory param to load the electron density *map* previously downloaded or generated in *Scipion* to fit the atomic structure.

      -  | *Input additional Volumes*: :math:`Idem`. If additional maps, others than the previous *map*, are needed.

      -  | *Atomic structure to be fitted*: Mandatory param to load the atomic structure previously downloaded or generated in *Scipion* to be fitted to an electron density map.

      -  | *Other reference atomic structures*: Atomic structures others than the previous *model* used to help in the rigid body fitting process.

   -  | *Help* section

      | This section contains *ChimeraX* commands required to save *models* according to their reference volumes, which can also be saved if required. Remark that using *scipionwrite* command, *ChimeraX* session will be saved by default, without prejudice that it may be saved with *scipionss* command. *ChimeraX* sessions can be restored by using **chimerax-restore session** protocol. In addition, *scipioncombine* allows to combine several atomic structures in a unique *model*.

-  | Protocol execution:

   | Adding specific map/structure label is recommended in *Run name*
     section, at the form top. To add the label, open the protocol form,
     press the pencil symbol at the right side of *Run name* box,
     complete the label in the new opened window, press OK and, finally,
     close the protocol. This label will be shown in the output summary
     content (see below). If you want to run again this protocol, do not
     forget to set to *Restart* the *Run mode*.

   | Press the *Execute* red button at the form bottom.

   | *ChimeraX* graphics window will be opened after executing the protocol. The
     electron density map and the atomic structure are shown. Main steps
     to complete the rigid body fitting are:

   -  | If density map and atomic structure are quite close to each
        other:

      | Go to *ChimeraX* main menu and select *Tools -> Volume Data-> Fit in Map*.
        A small *Fit in Map* window will be opened. Once the right
        atomic structure and the electron density volume have been
        selected, fit them by clicking *Fit*.
      | ``Note:`` The same result can be obtained by typing in the command
        line *fit #n1 inMap #n2*, with *#n1* and *#n2* model numbers of
        *model* and *map*.

   -  If *model* and *map* are far from each other, start the fitting
      process interactively activating and inactivating *ChimeraX* objects
      alternatively to finally get *map* and *model* close enough to go
      to the previous step. Otherwise, consider the possibility of
      running the protocol **chimerax-rigid fit** after *PHENIX dock in map* protocol.

   -  | To combine two or more atomic structures, write in *ChimeraX* command line:

        ::

             scipioncombine #n1,n2

      | *#n1* and *#n2* are the respective *model* numbers of two
        different atomic structures. Optionally you can set the
        *model* number of the output combined structure *#n3*:

        ::

             scipioncombine #n1,n2 modelid n3

   -  | Save fitted *model* by writing in *ChimeraX* command
        line:

        ::

             scipionwrite #n prefix userString_

      | Replace *#n* by model numbers shown in *ChimeraX Models* panel. *prefix*
        + string preferred by the user to easily identify the atomic
        structure is optional, although quite recomendable.

   -  | Close *ChimeraX* graphics window.

-  | Visualization of protocol results:

   | After executing the protocol, press *Analyze Results* and *ChimeraX* graphics window will be opened by default. Atomic structures and volumes are referred to the origin of coordinates in *ChimeraX*. To show the relative position of *model* and *map*, the three coordinate axes are represented; X axis (red), Y axis (yellow), and Z axis (blue) (:numref:`model_building_app_protocol_volume_3`). Coordinate axes, map, and atomic structure are model numbers *#1*, *#2*, and *#3*, respectively, in *ChimeraX Models* panel in the most simple case.

-  | Summary content:

   -  | If only the atomic structure has been saved by *scipionwrite* command:

      -  | Protocol output (below *Scipion* framework):
         | *chimerax - operate -> output atomic structure name, starting
           with the prefix*;
         | *AtomStruct (pseudoatoms=True/ False, volume=True/ False)*.
         | Pseudoatoms is set to *True* when the structure is made of
           pseudoatoms instead of atoms. Volume is set to *True* when an
           electron density map is associated to the atomic structure.

      -  | *SUMMARY* box:
         | Produced files:
         | output atomic structure name, starting with the prefix (.cif
           file)
         | we have some result

   -  | If both the atomic structure and its reference electron density map have been saved by *scipionwrite* command:

      -  | Protocol output (below *Scipion* framework):
         | *chimerax - rigid fit -> Map_name*; *Volume (x, y, and z
           dimensions, sampling rate)*.
         | *chimerax - rigid fit -> Atom_struct_name*;
         | *AtomStruct (pseudoatoms=True/ False, volume=True/ False)*.
         | Pseudoatoms is set to *True* when the structure is made of
           pseudoatoms instead of atoms. Volume is set to *True* when an
           electron density map is associated to the atomic structure.

      -  | *SUMMARY* box:
         | Produced files:
         | Map_name file, starting with the prefix (.mrc)
         | we have some result