Farseer-NMR: automatic treatment, analysis and plotting of large, multi-variable NMR data

We present Farseer-NMR (https://git.io/vAueU), a software package to treat, evaluate and combine NMR spectroscopic data from sets of protein-derived peaklists covering a range of experimental conditions. The combined advances in NMR and molecular biology enable the study of complex biomolecular systems such as flexible proteins or large multibody complexes, which display a strong and functionally relevant response to their environmental conditions, e.g. the presence of ligands, site-directed mutations, post translational modifications, molecular crowders or the chemical composition of the solution. These advances have created a growing need to analyse those systems’ responses to multiple variables. The combined analysis of NMR peaklists from large and multivariable datasets has become a new bottleneck in the NMR analysis pipeline, whereby information-rich NMR-derived parameters have to be manually generated, which can be tedious, repetitive and prone to human error, or even unfeasible for very large datasets. There is a persistent gap in the development and distribution of software focused on peaklist treatment, analysis and representation, and specifically able to handle large multivariable datasets, which are becoming more commonplace. In this regard, Farseer-NMR aims to close this longstanding gap in the automated NMR user pipeline and, altogether, reduce the time burden of analysis of large sets of peaklists from days/weeks to seconds/minutes. We have implemented some of the most common, as well as new, routines for calculation of NMR parameters and several publication-quality plotting templates to improve NMR data representation. Farseer-NMR has been written entirely in Python and its modular code base enables facile extension. Electronic supplementary material The online version of this article (10.1007/s10858-018-0182-5) contains supplementary material, which is available to authorized users.


I. Introduction and README a) What is Farseer-NMR?
The daily problem Biomolecular NMR-related projects require thorough investigation of a system under study, which usually translates into testing it against multiple experimental variables (e.g. ligand concentration, ligand nature, temperature, pH, paramagnetic agents). Such experimental setups ultimately generate large and complex datasets of peaklists that easily overload human capacity of analysis by standard means. Treating peaklist datasets of this nature in a fast and straightforward manner is a growing requirement for researchers. NMR researchers beneft from many computational tools, available at the diferent stages of the NMR projects pipeline, which boost their capacity to extract the most out of NMR experiments in a fast and reliable way. In spite of this, one of the connections in the NMR analysis pipeline is broken due to a lack of software availability. This connection is the transformation of curated peaklists into biophysically-relevant restraints and data-rich tables and plots.

The solution
Farseer-NMR is a software package that automatically treats, calculates and plots NMR data and parameters derived from experiments measuring the sequential response of a system to a single or multiple correlated variables. The process of handling large amounts of diverse NMR data can be tedious, repetitive, error prone and time-consuming; taking days and, in some cases, even weeks. Farseer-NMR removes the tedium, minimises the efect of human error, reduces the time burden to seconds/minutes and simplifes data visualisation. Figure 1 shows the position of Farseer-NMR into the NMR analysis pipeline.

How?
Farseer-NMR uses high-dimensional Python 3 Numpy/Pandas arrays to deconvolute multivariate dependent NMR data into simpler parts, which are straightforwardly analysed and presented in a human-readable manner and without information loss.

What else?
We have implemented the most common (and some not so common) calculation routines (e.g. PRE, CSP) and several publication-quality plotting templates to improve data representation. Farseer-NMR is written completely in Python and can read the most common NMR peaklist formats: Ansig, NmrDraw, NmrView, Sparky and CcpNmr Analysis 2.4 via simple drag-and-drop import. The graphical interface is written using the most up-to-date version of PyQt, PyQt v5.8, and its modular code base enables facile extension.

b) README Project Repository and Download
Find here the Farseer-NMR Homepage. You can download the latest release here or browse the project GitHub repository here.
Please keep in mind that this is a living and ongoing project, built by the NMR community and to the NMR community. Please expect bugs :-). We have done our best eforts to make Farseer-NMR as solid as a rock but many issues can only be identifed and solved after interaction with the users and users daily problems. So, let's interact! :-)

Installation
Farseer-NMR runs on Unix based systems. Attempting to run the current version under Windows machines will fail. Farseer-NMR has been built in its entirety using Python libraries and we try to keep it up-to-date with the Python community. To install Farseer-NMR frstly: 1. Unpack the downloaded version.
2. In your Terminal emulator, navigate to the unpacked Farseer-NMR folder.
There are three diferent ways to install Farseer-NMR according to your system setup, here are organised from the simplest to the hardest:

3) Installation for advanced users
If you are an advanced user who is profcient in manually managing your own installed Python libraries, you can get a list of the libraries required to run Farseer-NMR in the architecture respective spec-fles inside the Documentation folder. Afterwards, to create the run_farseer.sh fle execute: ./Linux_install_manual.sh

Running Farseer-NMR
Before running Farseer-NMR, please read carefully the Installation section. After Farseer-NMR has been correctly installed, to run execute: ./run_farseer.sh

Running without the GUI
A Farseer-NMR calculation run can be launched without the GUI interface. Nevertheless we advocate the use of the GUI version for all users, advanced and beginners. All implemented and functional features are available through the GUI. We advise the use of the command line version only for developers. For further information, see here.

Warnings, Errors and Troubleshooting (WET) list
We have implemented several fail safe checks during the Farseer-NMR calculation runs to warn the users when the input data or confguration would lead to erroneous behaviour. When an error is found, Farseer-NMR outputs a short explanatory message and the user is redirected to a full explanation under the Wiki WET page.

Participate in the Farseer-NMR community
There are several ways that you can help us improve Farseer-NMR and be part of its community! :-)

Reporting a bug
If you fnd bugs, mis-functional or non-functional features during your calculation runs, please report them by using the I ssues tab under the GitHub repository. We have prepared a set of labels that help you to specify the nature of the issues.

Suggesting Features
You can also use the I ssues tab under the GitHub repository to suggest new features that you would like us to implement or that you would like help implementing.

Become a collaborator
Help us implement new features! Do you have your own NMR analysis routines that you would like to see implemented in Farseer-NMR? You can fork the Farseer-NMR project to your own GitHub account, write the functionalities and prepare a pull request for us to review and help you out! We have prepared a Farseer coding style guide for developers so that we keep code readability consistent. We kindly request that contributors to the project adhere to this style guide. Even if you're not an experienced programmer, please get contact with us and we will be happy join forces with you to introduce your functionalities!

Mailing list
Post on our mailing list for questions, discussion and help!

Social Network
Find us on: • Twitter @Farseer-NMR • Research Gate

License
The entire Farseer-NMR code base comes with no liability and is licensed under the GPL-3.0. 6 April 2018 9/86 Farseer-NMR Documentation -II.The Farseer-NMR data structure: II.The Farseer-NMR data structure

II. The Farseer-NMR data structure
Farseer-NMR performs complex analysis on series of NMR peaklists that inspect a system's dependency on (up to) three diferent variables (e.g. ligand concentration, ligand nature, temperature, pH, paramagnetic agents, etc…).

