Structural analysis of low occupancy states

Xtrapol8

Xtrapol8 is software for the calculation of Fourier difference maps, extrapolated structure factor ampltiudes (ESFAs) and estimation of the occupancy of at triggered state that occupies the crystal at low occupancy. It is based on the cctbx toolbox and uses some CCP4 programs. In order to run Xtrapol8, you will need to have a proper licence for Phenix and CCP4 and have both software suites installed. Please use Phenix 1.19 or higher.

An introduction into Fourier difference maps, structure factor extrapolation and the software itself can be found on the youtube channel of CCP4

If Xtrapol8 was useful in your project, please cite us: De Zitter, E., Coquelle, N., Oeser, P., Barends, T. R. M., Colletier, J.-P., Xtrapol8 enables automatic elucidation of low-occupancy intermediate-states in crystallographic studies, Communications Biology, 5(1):640, 2022.

New in version 1.2.0

• Untreated extrapolated electron density maps ("keep_no_fill") are now automatically added to the output, allowing easy comparison of negative_and_missing strategies.
• Resolution boundaries for scaling can be specified.

See release notes and manual for more info and other new features.

Getting Started

Xtrapol8 uses no external modules in addition to standard python and those from cctbx (which comes with Phenix). It also uses some programs from CCP4. This means that you have CCP4 and Phenix, you are ready to go. Follow the steps below to make sure that Xtrapol8 can find what it needs.

Prerequisites

You need the ccp4 and Phenix software suites, and both should be setup via the command line. Below you find a detailed description on how to setup CCP4 and phenix correctly for Xtrapol8 using a terminal on Mac:

1. Add Phenix and the cctbx modules to your PATH: Source the file phenix_env.sh folder (you can use Finder to find out which Phenix version you have installed and where to find phenix_env.sh):

   source /Applications/phenix-1.19.1-4122/phenix_env.sh

2. Add CCP4 to your PATH: In the same terminal source ccp4.setup-sh (again you can use Finder to find out which CCP4 version you have installed and where to find phenix_env.sh):

   source /Applications/ccp4-7.1/bin/ccp4.setup-sh

3. Check if Phenix and CCP4 programs can be found (you should get the paths in return):

   which phenix.refine
   which scaleit

   • You can add step 2 and 3 to your ~/.profile, ~/.zprofile or ~/.bashrc file if you want to avoid doing these steps each time you open a new terminal. Using your favorite editor (e.g. nano):

     nano ~/.zprofile
     #Setting Phenix and ccp4
     source /Applications/phenix-1.19.1-4122/phenix_env.sh
     source /Applications/ccp4-7.1/bin/ccp4.setup-sh

Installation

Clone or download the Xtrapol8 repository. Take care that all files are stored in the same directory (don't move any file).

   git clone https://github.com/ElkeDeZitter/Xtrapol8.git

Or click on "Code" -> "Download ZIP" on the top.

Usage

Command line usage

Upon running Xtrapol8 without arguments, you get the full list of arguments that can be added using an input file or via command line arguments:

   phenix.python <folder/to/Xtrapol8>/Fextr.py

• You can add Xtrapol8 to your path for easier accessibilty, otherwise you just memorize where you've put it

  nano ~/.zprofile
  alias 'X8=phenix.python <folder/to/Xtrapol8>/Fextr.py'

An example input file with all changeable parameters can be found in the example or in the minimal_input

• Example using input file:
  1. Change the Xtrapol8.phil using your favorite text editor:

     nano Xtrapol8.phil

  2. Run Xtrapol8

     phenix.python <folder/to/Xtrapol8>/Fextr.py Xtrapol8.phil

• example using command line argument only:

  phenix.python <folder/to/Xtrapol8>/Fextr.py input.reference_mtz=hiephiep.mtz input.triggered_mtz=hieperdepiep.mtz input.model_pdb=hoera.pdb input.additional_files=jeej.cif input.additional_files=another.cif occupancies.list_occ=0.1,0.3,0.5 f_and_maps.f_extrapolated_and_maps=qfextr,qfgenick map_explorer.peak_integration_floor=3.5 map_explorer.peak_detection_threshold=4 output.outdir=fancy_party

• example using input file and command line:
  1. Change the Xtrapol8.phil using your favorite text editor:

     nano Xtrapol8.phil

  2. Run Xtrapol8 with additional arguments. The order of arguments determines how parameters will be overwritten

     phenix.python <folder/to/Xtrapol8>/Fextr.py Xtrapol8.phil refinement.phenix_keywords.refine.cycles=3

_For more information, please have a look into the Command line Manual_

Graphical User Interface usage

Xtrapol8 can also be launch via the GUI, called "XtrapolG8", and should be launched via the command line:

  phenix.python <folder/to/Xtrapol8>X8_gui.py

• You can add XtrapolG8 to your path for easier accessibilty, otherwise you just memorize where you've put it

  nano ~/.zprofile
  alias 'XG8=phenix.python <folder/to/Xtrapol8>/X8_gui.py'

• XtrapolG8 can also make use of a pre-made input file:

  • the input file can be loaded directly when launching XtrapolG8:

    phenix.python <folder/to/Xtrapol8>X8_gui.py Xtrapol8.phil

  • or the input file can be loaded from within XtrapolG8 via the File menu:
    "File" -> "Open Phil"

• XtrapolG8 can also be used to inspect results from a former run, independent on whether it was run via the GUI or the command line:
  "File" -> "Load Results"

_For more information, please have a look into the GUI Manual_

License

Xtrapol8 is published under the MIT License Xtrapol8 makes use of adapted cctbx modules, for which we additionally refer to the cctbx license The user is responsible to legally correct obtain and install ccp4, Coot and Phenix.

Contact

Elke De Zitter - elke.de-zitter@ibs.fr

Jacques-Philippe Colletier - jacques-Philippe.colletier@ibs.fr

Institut de Biologie Structurale - DYNAMOP