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 YoutTube channel of CCP4 CCP4 Study Weekend 2022 and CCP4 Study Weekend 2024

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). Don't forget to cite the software on which we build: * Liebschner, D. et al., Macromolecular structure determination using X-rays, neutrons and electrons: recent developments in Phenix, Acta Crystallogr. D. Struct. Biol. 75, 861–877 (2019). * Agirre, J. et al., The CCP4 suite: integrative software for macromolecular crystallography, Acta Crystallogr. D. Biol. Crystallogr. 67, 235–242 (2011). * Emsley, P. et al., Features and development of Coot, Acta Crystallogr. D. Biol. Crystallogr. 66, 486–501 (2010). * Grosse-Kunstleve, et al., The Computational Crystallography Toolbox: crystallographic algorithms in a reusable software framework, J. Appl. Crystallogr. 35, 126–136 (2002).

New since version 1.2.0

• Untreated extrapolated electron density maps ("keepnofill") are now automatically added to the output, allowing easy comparison of negativeandmissing strategies.
• Resolution boundaries for scaling can be specified.
• Refinement can be done with a combination of different programs, one should not restrict themselves to the CCP4 or Phenix suite.
• Easier usages of standalone verison to redo the difference-map and distance analysis for alpha estimation.
• New keywords. 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 phenixenv.sh folder (you can use Finder to find out which Phenix version you have installed and where to find phenixenv.sh): 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 phenixenv.sh): 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): sh 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): ```sh nano ~/.zprofile #Setting Phenix and ccp4 source /Applications/phenix-1.19.1-4122/phenixenv.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). sh 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: sh 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 sh 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: sh nano Xtrapol8.phil
  2. Run Xtrapol8 sh phenix.python <folder/to/Xtrapol8>/Fextr.py Xtrapol8.phil
• example using command line argument only: sh 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: sh nano Xtrapol8.phil
  2. Run Xtrapol8 with additional arguments. The order of arguments determines how parameters will be overwritten sh 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: sh 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 sh 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: sh 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