Example 1:
Given a protein system P, the binding profle of the ligand L1 was measured at fve concentrations (C). The same protein P was screened against four related ligands (L1, L2, L3, L4) and each experiment was repeated at three diferent temperatures (T1, T2, T3).
The above experimental setup embodies a set of 12 experimental series, which result from the combination of two continuous variables (temperature and concentration) and one discontinuous variable (ligand nature). In this case, a total of 60 2D-NMR experiments would be performed (5×4×3). NMR data are sensitive to the contribution of each experimental variable. In order to fully understand the contribution of each variable to the system under study, it is essential to have a fexible, yet simple way to access the data, which preserves all information content and allows the deconvolution of these complex contributions into simpler parts.

a) The Farseer-NMR Cube
To freely navigate and explore experimental datasets spanning multiple conditions, Farseer-NMR loads the whole input data to a single digital object, a Python Numpy/Pandas five-dimensional array; which, for the sake of simplicity, can be visualized as a cube made of 2D data points, where the threedimensional axes of the cube (x, y, z) are the experimental variables (in Example 1, ligand concentration, ligand nature and temperature range), and each data point is a 2D-NMR peaklist (loaded as pandas.DataFrame) with the respective rows referring to the residues and columns to the experimental observables previously extracted from the user preferred NMR analysis suite. We have named this object the Farseer-NMR Cube ( Figure 2).
Cube dimensions can have any number of data points and, they can be accessed and combined freely to generate a panoply of series, which encode the answers to diferent experimental questions. 6 April 2018 11/86

b) Multidimensional Analysis Workfow
The great advantage of having the whole experimental dataset in a single digital object, the Farseer-NMR Cube, is that it can be arbitrarily sliced to investigate specifc questions, which are not limited to the acquisition schedule of the multivariable data. Following the previous example, we can ask diferent questions of the dataset that directly relate to the conditions assayed: c. Do they evoke the same changes in P?

Temperature variations:
a. How does the temperature afect the binding profles of the ligand library?
As explained above, the Farseer-NMR Cube's three dimensional axes correspond to the evolution of the system as a function of the three experimental assayed conditions and, therefore, we can explore the above cited questions by slicing the cube along the diferent axes, where the above points 1, 2 and 3 correspond to Farseer-NMR Cube's axes X, Y and Z, respectively.

A Series of NMR experiments
A series of NMR experiments is any set of experiments (peaklists) that represent the evolution/change of a system or experimental response as a function of an external variable, which can be continuous or discontinuous, where the frst experiment is the reference against which all the other experiments are consecutively evaluated.
Following the above rationale, and considering a multivariable dataset of peaklists represented in the Farseer-NMR Cube, we can fx two points along two given axes (e.g. X=C2 and Z=T2) and slice along the third axis (Y) to generate an 1D-vector of 2D-NMR peaklists, which would correspond to the experimental series where Y=L1 is the reference experiment of the series.
From the Farseer-NMR Cube, we can extract as much sets of 1D-vectors (series of peaklists) as diferent combinations of the three axes X, Y and Z.
Following example 1, out of the 12 experimentally-acquired series relating to the progression of ligand concentration (4×3, in our example), Farseer-NMR can extract up to 47 in silico generated series of experiments that result from the diferent combinations of the other experimental variables:

Navigating the Farseer-NMR Cube's Axes
The implemented workfow sequentially generates series of experiments (peaklists) out of the Farseer-NMR Cube, which result from all possible combinations of X, Y and Z. This is accomplished by fxing data points along two axes and extracting the series along the third one. In other words, say, the progression of X as a function of a given Y and a given Z.

Evolution along the X axis
Farseer-NMR analyses how the whole dataset evolves along the X axis by fxing one data point in Y and another in Z and creating a series of peaklists along the X axis. A full set of series is generated by walking through the Y and Z data points ( Figure 3). Following example 1, a total of 60 NMR experiments (peaklists) are organized in a Farseer-NMR cube with dimensions 5x4x3 (XxYxZ). Analysing the dataset along the X axis generates 12 experimental series that will be analysed individually according to the Analysis Routines. Farseer-NMR Documentation -II.The Farseer-NMR data structure: b)Multidimensional Analysis Workfow

Evolution along the Y axis
Following the same rationale as for Evolution along the X axis, in this case, Z and X are fxed and series of peaklists are generated along the Y axis ( Figure 4).

Figure 4:
Representation of how the Y axis series are generated along the Farseer-NMR Cube.

Evolution along the Z axis
Following the same rationale as for Evolution along the X axis, in this case, X and Y are fxed and series of peaklists are generated along the Z axis ( Figure 5).

Analysis of Experimental Series
Experimental series are analysed by evaluating each peaklist in the series to the series' reference peaklist. The diferent NMR parameters calculated (chemical shift perturbations, intensity ratios, etc.) are then stored directly in each peaklist DataFrame and conveniently exported in the diferent available formats (tables, plots, …) carefully structured into hierarchical folders. Farseer-NMR contains a set of analysis routines that can be applied to extract the most out of each NMR peaklist series.

c) The Farseer-NMR Analysis Routines
Series of NMR peaklists are extracted from the Farseer-NMR Cube following to the Multidimensional Analysis Workfow and according to the user-defned preferences. Each series can be viewed as a vector of two-dimensional NMR peaklists (data tables) that represents the evolution of a system as a function of an experimental variable, which can be continuous or discontinuous. In this vector, the frst point in is the reference peaklist followed by the other peaklists in the series. Each series is analysed according to a workfow of routines, the Farseer-NMR routines, which can be summarised in three main steps: 1. General parsing and formatting, where all the peaklists are expanded to the same size through identifcation of missing and unassigned residues.
2. For each series, NMR parameters are calculated from the NMR observables, showing the evolution of these along the series.
3. Results are conveniently plotted and exported in user-friendly parsed data tables organised in dedicated folders. Farseer-NMR Documentation -II.The Farseer-NMR data structure: c)The Farseer-NMR Analysis Routines

Treating and Formatting peaklists
Before biologically relevant NMR Parameters can be calculated, peaklists in a Farseer-NMR Series must be treated and formatted and an initial set of information must be parsed out and organised.
The combined workfow of the routines presented bellow serve three purposes: 1. Parsing assignment information to a higher readability level a. Reading Assignment Information 2. Identifcation of missing and unassigned residues a. Identifying the missing residues b. Identifying the unassigned residues 3. Expansion of all loaded peaklists to the same size in rows and columns, this allows direct evaluation and comparison by computational means.

Technical consideration
For the sake of clarity, the above mentioned routines can be understood as being executed during at the Farseer-NMR Series level, after extracting a series from the Farseer-NMR Cube. However, these are actually performed before the creation of the Farseer-NMR Cube and while the peaklists are being organised hierarchically in the PeakList Tree, even though the end result is the same, except for very specifc cases. The exact algorithm can be described as follows, practical considerations are also explained: 1. By default, identifcation of missing residues is performed only along the X axis by evaluation of each peaklist in the X axis series with the reference.
a. To expand this analysis to the other axes, the user must activate the search for missing residues Y/Z fag . This option is especially useful when analysing paramagnetic data, because it allows tracking of peaks that disappear solely by the introduction of the paramagnetic tag.
2. Identifcation of unassigned residues based on FASTA fles takes place only along the X axis, which means that FASTA fles are unique for each Y data point; as described, diferent FASTA fles can only be input along the Y axis.
a. This can be overcome by activating the corresponding fag in search for missing residues Y/Z menu.

