-
Notifications
You must be signed in to change notification settings - Fork 5
Documentation
- Farseer-NMR is under strong development:
- new features will be added and interfaces may change.
- Please expect changes in this Documentation as the program naturally evolves.
+ updated: December 2018
+ Farseer-NMR version: +1.3.0We are currently migrating our documentation PDF to this online wiki page. Find in this page the most updated information and in the PDF file all the information that has not yet been covered here.
Before running Farseer-NMR, please read carefully the Installation section. After the installation step two files will be generated: the farseer_gui (GUI interface) and the farseer_cmd (command line based). We strongly encourage you to use the GUI, but the command line interface can be very handy for advanced users or to repeat a calculation after minor settings changes.
To run the Farseer-NMR guided user interface, execute the farseer_gui file inside the bin folder.
./farseer_gui
You can run a Farseer-NMR calculation without using the GUI providing a previously configured config.json file and spectra folder. Nevertheless, we advocate the use of the GUI version for all users, advanced and beginners. To execute Farseer-NMR from the command line, proceed as follows:
- Setup your configuration file manually.
- copy the
default_config.jsonfile from thecorefolder to the folder where you wish to perform your calculation. - edit the file with your favourite text editor, the file contains several dictionaries with all the options possible to set up. Find a full description of the
default_config.jsonfile here and alter it accordingly to your needs. - or simply use a config file previously configured from the GUI.
- copy the
- Setup the
spectrafolder according to these instructions.- you can also used a
spectrafolder previously generated from a GUI run.
- you can also used a
- Execute Farseer-NMR with the following command;
./farseer_cmd <CONFIG.JSON> [PATH_TO_SPECTRA_FOLDER]
where, <CONFIG.JSON> is the path to your configuration file and [PATH_TO_SPECTRA_FOLDER] is an optional parameter to identify the path to the folder where the spectra folder residues. If not provided, Farseer-NMR will look for spectra_path parameter in the configuration file, if not present will take the current folder.
The Farseer-NMR installation and execution was tested on a Windows 10 Pro machine with satisfactory results (version +1.3.0); however, we cannot guarantee that both installation and execution will work on other Windows versions.
You are on Windows, so try double-click on the farseer_gui.py file ;-). In the current version (+1.3.0) the output generated during the calculation won't be shown on a pop-up window, it is registered in the farseernmr.log file. If you wish to see on-the-fly the calculations output you should run Farseer-NMR command line.
If double-click does not work, try launching the GUI via command line. For that, open the TERMINAL and navigate to bin folder inside the Farseer-NMR installation folder. Simply execute one of the executable scripts by calling its name WITHOUT any mention to the Python interpreter, for example:
YES:
farseer_gui.py
NO:
python farseer_gui.py
If this fails, try explicitly using your Python Farseer-NMR ENV executable. For example (from inside the bin folder):
C:\Users\<user_name>\<FarSeer-NMR>\miniconda\envs\farseernmr\python.exe farseer_gui
Replace the above python.exe ENV path for the one referent to your installation, you can find the that path in the install_reg.py file (created during the installation) under the variable name python_exec, for example:
python_exec = 'C:\Users\<user_name>\FarSeer-NMR\miniconda\envs\farseernmr\python.exe'
To run Farseer-NMR command-line, that is, without using the GUI follow the same instructions as for UNIX systems but considering the execution requirements described for lauching the GUI on Windows.
The Farseer-NMR configuration file is a JSON file that contains all parameters that setup a run organized in several dictionaries. The file can be edited using the Farseer-NMR user interface (we advise this method), but can be also edited manually using any text editor. Bellow a description of the default_config.json file that can be found in the core folder (dictionaries can be found not necessarily in this order):
Calculation settings are controlled by the fitting_settings dictionary and control the flow of the calculation run and main operations to be performed on the Farseer-NMR Cube:
"fitting_settings": {
"do_along_x": true, # analyse along Farseer-NMR cube X axis.
"do_along_y": false, # analyse along Farseer-NMR cube Y axis.
"do_along_z": false, # analyse along Farseer-NMR cube Z axis.
"expand_missing_yy": false, # search for missing residues along Y axis.
"expand_missing_zz": false, # search for missing residues along Z axis.
"perform_comparisons": false # perform stacking comparisons
}
Configures how FASTA files will be read:
"fasta_settings": {
"FASTAstart": 1, # the FASTA sequence starting number (can be negative)
"applyFASTA": false # if apply FASTA information to the calculation
},
As the name implies sets up general settings of the run ;-):
"general_settings": {
"chimera_att_select_format": ":", # selection format for the Chimera Attribute Files
"fig_dpi": 300, # figure plot dpis
"fig_file_type": "pdf", # figure plot file type
"fig_height": 11.69, # figure plot height
"fig_width": 8.69, # figure plot width
"has_sidechains": false, # Do your peaklists contain sidechain information?
"use_sidechains": false, # Do you wish to analyse the sidechain information in your peaklists?
"output_path": "", # where the output will be written
"spectra_path": "" # where the spectra folder will be written or loaded
},
PosF1_settings, PosF2_settings, csp_settings, Volume_ratio_settings, Height_ratio_settings and pre_settings (10.1016/j.str.2017.02.011):
"csp_settings": {
"cs_missing": "prev", # how missing residues will be represented in Bar plots
"csp_res4alpha": 0.14, # the default normalization Alpha value to calculate CSPs
"csp_res_exceptions": {"G": 0.2}, # exceptions to the general alpha values
"calccol_name_CSP": "CSP", # column name to register the output
"calcs_CSP": true, # flag true/false to execute calculation
"yy_label_CSP": "CSPs (ppm)", # Y axis label in plots
"yy_scale_CSP": 0.3 # Y axis scale
},
"PosF1_settings": {
"calccol_name_PosF1_delta": "H1_delta", # column name to register the output
"calcs_PosF1_delta": false, # flag true/false to execute calculation
"yy_label_PosF1_delta": "ppm", # Y axis label in plots
"yy_scale_PosF1_delta": 0.2 # Y axis scale
},
"PosF2_settings": {
"calccol_name_PosF2_delta": "N15_delta", # column name to register the output
"calcs_PosF2_delta": false, # flag true/false to execute calculation
"yy_label_PosF2_delta": "ppm", # Y axis label in plots
"yy_scale_PosF2_delta": 2 # Y axis scale
},
"Volume_ratio_settings": {
"calccol_name_Volume_ratio": "Vol_ratio", # column name to register the output
"calcs_Volume_ratio": false, # flag true/false to execute calculation
"yy_label_Volume_ratio": "Vi/V0", # Y axis label in plots
"yy_scale_Volume_ratio": 1.1 # Y axis scale
},
"Height_ratio_settings": {
"calccol_name_Height_ratio": "Height_ratio", # column name to register the output
"calcs_Height_ratio": false, #flag true/false to execute calculation
"yy_label_Height_ratio": "Hi/H0", # Y axis label in plots
"yy_scale_Height_ratio": 1.1 # Y axis scale
},
"pre_settings": {
"apply_PRE_analysis": false, # flag true/false to execute calculation
"gauss_x_size": 7, # the Gaussian window size for PRE smoothed curve
"gaussian_stdev": 1 # the standard deviation for PRE smoothed curve
},
Plotting flags control which plots will be draw for each parameter activated.
"plotting_flags": {
"do_ext_bar": true, # Extended Bar plot
"do_comp_bar": false, # Compacted Bar plot
"do_vert_bar": false, # Vertical Bar Plot
"do_res_evo": false, # Residue Evolution plot
"do_cs_scatter": false, # Chemical Shift Scatter Plot
"do_cs_scatter_flower": false, # Chemical Shift Scatter Flower plot
"do_DPRE_plot": false, # DeltaPRE plot
"do_heat_map": false # DeltaPRE Heatmap plot
}
Every visual detail in a Farseer-NMR plot can be configured via the config.json file (and if not let us know to implement ;-)). Bellow you find which dictionaries control which plots. Parameters inside dictionaries are self explanatory.
Bar plots are configured by three dictionaries that share the following hierarchy:
- series_plot_settings
- bar_plot_settings
- extended_bar_settings # Extended Bar plot
- compact_bar_settings # Compacted Bar plot
- vert_bar_settings # Vertical Bar Plot
Residue evolution plots are configured by two dictionaries that share the following hierarchy:
- revo_settings
- res_evo_settings # Residue Evolution plot
- cs_scatter_settings # Chemical Shift Scatter Flower plot
Delta PRE plots are configured by two dictionaries that share the following hierarchy:
- series_plot_settings
- DPRE_plot_settings
- heat_map_settings
Chemical Shift Scatter Flower is configured by cs_scatter_flower_settings dictionary.
The Farseer-NMR experimental setup is configured by the following dictionaries: peaklists, experimental_dataset and conditions. These configure the Experimental Tree as displayed in the GUI and are the basis that define how the spectra folder will be created. These dictionaries serve only GUI purposes and are not necessary to run Farseer-NMR from the command line; but can, and should, be used for traceability purposes. Find bellow an example:
"experimental_dataset": {
"298K": {
"protein_1": {
"reference": "peaklist_1",
"ligand_1": "peaklist_2"
}
}
},
"peaklists": {
"peaklist_1": "/home/user/my_peaklists/peaklist_1.csv",
"peaklist_2": "/home/user/my_peaklists/peaklist_2.csv"
},
"conditions": {
"x": [
"reference",
"ligand_1"
],
"z": [
"298K"
],
"y": [
"protein_1"
]
}
Lists the .fasta files that will be used for the calculation run if requested. This dictionaries serves only GUI purposes and are not necessary to run Farseer-NMR from the command line; but can, and should, be used for traceability purposes. Find bellow an example (following the example above):
"fasta_files": {
"protein_1": "home/user/my_fasta/protein_1.fasta"
}
Lists the .pre files containing the theoretical PRE profile that will be used for the calculation run if requested. This dictionaries serves only GUI purposes and are not necessary to run Farseer-NMR from the command line; but can, and should, be used for traceability purposes. Find bellow an example (following the example above):
"pre_files": {
"protein_1": "home/user/my_pre/protein_1.pre"
}
The spectra folder is the folder that contains the input data for Farseer-NMR. This folder should be called spectra otherwise Farseer-NMR will not see it. The spectra folder contains hierarchic subfolders that configure the dimensions (axes) of the Farseer-NMR Cube.
The Farseer-NMR guided user interface (GUI) will automatically configure the spectra folder according to the defined Experimental Tree Setup. However, you may wish to configure the spectra folder manually and run Farseer-NMR command line. The spectra folder is created by the GUI, and can be manually setup, as follows:
# experimental example
:3rd (Z) dimension: para and dia (main folders)
:2nd (Y) dimension: 278K and 298K (subfolders)
:1st (X) dimension: l1, l2 (peaklist files)
: fasta files are used (seq.fasta)
: pre files are used (tag1.pre)
# / character represents a folder
spectra/
dia/
278K/
l1.csv
l2.csv
seq.fasta
298K/
l1.csv
l2.csv
seq.fasta
para/
278K/
l1.csv
l2.csv
seq.fasta
tag1.pre
298K/
l1.csv
l2.csv
seq.fasta
tag1.pre
Important considerations:
- data points must have the same name, for example: peaklists
l1.csvare different in each subfolder because they relate to the different experimental conditions, however they must have the same file name. The same applies for subfolder names of the Y dimension. - peaklist files should be in the CCPNMRv2 format:
Number,#,Position F1,Position F2,Assign F1,Assign F2,Height,Volume,Line Width F1 (Hz),Line Width F2 (Hz),Merit,Details,Fit Method,Vol. Method
1,1,7.541173985596941,103.37071938371595,2IleH,2IleN,9.59625e+06,2.13965e+09,19.97441,12.31768,1.00000,None,parabolic,peak fit
2,2,6.7857114833946115,120.58007910759581,5LeuH,5LeuN,4.76242e+06,1.27545e+10,30.26231,14.06644,1.00000,None,parabolic,peak fit
3,3,11.482623595183078,103.74619375150236,6ThrH,6ThrN,2.06871e+07,1.65371e+09,21.10803,11.22444,1.00000,None,parabolic,peak fit
4,4,11.839501094062008,126.55424173079811,7LeuH,7LeuN,1.29616e+07,1.09318e+09,22.16974,12.20944,1.00000,None,parabolic,peak fit
- If FASTA information is to be used, one
.fastafile must be given to each Y data point subfolder - If analysing PRE data, one
.prefile should be given to each Y data point subfolder in the Z datapointparafolder.