User Guide
The first step for new ExiFRET users is to get familiar with the parameters in the input file. The following is description of all input parameters and their dependencies. Some of the parameters are inter-related and some of them are only used for particular cases. The parameters are grouped into external coordinate generation , internal coordinates and parameters related to the FRET experiment . The input parameters for some specific examples can be found here. Below you will also find information on how to use ExiFRET with user defined coordinates and a description of the output .
Input Parameters
Users should first choose to either use externally, or internally generated fluorophore coordinatesexternal coordinate generation
| Parameter | Datatype | Value | Description | Dependencies |
| user coordinates | logical | true or false | if user coordinates is true, the coordinates for the fluorophores are read from an input file provided by the user. if user coordinates is false the coordinates are randomly generated by the program according to the internal coordinate generation parameters. See also user provided coordinates | if user coordinates = true, the user needs to provide a file with the coordinates of the fluorophores |
internal coordinate generation
| Parameter | Datatype | Value | Description | Dependencies |
| System dimension | integer | 2 or 3 | the dimension of the system. fluorophores are arranged in either 2D or 3D | if user coordinates = true, system dimensions will be ignored. if oligomers is true system dimension needs to be 2. if clusters is true system dimension needs to be 2 |
| oligomers | logical | true or false | used to simulate a system with a single hexagonally packed nmer |
If oligomers is true n_densities needs to be 1 If oligomers is true n_particles needs to be 1 If oligomers is true system dimension needs to be 2 If oliogomers is true nmer_size needs to be less than 15 oligomers and clusters cannot be true at the same time, oligomers and clusters cannot be true at the same time. If oligomers is true n_particles needs to be 0.0 |
| nmers size | integer | >=1 | fluorophores are assumed to part of n-mer structures, in which n fluorophores are linked in regular geometrical arrangement. For n=1 individual fluorophores are distributed randomly. For n=2 fluorophores are linked in pairs with a specific separation. For n=> 3 fluorophores are distributed on the radius of either a circle (for system dimensions 2 or 3) or a sphere ( for system dimension 3). See also examples |
If da stoichiometry is true nmer_size needs to be 2 or more. if da_stoichiometry is true, d_per_nmer + a_per_nmer need to add up to nmer_size. If oliogomers is true nmer_size needs to be less than 15 |
| da stoichiometry | logical | true or false | To specify a specific stoichiometry of donors and acceptors within an nmer | if da_stoichiometry is true P_donor will be ignored if da_stoichiometry is true nmer_size needs to be 2 or more if da_stoichiometry is true, d_per_nmer + a_per_nmer need to and add up to nmer size |
| d per nmer | integer | >= 1 | number of donors in each nmer | d per nmer is only used if da_stoichiometry is true, d per nmer and a per nmer need to add up to nmer size |
| a per nmer | integer | >= 1 | number of acceptors in each nmer | a per nmer is only used if da_stoichiometry is true, d per nmer and a per nmer need to add up to nmer size |
| da separate | logical | true or false | if da separate = true each nmer contains only donors or only acceptors. ie only inter-nmer FRET can arise. | da separate and oligomers cannot be true at the same time da_stoichiometry and da_separate cannot be true at the same time if da_separate is true, nmer_size needs to be 2 or more |
| n densities | integer | >= 1 | number of densities to calculate FRET for, used to calculate the intervals between density max and density min | If oligomers is true n_densities needs to be 1 if n_densities is 1, the minimum density is used if n densities > 1, density_min and density_max cannot be equal |
| density min | integer | >0, format 4.97e-5 | minimum density at which to distribute nmers, in units of nmers per square angstrom in 2D and per cubic angstrom in 3D. In 3D 6.023e-7 is equivalent to 1 mM | density_min cannot be larger than density_max, if n densities > 1, density_min and density_max cannot be equal, if n_densities is 1, the minimum density is used | density max | integer | >0, format 4.97e-5 | maximum density at which to distribute nmers | density_min cannot be larger than density_max, if n densities > 1, density_min and density_max cannot be equal |
| n radius | integer | >= 1 | number of nmer radii to calculate FRET for, used to calculate the intervals between radius min and radius max. The radius can be thought of as that of the host protein to which probes are attached | if n_radius is 1, the minimum radius is used |
| radius min | integer | > 0 | minimum if n_radius is > 1, radius_min and radius_max cannot be equal radius of nmer to calculate FRET for |
radius min cannot be larger than radius max |
| radius max | integer | > 0 | if n_radius is > 1, radius_min and radius_max cannot be equal maximum radius of nmer to calculate FRET for |
radius max cannot be less than radius min |
| second radius | logcial | true or false | if second radius = true the program defines two radii for the nmers: inner and outer radius. The inner radius is used to define the size of the nmer to calculate FRET efficiency. The outer radius is used to avoid overlapping nmers when assigning coordinates for the fluorophores. In practical situations the inner radius relates to the size of the host protein while the outer radius corresponds to the radius of the host with attached probes. the radius given in the input file is the outer radius. the inner radius is defined as inner radius = radius – radius difference | if second radius = false, radius diff is ignored |
| radius diff | integer | > 0 | difference between inner and outer radius | for radius diff to be used, second radius needs to be true |
| avoid overlap | logical | true or false | determines if nmers are allowed to overlap when assigning the coordinates of the fluorophores. if avoid overlap = true, overlaps are avoided | |
| planar nmers | logical | true or false | decides if the nmers are planar or spherical in 3D only | if system dimension = 2, planar nmers is ignored |
| clusters | logical | true or false | determines if the nmers are distributed randomly in space or in clusters. If clusters = true, the fluorophores are arranged in local regions with high density. The clusters are themselves arranged randomly in 2D. The nmers are distributed randomly inside each cluster. see also: examples | oligomers and clusters cannot be true at the same time if clusters is true system_dimension needs to be 2. if clusters is true, n_particles should be larger than n_clusters |
| n clusters | integer | >= 1 | number of clusters | if clusters is true, n_particles should be larger than n_clusters |
FRET calculation parameters:
| Parameter | Datatype | Value | Description | Dependencies |
| R0 | integer | > 0 | characteristic (Forster) distance for the donor-acceptor pair (in Angstroms) | |
| n particles | integer | >=1 | number of nmers in the simulation system. Important: the number of particles refers to the number of nmers, not fluorophores ie if n particles = 500 and nmer size = 5 the total number of fluorophores is equal to 2500 | if clusters is true, n_particles should be larger than n_clusters. If oligomers is true n_particles needs to be 1 |
| n configurations | logical | >=1 | number of configurations to use to calculate an average FRET efficiency value. Each configuration is an independent geometrical arrangement of fluorophores | |
| P donor | real number | 0.0 - 1.0 | Probability of any fluorophore being a donor, determines the ratio of donors and acceptors in the system. Note that the ratio within a given nmer is not adhering to P donor but is assigned randomly. P donor refers to the overall system wide ratio of donors and acceptors. | if da_stoichiometry is true P_donor will be ignored |
| labelling efficiency | real number | 0.01 - 1.0 | to examine how the FRET efficiency varies according to the labeling efficiency achieved in an experiment. if labelling efficiency is less than 1, randomly selected fluorophores will be assigned to be empty sites which are ignored for the calculation of FRET efficiency eg if labelling efficiency = 0.9, 10 % of all fluorophores will be empty sites. see also: examples | |
| n photons | integer | >= 1 | number of photons used to determine FRET for each configuration. photons are used to model the incoming radiation, representing a discrete series of photons that cause the excitation of the donors | |
| buffer size | real number | >0 | defines the buffer region to avoid boundary effect caused by having a finite-sized simulation system. Energy released from donors in the buffer region are not included in the calculation of FRET efficiency | If oligomers is true buffer size needs to be 0.0 | `
| irradiance | real number | >0, format 4.97e-5 | irradiance of illuminating laser in W/ m2 (default 1x10e-15 to represent a very low power laser) | wavelength | integer | > 0 | wavelength of illuminating laser in nm | extinction coefficient | integer | > 0 | extinction coefficient of donor in cm-1 M-1 |
| donor lifetime | real number | > 0 | donor fluorescence lifetime in the absence of the acceptor in ns | |
| acceptor lifetime | real number | > 0 | acceptor fluorescence lifetime |
User defined coordinates
Format of user_coords.in file The program allows the user to provide the coordinates for the fluorophores in the form of an input file that will be uploaded to the server. The file needs to have to following format.x-coordinate y-coordinate z-coordinate fluorophore type
Fluorophore type defines if the fluorophore is a donor or acceptor where 1 = donor and 0 = acceptor. For a system in 2D the z coordinates are simply put to 0.00 for each fluorophore. The position and type of each fluorophore needs to be on a separate line and the file should not contain any empty lines ie if there are 20 fluorophors the file needs to exactly 20 lines plus a carriage return at the end of the last line. The field deliminator is a space, no comma is required.
Also note that the number of fluorophores refers to the total number of fluorophores in the system and not the number of nmers. nmers have no meaning with externally defined coordinates.
The following is an example of an input file for a simulation with 4 donors and 2 acceptors, arranged in 3 dimensions.
| 419.223 | -117.915 | 53.095 | 0 |
| 398.690 | -95.318 | 96.294 | 1 |
| 189.152 | -32.108 | -269.265 | 1 |
| 155.281 | -104.026 | -215.968 | 0 |
| 144.843 | 35.586 | -241.324 | 1 |
| -71.356 | -31.651 | -338.035 | 1 |