Reading assignment information
NMR peaklists are simply tables were rows represent residues and columns contain all the information regarding residue identifcation, NMR observables and notes.
In the preferred peaklist format of Farseer-NMR (CCPNMR v2 format), assignment information is concatenated into a single column (Assign F1 in the format 1MetH) and it is therefore necessary to split this information into a more usable format. Three additional columns are created (Res#, 1-letter, 3letter) to store the assignment information and this information is used to index all the data and resulting calculations ( Figure 7). 6 April 2018 21/86

Identifying missing peaks
When performing a series of NMR experiments as a function of an external variable, it is common to lose track of a certain number of peaks, this might due to linewidth broadening or to peak overlap. As a consequence, extracted peaklists most likely difer in size, i.e. diferent numbers of rows. We describe disappearing peaks as missing peaks. It is of great importance to identify these peaks (better put, missing peaks) as they represent the regions most sensitive to the environment, therefore, they are information rich.
Technical note: The diference in peaklists size greatly hinders direct and straightforward analysis of the peaklists fles in traditional plotting tools, because row identities won't match when comparing row by row. In the past, this issue had to be handled manually, whereas Farseer-NMR does it automatically.
The second task of Farseer-NMR is to identify missing residues and, thus, expand all the peaklists in a series to the same size of the reference (number of rows). New rows are added for each missing residue found, and new column is created, named Peak Status column, to tag residues as measured or missing according to their nature. Other columns are flled with user defned default values or numpy.nan values ( Figure 8). 6 April 2018 22/86 Figure 8: New rows are added to identify the peaks that were missing with respect to the reference experiment.

Identifying unassigned residues
This feature is optional and is performed in a similar manner to the identifcation of the missing residues , with the exception that all the peaklists in the series (reference included) are compared to a previously loaded FASTA fle containing the protein's full primary structure. New rows identify the unassigned residues and the tag unassigned is added to the Peak Status column. 6 April 2018 23/86 Figure 9: New rows are added to identify those residues that are not assigned in the reference, and in consequence, in the whole series.

Performing Calculations
NMR Parameter calculation, or any related routine, is performed by evaluating each data point (peaklist) in the Farseer-NMR series being analysed to its reference experiment (peaklists), which is the frst in the series of peaklists.
The results are added to newly-generated columns in the peaklists' pandas.DataFrames, which are all exported together at the end of a run. Farseer-NMR can calculate:

Plotting the results
Farseer-NMR contains several publication-quality plotting templates to represent calculated data. For each series analysed, the calculated NMR parameters can be plotted in any and all available templates. Each template is highly customisable and enables a user to adapt the representation of data to diferent publications' requirements.

d) Comparative/stacking Analysis
Comparative Analysis, also described as stacking analysis, does not generate new data. Rather, it consists in parsing algorithms that reorganise and stack the Farseer-NMR results diferently. Note: comparative analysis generates additional pseudo dimensions in the Farseer-NMR Cube , which are essential to analyse, for example, paramagnetic ally -derived restraints .

Example 2:
A protein P was investigated against fve progressive concentrations of two similar, yet not identical, ligands (L1 and L2), at 298K. The Farseer-NMR Cube of this data set has the following form ( Figure 10): The z dimension consists of a single datapoint (298K), and therefore can be disregarded (although, technically, it exists). Consider the case where the user wants to analyse the two experimental series for L1 and L2 only along the x axis of the Cube, that is, in terms of increasing ligand concentration. In this case, two folders containing the corresponding results for L1 and L2 are generated (further reading on folder organization) containing all the tables and plots requested by the user (analysis routines).
The generated plots, within each folder, will represent the evolution of the experimental series in response to increasing ligand concentration. However, it can be fruitful to compare the results obtained for the two ligands at a given concentration, in other words, have that information gathered in a single fgure/fle/table. This requirement could be fulflled by the user by simply opening the two plotting fgures (or hard copies) and placing them side by side for comparison. This manual procedure would quickly become awkward when comparing large experimental datasets in which several points were acquired for a particular variable: e.g. screening a library of 20 ligands. To solve this issue, Farseer-NMR has implemented a special routine.
Following on from the above example , the data generated along the X axis can be compared/stacked along the Y axis, because there are two datapoints along the latter dimension, but it cannot be compared/ stacked along the Z axis (temperature), because there is only one point on this axis and there is nothing to compare with. The subsections below describe the diferent possibilities that can be explored in Comparative/Stacking analysis. 6 April 2018 26/86

Calculating along X and stacking along Y
Farseer-NMR comparative analysis generates stacked plots and tables along the Y axis for each of the datapoints of the X axis, containing the results previously obtained from the evaluation of the extracted series along the X axis (ligand concentration), as shown in Figure 11. N.B.: Comparing along the Y axis is diferent from analysing an experimental series along the Y axis ! In the former no new data is created while in the latter new NMR parameters are indeed calculated. 6 April 2018 27/86 Figure 11: Schematic representation of how results generated along the X axis are compared along the Y axis.
Calculating along Y and stacking along X Similar to the above, NMR parameters data, tables and subplots resulting from calculations along the Y axis are stacked along X. 6 April 2018 28/86 Calculating along Z and stacking along X Similar to the above described, subplots resulting from calculations along the Z axis are stacked along X. 6 April 2018 29/86 Figure 13: Schematic representation of how results generated along the Z axis are compared along the X axis.

Stacking for each dimension/experimental variable.
The same rationale can be applied to any dimension. Therefore, for each condition axis, stacking can be made along the other two axes, as long as the axis along which we want to perform the stack has more than one datapoint. Consider the previous example where 12 experimental series summing 60 HSQC experiments investigating the system's dependence on 3 diferent variables -Farseer-NMR Cube has dimensions of 5×4×3.
We have seen that in total 4×3 series can be analysed along the x axis. Stacking these results along the Y axis will generate 5×3 newly parsed series (not new data) and, stacking performed along the Z axis results in 5×4 additional series of parsed data. 6 April 2018 30/86 Farseer-NMR Documentation -III.The Farseer-NMR Program: III.The Farseer-NMR Program

III. The Farseer-NMR Program
The Farseer-NMR program consists of two main blocks: the Core and the Graphical User Interface (GUI). The Core contains all the libraries, functions and algorithms for data treatment, organization and output generation. While the curated GUI organizes all the available functionalities in a human-readable and convenient graphical menus that allow users from all expertises to take the maximum beneft from Farseer-NMR.
The two coding blocks function independently and communicate with which other only via a confguration fle in JSON format. The GUI can load and save the settings to the confg.json fle that serves as input to the Core when a calculation is launched.
In this section you will fnd general information on how to setup a Farseer-NMR Run via the Graphical User Interface, our main and recommended way of using of Farseer-NMR. It is possible also to run Farseer-NMR via command line using only the Core code, though we advise this use only for developers and, even then, only in certain cases.
Further sections are dedicated to explaining the implemented calculations, additional functionalities, organization of the generated output and the plotting templates available.
Section VII -Tutorials provides real case examples with extended explanations on how to use Farseer-NMR. 6 April 2018 31/86 Farseer-NMR Documentation -III.The Farseer-NMR Program: a)The initial input structure

