Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Next revision		Previous revision
lunchtime_byte_2023 [2022/12/21 12:22] – created - copy from webinar 2021 malylunchtime_byte_2023 [2023/01/05 12:39] (current) – cc* English maly
Line 1: Line 1:
-====== PAIREF -- lunchtime byte ======+====== PAIREF in CCP4 - CCP4SW Lunchtime Byte ======
  
-5 Jan 2023+5th Jan 2023
  
-===== Tutorial =====+[[https://pairef.fjfi.cvut.cz/docs/pairef_poli_ccp4sw2023/20230105_ccp4sw_pairef.pdf|{{pdf_icon.png?30x35}}]] [[https://pairef.fjfi.cvut.cz/docs/pairef_poli_ccp4sw2023/20230105_ccp4sw_pairef.pdf|Download presentation in PDF]]
  
-==== PAIREF installation: IMPORTANT: Please install PAIREF before the webinar ==== +In this short tutorial, we submit a paired refinement job using the //PAIREF// program, now distributed in the [[http://www.ccp4.ac.uk/|CCP4 suite]]. You can use our example data from interferon gamma from //Paralichthys olivaceus// (POLI)  (([[https://www.sciencedirect.com/science/article/pii/S1050464818302651|Zahradnik et al. (2018). Fish Shellfish Immunol. 79:140–152]])), PDB entry [[https://www.rcsb.org/structure/6F1E|6F1E]].
-Althought //PAIREF// has been developed to be installed easily, atypical computer setting can cause problems sometimes. Feel free to contact us via email ([[martin.maly@fjfi.cvut.cz]]) and we will help you.+
  
-//PAIREF// **depends** on the installation of the [[http://www.ccp4.ac.uk/|CCP4 Software Suite]] or [[https://www.phenix-online.org/|PHENIX]]. In this webinar, we recommend to have the CCP4 Suite installed as we will be focused on that. 
  
-In GNU/Linux or macOS, just open the terminal. +==== Download example data ====
  
-In Windows, find the CCP4 console or Phenix Command Prompt in the Start menu and open it (see the screenshots below).+[[https://pairef.fjfi.cvut.cz/docs/pairef_poli_webinar/PAIREF_webinar_poli.zip|Download the archive with the POLI  data]] and extract it in a folder - we will refer this folder as //working folder//. The archive contains: 
 +  * Structure model previously refined against data at 2.3 Å - //poli67_webinar_2-3A.pdb//. 
 +  * Merged diffraction data up to 1.9 Å - //poli67_1-9A.mtz// 
 +  * Unmerged diffraction data up to 1.9 Å - //poli67_XDS_ASCII_1-9A.HKL//
  
-{{:ccp4console.gif?nolink|}} {{:phenix_command_prompt.gif?nolink|}} 
  
-Now execute the following commands that install PAIREF into CCP4 environment on your computer: +==== Launch PAIREF from console in working directory ====
-<code> +
-ccp4-python -m ensurepip --user +
-ccp4-python -m pip install pairef --no-deps --upgrade --user +
-</code>+
  
-If the installation was not successful, please go through the section [[https://pairef.fjfi.cvut.cz/docs/installation.html#troubleshooting|Installation - Troubleshooting]] in our documentation.+Implementation of //PAIREF// to //CCP4i2// interface is under development but it is not available in the latest CCP4 version 8.0.007 yet. Thus, we will use the standalone [[https://pairef.fjfi.cvut.cz/docs/gui.html|graphical user interface (GUI)]] for //PAIREF// that can be launched from command line.
  
-**In the end, please check whether the installation was successful: Try to show the help message executing the following command:**+In Windows, find the CCP4 console in the Start menu and open it (see the screenshots below). In GNU/Linux or macOS, just open the terminal, assuming all the executables for CCP4 are available there.
  
-<code>ccp4-python -m pairef --help</code>+{{:ccp4console.gif?nolink|}} 
  
-If the help message appears, the installation seems to be successful. Please download also the data before the webinar - the instruction follows.+Then go to the folder where your structure model and diffraction data are saved using the command ''cd''. For example, if you saved those three files in the folder ''C:/Users/Lab/PAIREF_tutorial_poli'', write ''cd C:/Users/Lab/PAIREF_tutorial_poli'' into the console and press ''Enter''.
  
-==== Download data ====+Now execute the following command for launching the PAIREF GUI: 
 +<code>ccp4-python -m pairef --gui</code>
  
-In this tutorial, we will deal with the data from interferon gamma from //Paralichthys olivaceus// (POLI)  (([[https://www.sciencedirect.com/science/article/pii/S1050464818302651|Zahradnik et al. (2018). Fish Shellfish Immunol. 79:140–152]])), PDB entry [[https://www.rcsb.org/structure/6F1E|6F1E]].+The structure of POLI was originally refined at 2.3 Å resolution. Nevertheless, we will inspect an impact of the reflection beyond this high-resolution cutoff on the model quality, We have data processed up to 1.9 Å resolution. Thus, we will add three high-resolution shells step by step: 2.3-2.1 Å, 2.1-2.0 Å and 2.0-1.9 Å.
  
-[[https://pairef.fjfi.cvut.cz/docs/pairef_poli_webinar/PAIREF_webinar_poli.zip|Download the archive with the data]] and extract it in a working folder. The archive contains: +In the //PAIREF// window, we need to specify: 
-  * Structure model previously refined against data at 2.3 Å - //poli67_webinar_2-3A.pdb//. +  * How we want to add high-resolution shells - put 2.1,2.0,1.9 to "Explicit definition of high-resolution shells" 
-  * Merged diffraction data up to 1.9 Å - //poli67_1-9A.mtz// +  * Input structure model 
-  * Unmerged diffraction data up to 1.9 Å - //poli67_XDS_ASCII_1-9A.HKL//+  * Input merged diffraction data that contains free flags 
 +  * Input unmerged data - //recommended, not required// 
 +  * X-ray weight term 0.06 - //from prior knowledge for this particular data set//
  
-**If you have installed //PAIREF// and extract the data, you are ready for the webinar.** :-)+{{ :pairef_webinal_poli_gui_win.png?nolink |}}
  
-==== Open console in working directory ==== +And now we can press RUN and open the HTML log file in a web browser.
-Open terminal (GNU/Linux, macOS) or CCP4 console (Windows) and go to the folder where your structure model and diffraction data are saved. For example, if you saved those three files to folder ''C:/Users/Lab/PAIREF_tutorial_poli'', write ''cd C:/Users/Lab/PAIREF_tutorial_poli'' into the console and press ''Enter''.+
  
-==== Run PAIREF in command line ==== +==== Results ====
-We will add three high-resolution shells step by step: 2.3-2.10 Å, 2.1-2.0 Å and 2.0-1.9 Å. Run //PAIREF//: <code>ccp4-python -m pairef --XYZIN poli67_webinar_2-3A.pdb --HKLIN poli67_1-9A.mtz -u poli67_XDS_ASCII_1-9A.HKL -r 2.1,2.0,1.9 -w 0.06 -p poli_webinar</code> +
-Note: The structure model was refined using X-ray weight 0.06, we have to keep this setting to gain unbiased results.+
  
-==== Graphical user interface ==== +The results should look similar to ours: [[https://pairef.fjfi.cvut.cz/docs/pairef_poli_ccp4sw2023/PAIREF_poli_ccp4sw2023.html]].
-//PAIREF// provides also a [[https://pairef.fjfi.cvut.cz/docs/gui.html|graphical user interface (GUI)]] for intuitive setting of arguments without making up a command. However, it depends on the installation of CCP4 suite. For launching the PAIREF GUI, execute the following command: +
-<code>ccp4-python -m pairef --gui</code> +
-{{ :pairef_webinal_poli_gui_win.png?nolink |}}+
  
 +//PAIREF// ran all the calculation and did also an automatic suggestion of an optimal high-resolution cut off. Let's check the table on top of the HTML log file:
  
-==== Interpretation of results ==== +{{ :poli_ccp4sw2023_verdict_table.png?nolink |}}
-Follow the note ''%%------> RESULTS AND THE CURRENT STATUS OF CALCULATIONS ARE LISTED IN A HTML LOG FILE%%'' in the program output and open the stated file in your preferred web browser (//e.g.// Firefox). The results should look similar to ours: [[https://pairef.fjfi.cvut.cz/docs/pairef_poli_webinar/PAIREF_poli_webinar.html]].+
  
-The first thing that should be checked is whether the refinements have converged. Scroll at the very bottom of page, here you can see plots of Rwork and Rfree vs. refinement cycle. We can conclude that all the refinements have converged.+The suggestion is based on the results plotted in the following graphs. Overall Rfree decreased for all the three high-resolution shells that denotes model improvement:
  
-Rfree decreased after the addition of shells 2.3-2.10 Å and 2.1-2.0 Å:+{{ :poli_ccp4sw2023_r-values.png?nolink |}}
  
-{{ :poli_webinar_r-values.png?nolink |}}+However, we should take into account multiple criteria. Since a perfect model gives an R-value of 0.42 against random data (i.e. pure noise) – assuming non-tNCS (translational non-crystallographic symmetry) data from a non-twinned crystal ((Evans, P. R. & Murshudov, G. N. (2013). Acta Cryst. D69, 1204-1214.)) – a higher R-value in the (current) high-resolution shell indicates either the involvement of high-resolution data without information content (the data are even worse than noise), or poor quality of the model, or the presence of tNCS. This is indicated for the shell  2.0-1.9 Å. 
 +{{ :poli_ccp4sw2023_rfree.png?nolink |}}
  
-Since a perfect model gives an R-value of 0.42 against random data (i.e. pure noise) – assuming non-tNCS (translational non-crystallographic symmetry) data from a non-twinned crystal ((Evans, P. R. & Murshudov, G. N. (2013). Acta Cryst. D69, 1204-1214.)) – a higher R-value in the (current) high-resolution shell indicates either the involvement of high-resolution data without information content (the data are even worse than noise), or poor quality of the model, or the presence of tNCS. This is indicated for the shell  2.0-1.9 Å. +CC* is a model-independent measure of noise is in the diffraction data. For this data set, CC* is higher than CCwork in the whole resolution range, except the shell 2.0-1.9 Å where CC* is undefined due to negative CC1/2. That means overfitting was not indicated but the shell 2.0-1.9 Å should be discarded because these data are very noisy. Note that to access overfitting, it is not needed to use test set, so the comparison of CC* with CCwork is much better than with CCfree as CCwork is calculated on more data. 
-{{ :poli_webinar_rfree.png?nolink |}}+{{ :poli_ccp4sw2023_ccwork.png?nolink |}}
  
-CC* a model-independent measure of noise is in the diffraction data. CC* is higher than CCwork in whole resolution range (except the shell 2.0-1.9 Å where CC* is undefined due to negative CC1/2. Thus, the overfitting was not indicated. To access overfitting, it is not needed to test set, so the comparison of CC* with CCwork is much better then with CCfree as CCwork is calculated on more data. +We should also check whether the refinements have converged. Scroll at the very bottom of page, here you can see plots of Rwork and Rfree vs. refinement cycle. We can conclude that all the refinements have converged, indeed.
-{{ :poli_webinar_ccwork.png?nolink |}}+
  
-**We can conclude that the high-resolution cutoff can be set to 2.0 Å.**+**We can conclude that the high-resolution limit of the data is ca. 2.1 Å.**
  
 Merging statistics: Merging statistics:
Line 82: Line 75:
 07      2.10   2.00  49772   4021   12.38  98.51       0.3     0.1   16.989   17.721    4.963   0.027   0.008   0.2293 07      2.10   2.00  49772   4021   12.38  98.51       0.3     0.1   16.989   17.721    4.963   0.027   0.008   0.2293
 08      2.00   1.90  35920   4046    8.88  81.18       0.1     0.0   41.435   43.993   14.417  -0.132  -0.016   N/A</code> 08      2.00   1.90  35920   4046    8.88  81.18       0.1     0.0   41.435   43.993   14.417  -0.132  -0.016   N/A</code>
 +
 +==== Stay tuned, CCP4i2 interface for PAIREF is coming soon! ====
 +
 +{{ :pairef_ccp4i2_dev.png?nolink |}}
 +
 +==== Run PAIREF in command line ====
 +
 +It is also possible to run //PAIREF// in the command line. The job described here could be executed using the following command: <code>ccp4-python -m pairef --XYZIN poli67_webinar_2-3A.pdb --HKLIN poli67_1-9A.mtz -u poli67_XDS_ASCII_1-9A.HKL -r 2.1,2.0,1.9 -w 0.06 -p poli</code>
 +
  
 ===== Contact ===== ===== Contact =====
  
-In case of any questions or problems, please do not hesitate and write us: [[martin.maly@fjfi.cvut.cz]].+In case of any questions or problems, please do not hesitate and write us: m.maly #AT# soton.ac.uk.
  
 ===== Further reading ===== ===== Further reading =====