a) The initial input structure
Farseer-NMR performs complex analysis on NMR peaklist datasets by generating experimental series (of peaklists) from permutation of the experimental variables defned as described in the Multidimensional Analysis Workfow subsection.
To initiate a Farseer-NMR run, and hence create the Farseer-NMR Cube, data should be input in the form of a hierarchical tree that comprises the three experimental variables (Cube's axes): X, Y and Z. A logical tree of experiments is created where the top level corresponds to the Z axis, followed by the Y axis data points and fnally the X axis data points, see next subsection.

Example 3:
Two protein mutants (mut1 and mut2), in samples of a 50µM concentration, were measured (NMR 1 H-15 N HSQC) against ligandA in three increasing concentrations 50µM, 100µM and 200µM. Mut1 and Mut2 were labeled with the paramagnetic tag, MTSL and, therefore, two diferent series of experiments were acquired: an initial paramagnetic series and a diamagnetic series that serves as reference to the frst one. A total of 2x2x3=12 NMR experiments were measured. After analysing the spectra and exporting the resulting peaklist fles, containing all the NMR observables and residue information, we face the task of extracting biologically relevant information out of those data.
The structure of these experiments can be organized hierarchically in the following way: This structure is the base of Farseer-NMR data structure (peaklist dataset) and is from this that the Cube will be created.

b) Setting up the Experimental Tree
To confgure the Farseer-NMR Cube a hierarchical tree (Z → Y → X) must be defned and populated with the corresponding peaklists, as explained in the previous section (IIIa). Peaklists can be input in two diferent ways: 1) Through selection of a directory path via the Peaklist Dataset Folder feld in Settings tab, which selects the folder containing the peaklists (Figure 14) or 2) they can be directly dropped into the Side bar of the Peaklists tab (Figure 15), this method can be perform in addition to method 1).
Practical considerations: • Peaklist fles in the Side Bar cannot share the same name.
• A description of the compatible peaklist fle types and formats can be found here.
The number of data points in each axis can be defned as well as the name for each data point. The Setup Experimental Series button draws the experimental tree which must be populated with the peaklists by drag and drop from the side bar. Peaklists in the three can be placed back into the side bar back via a right mouse menu.
A maximum of 15-10-10 data points per axis X-Y-Z can be defned in the GUI. If your project requires additional data points please contact us! :-)

Logical order of the experiments
At some point during the input procedure, the user needs to tell Farseer-NMR the logical order of the experiments, that is, which is the reference and which experiments follow and by which order. The logical progression of the experiments if defned by the order input during the creation of the Experimental Tree. In other words, the order in which the datapoints are created defnes the logical order of the experiments inside the Farseer-NMR Cube, where the frst experiment (peaklist) is always taken as the reference. Further information on how this order is maintained can be found in the results folder hierarchy section.

Known issues:
• An issue related to the PyQt library is known to interfere at this stage by rendering invisible or repeating the peaklist names in the Side Bar and the Tree. If such happens simply click the Setup Experimental Series button to return things back to normal. We are making eforts to solve this. 34/86

c) Settings Tab
All the settings that have reached a stable state are available in the Farseer-NMR user interface and can be confgured directly in the Settings tab. Experimental routines under development will be available frstly only via the JSON confguration fle.
Settings are categorised in individual boxes according the routines or group of routines to which they belong. Additional, and specifc, settings may be available via pop-up menus.
The Calculation Output Folder is the folder where the spectra will be parsed in and all the output results will be stored according to the Results Folder Hierarchy.
Plotting settings submenus are hierarchical. For example, settings under General Series Plot Settings apply to every plot categorised as Series Plot, which are the bar plots and the DPRE map.
The Load/Save Configuration buttons allow the user to keep copies of the confguration JSON fle containing information of the whole Farseer-NMR session. A previous session can be readily recovered simply by loading a previously confgures JSON fle -read further.  where the CALCULATION_FOLDER is the folder containing the hierarchical spectra/ folder. Whereas the GUI will create the spectra/ folder for you automatically, to run Farseer-NMR from the Core, you have to create this folder yourself or use a previously created one, containing the peaklists *.csv fles and also the FASTA fles or of any other necessary fles. The format of the spectra/ folder is such as is created by the GUI, explained in the core/fslibs/FarseerCube.load_experiments() method docstring or in the previous section.
The CONFIG.JSON is any confguration fle saved by the GUI, with or without information describing the peaklist Experimental Tree as this information is not read when running command line. It is possible to change the calculation settings manually by editing the .json confguration fle or loading your confguration via GUI and set it up there and saving it afterwards, there is a fle with the default settings that can be used as templated, the defaulf_confg.json provided in the repository under core/. Read further on the confguration fle.

IV. NMR Parameters a) Chemical shift Diferences
Standard chemical shift diferences are calculated separately for each atom type, currently proton and nitrogen, and for each residue. Results are stored by default in new columns named 1H_delta and 15N_delta, respectively.

Related features:
• Absolute (measured) chemical shifts can be normalised to a given residue in the reference peaklist using the Chemical shift normalisation routine.
where δ H is the chemical shift (cs) diference for the proton, δ N is the chemical shift (cs) diference for the nitrogen dimension as calculated in step IV.a, and α is the normalization constant between both dimensions. By default, 0.14 for all residue types except Glycine which takes 0.2.
CSP Specific features can be confgured in the corresponding submenu (Figure 17), where: • CSP Alpha is the general value α • Show Missing Residues, is way missing residues will be displayed in the bar plots: • prev, the last calculated value is shown • full, a full bar is shown • zero, no bar is shown • α values can be setup individually for each residue type under the GUI popup menu Alpha by Residue (Figure 18). 6 April 2018 38/86

c) Intensity Ratios
Intensity ratios are calculated for the Height and Volume columns of the input peaklists, according to:

d) PRE and ΔPRE Analysis Theoretical PRE profiles
Farseer-NMR allows the input of theoretical Paramagnetic relaxation enhancement (PRE) profles to which intensity ratios can be compared. For that, it incorporates a set of routines that load and represent theoretical PRE profles into the Bar Plots. Further information on how to input a theoretical PRE profles is available in the corresponding subsection.
For the sake of organization, the practical aspects of the PRE analysis are explained in this section. To better understand the following explanation please carefully read the Results folder hierarchy section and the other sections referred.
The Theoretical PRE profles will be displayed in the Bar Plot representations of both Height and/or Volume ratio NMR parameters. As described in the axes restrictions section, paramagnetic data can only be evaluated along the Z axis. Therefore, the theoretical PRE profles are represented for the series analysed along the Z axis, that is, under the along_z/ folder (further information).
Or, in the case of the Comparative/Stacking analysis (see also folder description), the theoretical PRE profles are only represented for the stacking sets Cz/ and for the 00_para/ series subset.

PRE Analysis Δ
A complete description of the ΔPRE Analysis that is implemented in Farseer-NMR can be found in Arbesú et al. 2017.

Briefy, a ΔPRE is defned by the diference between the theoretical PRE values and the PREs (intensity ratios) observed for each data point (peaklist). A Gaussian smoothed flter is applied on top of the PRE
Δ data to facilitate the identifcation of interaction patterns.
• To activate the ΔPRE analysis, it is necessary that the calculation of Height or Volume ratios are activated.
• There are two specifc plots available to represent the calculated ΔPRE values, those are the Delta PRE plot and the Delta PRE heatmap.
The output of the ΔPRE Analysis is as previously described for the Theoretical PRE Profle representation. The folder TablesAndPlots/PRE_Analysis/ will be created for the series along_z/ folder where the ΔPRE heatmap plots will be saved.
A special case is the Delta PRE map. This plot represents the evolution of the ΔPRE, which is calculated along the Z axis, as a function of another variable, represented along X or Y, this is a typical use case of Comparative/Stacking analysis. Therefore, the ΔPRE maps will be represented only under the folder Cz/ and for Z datapoint 00_para/, it appears together with the ΔPRE heatmap plots inside the TablesAndPlots/ PRE_Analysis/ folder. 6 April 2018 40/86 Farseer-NMR Documentation -V.Other routines and Technical Details: V.Other routines and Technical Details

V. Other routines and Technical Details
This section contains information on routines available on Farseer-NMR, diferent from NMR parameter calculations, and summarises technical details that are important to consider to correctly set up a calculation run. Refer also to WET#26 for more information. 6 April 2018 42/86

a) Compatible Peaklist Formats
Farseer-NMR Documentation -V.Other routines and Technical Details: b)Load/Save and the Confguration File JSON

b) Load/Save and the Configuration File JSON
The Farseer-NMR GUI allows the user to save the current state of the confguration to an external fle that can be loaded, at any time, to fully restore the saved settings. Everything that can be confgured in Farseer-NMR GUI is saved to the confguration fle: loaded peaklists, current Sidebar state, current Experimental Tree state and all current Settings.
The confguration fle is a human-readable text JSON fle , a widely used format for data storage and transfer, especially in the world of web applications.
This fle can be confgured manually outside the GUI interface using any standard text editor. It can than be reloaded into the GUI where changes will be visible. Please consider that a JSON fle follows a very strict syntax, and manually editing of the JSON confg fle may lead to errors during the run if the user is not cautious about the fle syntax.
Every time Farseer-NMR launches a calculation, a copy of the current setup is stored inside the Calculation Output Folder under the name user_confg_DATE.json, where DATE is the current data and clock time. This backup is saved regardless of whether the user has previous saved or their confguration or not. In fact, the calculation run is executed from the backup confguration fle and not from the user saved fle.

c) Searching for missing residues along Y and Z
In the case of Paramagnetic analysis, it is likely that upon addition of the paramagnetic tag some peaks in the vicinity of the tag will disappear. Since evaluation of missing peaks takes place along the X axis, the missing peaks in the paramagnetic peaklists (when evaluating along the Z axis) would be identifed as unassigned. To avoid this, and to correctly identify these residues as missing, it is necessary to activate the search for missing residues/peaks along Z and/or Y axes, there is a dedicated fag option in the Settings tab. This procedure then performs an initial search for all the Z or Y axis series available, keeping the X axis datapoint fxed to the frst experiment.
Following this, the usual procedure of search for missing residues along X will take place, for the diamagnetic and paramagnetic series separately (for example), and the residues identifed initially will be taken into consideration, thus summing to the analysis along X and along each of the other (activated) axes.

d) Axes restrictions
Farseer-NMR loads all the peaklist data into a 5-dimensional array, which can be thought of as a cube made of 2-dimensional data points -the Farseer-NMR Cube. The X, Y and Z axes of the cube correspond to the diferent analysed experimental conditions and up to three distinct experimental conditions can be analysed simultaneously. If only one condition is analysed, the Cube is simply a vector or a set of vectors.
Farseer-NMR has been designed to enable any kind of variable to be analysed, however, some caveats apply concerning what type of analysis can be performed along these diferent axes.

Along the X axis -Data fitting
Farseer-NMR allows the ftting of biophysical parameters to continuous data, for instance the determination of afnity constants over a ligand concentration range. Further information about available data ftting routines can be found in its corresponding section.
Parameter ftting is only available along the X axis. It is possible to represent a concentration range series along Y and Z and perform all the analysis routines, however, the parameter ftting algorithms are not available for data represented by these axes.

Along the Y axis -Diferent sample constructs
Many biomolecular NMR studies involve the analysis of diferent protein constructs/mutants. A typical example would be: A series of fve ligand concentrations (L1 to L5) are probed against four diferent protein constructs/mutants (P1, P2, P3, P4), resulting in a single 5×4 face of the Farseer-NMR Cube, with ligand concentration along the x axis and the protein constructs along the y axis.
Conceptually, the two axes could be swapped and the ligand concentration could be represented along Y and the protein constructs along X. However, in order for Farseer-NMR to read FASTA fles and complete the output lists with information on the unassigned residues, this data must be put along Y axis, since FASTA fles can only be loaded for the data points of the y axis. Consequently, swapping the two axes would prevent the efective use of FASTA fles in the analysis.
FASTA fles are read only on the Y axis, but, nevertheless, Y can take any kind of variable.

Along the Z axis -Paramagnetic NMR Analysis
Paramagnetic NMR investigation of a system requires the acquisition of all data under both diamagnetic and a paramagnetic conditions. If, for example, a protein-ligand titration was performed as part of a paramagnetic NMR study, the dataset would consist of two titration series: diamagnetic and paramagnetic. The diamagnetic and paramagnetic series would ft as data points of a second axis where the concentration range would be ft on the frst axis, e.g. X axis (see above).
Farseer-NMR contains several routines specifcally for paramagnetic NMR data analysis and these routines are restricted to analysis along the Z axis. Therefore, when analysing paramagnetic NMR data, e.g. PREs, input data should be organised such that the frst point in the z axis corresponds to the diamagnetic series and the second point to the paramagnetic series.
There is an additional restriction on the names that the Z axis data points can take and that is such the diamagnetic series should be named simply "dia" while the paramagnetic simply "para".

When running without the GUI
Files should be placed under each YYY folder, that is spectra/<ZZZ>/<YYY>, together with the .csv peaklist fles.

Practical considerations
Farseer-NMR can receive diferent FASTA fles for each Y axis data point in order to evaluate a parameter's evolution for diferent mutants/constructs, for example. However, in order to perform analyses along the Y axis with diferent FASTA fles, FASTA sequences must have the same length, otherwise row numbers won't match when comparing peaklists. If no analysis is to be performed along Y, and only the analysis of several constructs is to be performed along X, there is no requirement for FASTA sequences to be the same length.

f) Chemical shift normalisation
On some occasions, chemical shifts of the whole experimental dataset need to be normalized or corrected to a given peak of the reference experiment. The Chemical Shift Normalisation routine normalises the absolute chemical shifts of each of the nuclei of the whole dataset to a given residue, according to: where r is the residue in consideration, N is the nucleus, p is the peaklist under observation in the peaklist series, res is the reference residue, and ref is the reference peaklist.
This normalisation routines is applied along the X axis and throughout the whole data set. 6 April 2018 50/86 Farseer-NMR Documentation -V.Other routines and Technical Details: g)Theoretical PRE profles

g) Theoretical PRE profiles
Theoretical PRE profles (such as those generated by Flexible-Meccano) should be given as a .pre fle where the frst column contains the residues numbers and the second column contains the PRE values. The frst line should be commented with a # character directly followed (without space) by the residue number where the paramagnetic tag was engineered, for example: The theoretical PRE profles are selected for Y axis data points in the same manner as FASTA fles from the popup menu Select theo. PRE Files under PRE Analysis submenu.

When running without the GUI
where, Y is the observable or calculated NMR parameter, S is the experimental variable (x axis), K0.5 is the half maximal constant and n the Hill coefcient.

Generated files
Fitting results are saved in two fles that are stored together with the plots and tables for that parameter: 1) a ftting log fle where all the information regarding the ftting procedure is stored (residue wise) and 2) a ftting results table (.csv fle) where the summary of the ftting with the ft parameters are stored.
Fitting results are drawn in the Parameter Evolution per Residue plot template, this required that the fag to generate this plot is activated Residue Evolution Plot → Residue Evolution.

Implementing new functions
The method FarseerSeries.perform_ft() defnes the ftting workfow inside Farseer-NMR, ftting routines are coded in the fslibs/ftting.py library. New ftting functions and routines can be implemented following the example provided in the code for the Hill ft. 6 April 2018 52/86 Farseer-NMR Documentation -V.Other routines and Technical Details: i)Sidechain Analysis

i) Sidechain Analysis
Sidechain analysis is performed in the same way as regular Backbone analysis, but the results are kept in a separated folder.
Under the submenu Sidechains select: • Are Sidechain peaks present? Use this option if there are sidechain entries in your peaklists and you want to parse them out and do not consider them in the calculation.
• Analyse Sidechains? Activate this fag if you actually want to analyse the sidechains present.

VI. Output and Data organization a) The log file
Farseer-NMR prints the progress of the run to the Terminal window showing detailed information on all the operations performed. At the end of a run, the full log is exported to an external fle written using Markdown syntax. In addition, a copy of the confguration fle is stored at the end of the log fle.
Use this fle for tracking input errors in unexpected results. Maybe a wrong FASTA sequence? Or a misleading peaklist fle name?
Moreover, when reporting errors or bugs, please provide the log fle.

b) The results folder hierarchy
The Calculation Output Folder… ... is the folder that contains the spectra/ folder (which contains all the input peaklists), is defned in the GUI as the Calculation Output Folder under the Settings tab, and is where all the Farseer-NMR generated output will be stored: 1. a copy of the user defned variables 2. a log fle

folders where results are stored
The Backbone and Sidechains Folders… ... are created in the main calculation folder and separate the results obtained for backbone atoms and those of side-chain atoms (if present). Farseer-NMR separates these two types of results because, from experience, concatenating results for backbone and side-chain atoms inside the same tables and plots results in awkward representations -both folders have the same internal hierarchy.

The Calculations folder…
... is found under the Backbone or Sidechains folders and stores the results generated for the diferent sets of series analysed along each Farseer-NMR Cube axis (condition).

The axes subfolders…
... contain the series originating from slicing the Farseer-NMR Cube along a specifc axis, each axis representing a diferent condition, where along_x, along_y and along_z, refer to X, Y and Z axis, respectively.

Folders index prefix
The experimental and logical progression of the series, and hence of the Farseer-NMR Cube, is dictated by the order the user inputs the datapoint names during the Experimental Tree setup. The Farseer-NMR Core reads this logic by considering the alphabetical order of the names along the diferent axis. Therefore, to keep alphabetical order along the axes datapoint names, a numbered prefx is added to the datapoint folder's names, starting from 00_ which is always the reference experiment to that axes/series.

The diferent series
The series generated for each axis (along_* subfolder) are hierarchically stored according to the data points fxed for each of the other two axes. Axis parent-child permutations follow the order:

Some examples:
• The analysis generated from a series of experiments (increasing ligand concentration) performed at 298K for ligand L1, will be stored under the following folder tree: Backbone/Calculations/along_x/01_298K/00_L1/.
Each of these series subfolders store the results generated from the Farseer-NMR Analysis routines. Read further on how the results are stored. 57/86

The Comparisons Folder
The Comparisons/ folder is found at the same level as the Calculations/ folder, stored under Backbone/ (or Sidechain/), and gathers the output from the Comparative/ stacking Analysis method.
This folder has an additional initial subfolder, namely Cx/, Cy/ or Cz/, these indicate that the results here stored were generated by analysing the Farseer-NMR C ube along the X, Y and Z axes, respectively. Inside, there are along_x/, along_y/ and along_z/ folders corresponding to the axes along which the comparison/stacking was performed.

Example 4:
Calculations performed along the X axis and compared/stacked along the Y axis are stored under: Backbone/Comparisons/Cx/along_y/.
Recall that each comparison is by itself a series of experiments. Therefore, in this folder hierarchy you will fnd that the series are organized in the same manner as described above for the Calculations/ folder. The Backbone/Comparisons/Cx/along_y/ structure is followed by a <preceding axis\>/<succeeding axis\>/<[results]> folder tree where series along these axes are stored. Below is a descriptive picture where, 00_r1/ is the frst data point along the X axis and 00_278K/ is the frst data point along the Z axis. 01_ratio2/ and 02_ratio3/ are other data points along X axis and 01_298K/ is the other datapoint along the Z axis. This series runs along the Y axis data points.

c) Reading the results
Inside each series folder, you will fnd diferent subfolders that organize the generated output data: tables, parsed fles and plots. These are organized in diferent categories depending on what is stored inside. Three folders exist to organize the Farseer-NMR outputs: ChimeraAttributeFiles, FullPeaklists and TablesAndPlots.

FullPeaklists folder …
… stores the parsed peaklists in comma separated fles that make up the whole series analysed. These peaklists have the same information as the originally input peaklists, plus the NMR parameters calculated during the analysis routines and, also, all the related information generated during the calculation run: 1. All peaklists are parsed to be the same length (number of rows/residues) so that they can be easily evaluated using other software.

Identifcation of unassigned and missing peaks (Proline residues included),
3. Three additional columns identifying the residue number, the 1-letter amino acid code, the 3-letter amino acid code and the Peak Status that identifes if the peak was measured, missing or unassigned.

TablesAndPlots subfolder …
… stores the plots created and the corresponding tables. One subfolder is created for each NMR parameter calculated (H1_delta, 15N_delta, CSP, Height_ratio, ...). Inside each subfolder is a fgure fle for each plotting template requested and a comma separated fle with the data used to generate those plots. See here for a the list of all available plotting templates.
There is also an observables folder that organizes the evolution of the NMR observables present in the original peaklists but isolated and parsed along the series. In this way, the user can make further representations of the evolution of the NMR observables simply by using the tables provided by Farseer-NMR.

ChimeraAttributeFiles folder …
… stores Chimera Attribute parsed fles that can be directly used in UCSF Chimera to represent NMR parameters into representation features (colours, …), and contain the calculated data for each restraint and each titration data point. 6 April 2018 59/86

d) Plotting Templates
Farseer-NMR contains a set of plotting templates that represent the calculated data in a simple, organized and publication-ready manner. There are plots that represent commonly used styles, and others that we have specifcally designed and implemented for improved data representation.
Each generated fgure represents the evolution of an NMR parameter along the whole series, either in diferent subplots (inside the same fgure) or concatenated into a single plot.
The structure of the fgures, subplot organisation in columns and rows, colours, font types and several other plotting style options are highly customisable under in the corresponding GUI menus or the JSON confguration fle.

Bar Plots
Bar plots represent the evolution of a calculated restraint in confgurable and commonly used form.
There are three bar plot templates available: compacted, extended and vertical.

General features:
• all text is customisable (font type, size and style) • X and Y ticks and scales are customisable • customisable colours for identifcation of missing, unassigned and measured bars • missing residues can be represented in three diferent manners ('full', 'prev' or 'zero') ▪ 'full', represents a full bar ▪ 'prev', represents the value of the previously measured point ▪ 'zero', represents no value • customisable bar width • identifcation of Proline residues (boolean fag) • user-defned labeling of bars • user-defned colouring of bars • a grid option • a signifcance threshold line

Compacted Bar Plot
Compacted bar plots are designed to ft a half-page width fgure in a scientifc publication and are generally drawn in an overall fgure of a columns vs rows matrix of subplots (Figures 22 and 23).

Extended Bar Plot
The extended bar plot is designed to ft a whole page width fgure in a scientifc reviewed publication and are generally drawn as overall fgures of vertically stacked subplots representing the titration evolution (Figures 29 and 30).

Specific features:
• bars individually identifed by residue labels up to 100 labels (larger proteins get progressively summarized ticks) • customisable x ticks colours 6 April 2018 63/86

Vertical Bar Plot
The vertical bar plot is designed to ft narrow spaces and column organisation styles in scientifc publications and are generally drawn as overall fgures of horizontally stacked subplots representing the titration evolution (Figures 26 and 27). 6 April 2018 64/86

Restraint Evolution
Residue evolution plots represent the evolution of a given restraint over the whole titration for individual residues. The generated fgure is amassed into one subplot for each residue in an MxN matrix. It is designed to ft a page width fgure in the Supporting Information of a scientifc manuscript. Individual plots can be cropped externally and used in specifc fgures of the main article body. Data represented in this manner also can be ft to a given equation.
• all text and labels are customisable (font type, size and style) • X and Y ticks and scales are customisable

Chemical Shift Scatter Plot
One of the most innovative plots of Farseer-NMR is the Chemical Shift Scatter plot: it translates to a plot the chemical shift evolution in two observed dimensions (generally 1 H and 15 N) for each residue, separately. The generated fgure is amassed into one subplot for each residue in an MxN matrix. It is designed to ft a page width under the Supporting Information of a scientifc manuscript. Individual plots can be cropped externally and used in specifc fgures of the main article body (Figures 30 and 31).
• all text and labels are customizable (font type, size and style) • customisable colours: • colour of gradients • colour of shapes • colour of missing data points (' residues') • customisable points styles: list of ordered shapes or colour gradient circle.
• identifcation of unassigned and missing residues • externally confgurable rules (default to 0.01 ppm) that is centred at the origin 6 April 2018 66/86  Following the idea of the Chemical Shift Scatter Plot, the Chemical Shift Scatter Flower plot amasses all that information in a single plot. The spread of the chemical shifts away from the centre resemble a fower's petals, allowing easy discrimination of afected residues and grouping of them according to their changing nature(s) (Figure 32).

The ΔPRE heatmap
See here for a complete explanation on PRE and how these results are stored. The PRE heatmap Δ Δ represents the PRE as a barcode giving a colour for each residue within a gradient where 1 is maximum Δ relaxation enhancement and 0 is no enhancement (the upper and lower limits of this gradient can be confgured). Results are better represented upon data smoothing with Gaussian flter.

VII. Tutorials
This section contains diferent tutorial exercises that will help the user to get introduced to Farseer-NMR software and to its various applicabilities. The examples presented are inspired in real cases, however, NMR observables were modifed or intentionally generated to better ft the educative purpose of the tutorials and, the original protein sequences were substituted by purely randomly generated sequences.

a) Tutorial 1 -Single variable datasets
Tutorial 1 describes the analysis of a single variable dataset, also termed 1D dataset, it can be found in folder Documentation/Tutorial_Datasets/Tutorial_1. This section focuses on the analysis of a series of NMR peaklists that represents the evolution of the system as a function of a single experimental variable -the simplest case study. For example: investigating the binding event between proteinA and proteinB where proteinA is observed by 1 H-15 N HSQC NMR and the concentration of proteinB (unlabelled) is the independent variable. We deem this kind of dataset a 1D dataset because it spans a single dimension on the Farseer-NMR Cube.

Aim
Describe the binding event between proteinA and proteinB: • Identifcation of unassigned peaks • Identifcation of missing peaks along the binding series • Calculation of Chemical Shift Perturbations (CSPs) • CSP representation for the whole proteinA along the series • CSP representations for each single proteinA's residue along the series

How to
In Documentation/Tutorial_Datasets/Tutorial_1/pkls/ you will fnd the series of peaklists .csv fles along with a proteinA.fasta fle which contains the complete proteinA construct's sequence. A .fasta fle needs to be provided for identifcation of unassigned residues.
2. Create one single point in the Y axis and name it proteinA.
3. Create seven diferent points in the X axis and name them accordingly to the concentration range. (Figure 35). 6. Drag and Drop the peaklist names from the Side bar to the "Drop peaklist here" corresponding places in the Experimental Tree (Figure 36).

Click Setup Experimental Series
7. On the Settings Tab confgure the following options: 8. The option Analysing Along X axis comes activated by default, in this tutorial there is no need to change this option. 9. Check Apply FASTA? And select the .fasta fle for proteinA. As described in the Documentation manual, fasta fles can only be selected for data points in the Y axis, that is why the Y axis codes for the protein construct observed (Figure 37 -1   13. Run Farseer-NMR! Please recall that, to avoid data overwrite the calculation won't proceed if there is already a Backbone/ and/or a spectra/ folder in the Calculation Output Folder, these folder should be moved or deleted priorly. All information regarding the run will be printed to the terminal window and stored in the farseer_log.md fle.

Results
A spectra/ folder and a Backbone/ folder are created inside the Calculation Output Folder defned in the run settings, please read the Results folder Hierarchy section for more information on how results are organized.
Inside the Backbone/ folder there is the Calculations/ folder with the following subfolder structure: Backbone/ Calculations/ along_x/ 00_298K/ 00_proteinA/ where along_x/ contains the series extracted along the X axis of the Farseer-NMR Cube. In this Tutorial the Farseer-NMR cube contains only one datapoint along the Y and Z axes and therefore there are no series to be extracted along those dimensions; this was also not defned in the settings anyway. 00_298K/ and 00_proteinA/ folders are the Z and Y fxed data points, respectively, for the X series generated, that, in this case, is only one series. Inside 00_proteinA/ folder, you will fnd the folders that organize the Farseer-NMR output for the analysed series. Further reading on these folders and how are they organized is available. You will fnd this organization for each and every single series that is analysed by Farseer-NMR. 6 April 2018 74/86

b) Tutorial 2 -Analysing 2D Datasets
Tutorial 2 describes the analysis of a dataset containing peaklists that correlate two diferent variables, protein:protein ratio gradient and diferent protein constructs, also termed 2D dataset; it can be found in folder Documentation/Tutorial_Datasets/Tutorial_2. In this case, we will perform: • Analysis along the Farseer-NMR Cube's X axis, to: • evaluate the response of the system to increasing concentration of an unlabelled partner.
• Two distinct mutants are evaluated.
• Analysis along the Y axis, to: • evaluate the experimental diferences between the two mutants for the diferent partner concentration ratio.
• A Comparative/Stacking analysis between all the series evaluated.
We advise you to try Tutorial 1 prior to this one because the most basic things regarding Farseer-NMR calculations are explained there.

Context
ProteinA interacts with ProteinH weakly provoking small chemical shift perturbations. It is suspected that residue 39 has an active role in the interaction process. To understand the role of residue 39, two mutants were prepared, Ala39 and Glu39. The two ProteinA mutants were observed by 1 H-15 N HSQC NMR in the free state and in the presence of ProteinH at two diferent concentration ratios, 1:1 and 1:2.
Because the interaction is weak, to facilitate the identifcation of the binding event, proteinH was functionalized with a paramagnetic MTSL tag, so that interaction between the two proteins results in decreasing of proteinA's signal intensity due to proximity with the paramagnetic MTSL tag. This is example is not intended to demonstrate a deep analysis of paramagnetic data, we wish to demonstrate here a simple case. A further extension to diferent sets of paramagnetic data analysis see is provided in Tutorial 3. This example can be done equally well by considering CSPs, but we have intentionally used a paramagnetic case.
variables (Z, Y and X). In cases where less than three variables are analysed, simply defne a single point in the non used axes.

c) Tutorial 3 -paramagnetic NMR analysis
Tutorial 3 explores the analysis of paramagnetic NMR data for four diferent experimental setups that have been measured in both diamagnetic and paramagnetic conditions. Please complete Tutorial 1 and Tutorial 2 before attempting this exercise. This example uses axes Y and Z but it can be easily expanded to also include the X axis. In this example, we will also make of use of two routines that are restricted to certain axis, which are analysis of diferent constructs (Y axis) and paramagnetic data (Z axis).

Context
An intrinsically disordered protein of 80 residues was mutated in position A2C and A27C, the engineered cysteine was functionalized with a MTSL paramagnetic tag with the intention of inspecting the protein's intramolecular interactions. The frst twenty residues are suspected to have an important role in these intramolecular interactions, therefore, two truncated constructs were generated from the mutant A27C: D10 and D20 where the frst ten and twenty residues were removed, respectively. Two 1 H-15 H NMR HSQC experiments were measured for each construct, a paramagnetic experiment followed by a diamagnetic reference after treatment with 5-equivalents of ascorbic acid. All experiments were acquired at 278K, which is the temperature at which peaks have highest intensity in this case. In order to understand how the dynamics of this intrinsically disordered protein deviate from a random coil model, the theoretical paramagnetic relaxation enhancements (PRE) were calculated with Flexible Meccano and used in the Farseer-NMR analysis.
5. Confgure the Farseer-NMR Run according to the following ( Figure 44): 6. In the Settings tab, activate analysis over all axes plus comparisons.
8. Select the corresponding FASTA fles for each Y axis datapoint. In this case two diferent .fasta fles are required, that corresponding to the A2C mutant and other for the A27C mutant and constructs ( Figure 45). Here we use the same .fasta for the truncated constructs because we want that those truncated residues are identifed in the plots (as unassigned residues) and because we want to compare the diferent constructs and for that computational analysis requires that all datasets have the same number of rows (residues) so that data tables (peaklists) can be compared. 9. Activate the calculation of Height ratios under Parameter Calculation.
10. When activating Height or Volume Ratios the PRE Analysis box becomes active allowing the user to select ΔPRE analysis. Activate the three PRE Analysis checkboxes. This activates the analysis itself (Do DPRE Analysis) and the generation of the DPRE map and the DPRE heatmap.
11. The DPRE Analysis requires that information on theoretical PRE profles are also input. A fle containing the theoretical PRE should be selected for each Y axis data point, this is done in the same way as for the .fasta fles. Use the menu Select theo. PRE Files to select the corresponding .pre fles ( Figure 46).
12. Activate the Compacted Bar Plot representation (is the best suited for this example).
13. Run Farseer-NMR! Please recall that, to avoid data overwrite the calculation won't proceed if there is already a Backbone/ and/or a spectra/ folder in the Calculation Output Folder, these folder should be moved or deleted priorly. All information regarding the run will be printed to the terminal window and stored in the farseer_log.md fle.

Results
Farseer-NMR analysis along the Y axis and the Z axis occur as described in the previous examples (Tutorial 1 and Tutorial 2 results sections) for X and Y. You can fnd those in Backbone/Calculations/along_y/ and along_z/.
Before continuing, please consider reading the PRE and DPRE explanatory section.
However, there is an addition to the analysis along the Z axis (along_z/ folder). The theoretical PRE profles appear for the Height and/or Volume ratio parameters in the subplots for the paramagnetic data point (TableAndPlots/ folder). Because the frst subplot is always evaluated against itself, the diamagnetic subplot of Height ratio yields 1 for every residue (Figure 47).
The folder PRE_Analysis/ (under along_z/) contains the plots and representations that are specifc for this analysis. Read further on the Delta PRE analysis.
In the example presented in this tutorial, we can reap considerable benefts from the Comparison/Stacking routines. For example, what if we wanted to observe, in a single fgure, the changes in PRE as a function of the protein construct. You can access this plot under: Backbone/Comparisons/Cz/along_y/00_278K/01_para/TablesAndPlots/Height_ratio/ The stacking routine gathers all plots generated along_z for the diferent Y datapoints in a single fgure. The same could be applied along the X axis, for example to visualize the evolution of PRE profles as a function of a ligand concentration.
Following on from the above, of the PRE Analysis routines, the DPRE Map is a special case. This map is a representation of the ΔPRE profles along the evolution of another variable and, therefore, it can only be represented in a Stacking analysis. To fnd this plot go to: Backbone/Comparisons/Cz/along_y/00_278K/01_para/TablesAndPlots/PRE_analysis/ it won't show for the diamagnetic (00_dia/) series for obvious reasons. 6     The datapoint corresponding to the paramagnetic data represents the input theoretical PRE profle. While the diamagnetic is a division over the self yielding 1.