Flow objects ============ .. role:: javascript(code) :language: javascript :class: highlight The cornerstone of EasyNMR is the flow objects that may be connected to give a specific functionality. There are more than 15 flow object types, and less than 10 flow transfer types. These numbers will increase as the functionality of EasyNMR is expanded. The description and function of flow objects are provided below. .. Comment here .. todo:: Yxy - first xxx - sedond yyy Data objects ------------ Data objects store and carry scientific data, tables, and molecules as described below. Scientific data ............... .. image:: images/objects/csdm.png :width: 100 EasyNMR stores scientific data in *Data* objects using the `Core Scientific Data Model (CSDM) `_. CSDM provides a lightweight, portable and self-contained model and file format for multi-dimensional scientific data. The CSDM object specifies the dimensions in the Dimensions pane and the dependent variables (data) residing on the grid specified by the dimensions are shown in the Dependent variables pane. All scientific data that is uploaded to EasyNMR or dropped onto the flow window is automatically transformed to CSDM on load. See the In- and output section below for compatible file formats. If you have any wishes for support to other file formats, please reach out to us via `email `_. See our publication on the CSDM in `PLOS ONE `_. Furthermore, there is a nice `Python CSDM library `_, and CSDM is fully supported by the `RMN `_, `SIMPSON `_, and `DMFit `_ software packages. .. admonition:: In- and output :Anchors: :csdm: The scientific data is output from the anchor in the CSDM format. :File types: :Bruker: Bruker spectra are recognised as folders containing a fid or ser file and a pdata folder. :Agilent: Agilent spectra are recognised as folders with .fid extension and contain a file named fid. :CSDM: CSDM files are recognised as JSON files with file extension .csdf or .csdfe. :ChemDraw: ChemDraw XML files that contain predicted spectra are recognised by their extension .cdxml. :SIMPSON: SIMPSON files have the extension .spe or .fid. :DPS: File format of the Bruker MiniSpec TD-NMR, with extension .dps. Table ..... .. image:: images/objects/table.png :width: 100 The *Table* object stores tables of data. In the table pane, you can view and sort the content of a Table object. To create a table, either load an Excel or CSV file, or use the *Calculator* object. The Import pane provides options for importing Excel and CSV files. For example, if your table has a title row, check *Has title row*; or if the elements of the table are separated by comma, write a comma in the *Separator* editbox. .. admonition:: In- and output :Anchors: :table: The table input allows to present output from e.g. calculator object in tabular format. The output anchor emits the table to another object. :File types: :Excel: Excel files have the extension .xls or .xlsx. :CSV: Files with comma-separated values have the extension .csv. Text .... .. image:: images/objects/text.png :width: 100 The *Text* object allows adding rich text to your project. You can use this module to add descriptions or write notes. The text is visible in the Text pane of description. To modify the text, click on Control to expand the Control pane, and then click Edit. Now you can change the text, remember to save by clicking the disk icon. To exit the edit mode, click Done in the Control pane. After you apply changes, the written text will appear in the Text pane and hides the editor. .. admonition:: In- and output :File types: :Text: Text files have the extension .txt. Molecule ........ .. image:: images/objects/mol.png :width: 100 The *Molecule* object loads molecules from PDB or CIF files. For CIF files, it is possible to expand the unit cell using the text input of the Molecule pane. The Database pane offers the possibility to directly download an entry from the protein database. .. admonition:: In- and output :Anchors: :mol: The mol anchor outputs the molecule for other objects. :File types: :PDB: PDB files have the extension .pdb. :CIF: CIF files have the extension .cif. :MOL: *ToDo:* Files of the type MOL have extension .mol. :XYZ: *ToDo:* XYZ files have the extension .xyz. Function objects ---------------- Function objects add functionality or calculations to NMR data as described below. Calculator .......... .. image:: images/objects/calc.png :width: 100 The *Calculator* object takes any input through the in (data) and par anchors and makes this data available as input for a JavaScript operation. The JavaScript code should generate an output that is sent to the out anchor. The Control pane shows the various inputs available along with their ID's. Furthermore this pane allows configuration of the output type of the object. Optionally, choose to add a an empty output with the right format by clicking "Add empty output". The Calculation pane contains the JavaScript code for generating the output. Any input is available as part of the :javascript:`input` variable with the ID as its key. By default, the *Calculator* object makes the output a copy of the first input, e.g. .. code-block:: javascript output = input.WfeGwi; If you had chosen to create an empty output, the default code would be .. code-block:: javascript :linenos: var np = 128; output = { version: "1.0", dimensions: [{ type: "linear", quantity_name: "frequency", count: np, complex_fft: true, increment: "1 Hz", label: "1H", application: { easy: {nucleus: "1H"} } }], dependent_variables: [{ type: "internal", numeric_type: "float32", quantity_type: "scalar", components: [ new Float32Array(np) ] }] } In general, any JavaScript operation can be used, as long as the JavaScript code defines the variable :javascript:`output` in the right format. If you use asynchronous code relying on JavaScript promises, you can also define the output to be such a promise that returns the output data on fulfill. For example, if we want to receive data from a web site, this could look like .. code-block:: javascript :linenos: :emphasize-lines: 2,8 var csdm = input.WfeGwi; output = new Promise(fulfill => { fetch('https://weather.data/somedata') .then(res => res.json()) .then(data => { // Assuming that the data object contains an array named arrayed_data csdm.dependent_variables[0].components[0] = data.arrayed_data; fulfill(csdm); }); }); .. admonition:: In- and output :Anchors: :in: A data input anchor to receive CSDM, table, or molecule data. :par: *ToDo:* The par anchor can receive and emit various parameters recognized and established by the *parameter* object. :out: The output from the calculation is forwarded to this anchor. .. _Simulation: Simulation .......... .. image:: images/objects/simulation.png :width: 100 .. include:: simulation.rst .. admonition:: In- and output :Anchors: :par: *ToDo:* The par anchor can receive and emit various parameters recognized and established by the *parameter* object. :data: Anchor to receive generic data that will be transmitted to the server as a file with the name is listed in the Data pane. :spins: *ToDo:* Receive a spin system from e.g. a *SIMMOL* object. :csdm: The resulting spectrum of the simulation is output in the CSDM format. :File types: :SIMPSON: SIMPSON input files have the extension .in and are opened using this object. Model ..... .. image:: images/objects/model.png :width: 100 .. include:: model.rst .. admonition:: In- and output :Anchors: :csdm: The experimental data to be modelled are sent to the object through this anchor. :par: *ToDo:* The par anchor can receive and emit various parameters recognized and established by the *parameter* object. These parameters are defined as *global* parameters. :out: The resulting spectra of the simulation is output in the CSDM format. .. _Eserver: eServer ....... .. image:: images/objects/eserver.png :width: 100 The *eServer* object (short for EasyNMR Server) allows signing in to the backend server. This is in general not required to use EasyNMR, except for a few functionalities requiring access to the backend server. These functionalities include - Running SIMPSON simulations using the :ref:`Simulation object ` - Performing automatic peak picking in the :ref:`Plot object ` using the NMRGlue peak picker Without eServer access, these functions will not be available in EasyNMR. The eServer uses `ORCID `_ for authentication. When pushing the Login button, you are directed to ORCID. EasyNMR only asks for permission to authenticate, not to modify anything in your ORCID account, so it should be safe to authorize EasyNMR to use ORCID to authenticate. After successfully logging in, you see the server you are connected to (e.g. easynmr.nmrbox.org), its status, your name, your ORCID identification, and the capabilities available with the server. You can log out from the server by pressing the Log out button. The Lost files pane displays any files from simulations not transferred to your EasyNMR workspace, e.g. if your computer lost its connection to the server during a simulation. Such files may either be loaded or removed. The Share workflow pane allows you to upload the current EasyNMR workflow to the eServer and obtain a unique link to the workflow for easy sharing. The Administration pane is only for EasyNMR system administrators. SIMMOL ...... .. image:: images/objects/simmol.png :width: 100 .. include:: simmol.rst .. admonition:: In- and output :Anchors: :mol: The object receives a molecule from another object through this anchor. :spins: *ToDo:* The par anchor can receive and emit various parameters recognized and established by the *parameter* object. These parameters are defined as *global* parameters. Trace ..... .. image:: images/objects/trace.png :width: 100 The function of the *Trace* object is to extract cross sections of multidimensional scientific data. Currently, it only supports 2D input and 1D output, but in principle, you could also imagine taking a 2D cross section of a 5D dataset. That will come later. The Trace/Projection pane allows selection of the desired type of trace. You can select if the trace should be horizontal or vertical, and if it should be just a trace or an integral region. Regions/traces can be specified either as points (e.g. "1 pt"), quantities (e.g. "1200 Hz"), or ppm if available (e.g. "12.01 ppm"). If there are two dependent variables in the dataset, there will also be the option to obtain the ratio between the two datasets - this is very relevant for processing of REDOR NMR experiments. The output will be a 1D dataset, where the dimension will be a copy of the first dimension of the 2D input dataset for horizontal traces and the second dimension for vertical traces. .. admonition:: In- and output :Anchors: :in: The 2D spectrum from which a trace/integral should be extracted is sent to this anchor. :out: The resulting 1D trace/integral of the simulation is output in the CSDM format. .. _Plot: Plot .... .. image:: images/objects/plotly.png :width: 100 .. include:: plot.rst .. admonition:: In- and output :Anchors: :csdm: The scientific data to plot are submitted to the object through this anchor. Auxiliary objects ----------------- File .... .. image:: images/objects/file.png :width: 100 The *File* object allows you to download a copy of NMR data in the CSDM format or to save a table object as an Excel file. To save data as a file click on the file icon in the Toolbar to create a File object. Drag the File object to the desired place in the project view. Only certain components can be connected to the File object. Compatible objects include: Scientific Data (CSDM), Table, and SIMPSON. To connect the File object to a compatible component, click on the connect icon and then on the anchor of the newly created File object. Anchors of other compatible components will blink. Click on the component of your choice. Components already connected to the File component will not blink. .. admonition:: In- and output :Anchors: :data: Data of any kind (see above for limitations) will be available for download. Configuration ............. .. image:: images/objects/config.png :width: 100 The *Configuration* object displays and edits default preferences used by EasyNMR. For example, when a new Scientific Data is added to the Workflow, a new *Plot* object is added and connects to the new data object. .. figure:: images/easynmr_config.jpg :align: center :width: 400 Default object behavior in the Configuration object. Transient objects ----------------- Transient objects are part of the Workflow that are produced if required, but will not be a permanent part of it, for example when exporting it. Folder ...... .. image:: images/objects/folder.png :width: 100 Drag and dropping a folder containing several NMR data sets creates a *Folder* object from which you can extract individual 1D/2D spectra as Scientific Data (CSDM) objects. The Object Properties of Folder shows all NMR spectra contained and text files in the folder. Press on Extract to create a data object from a specific processed experiment. .. figure:: images/easynmr_folder_glycine.jpg :align: center :width: 500 List of NMR experiments in a Folder. Archive ....... .. image:: images/objects/archive.png :width: 100 Drag and dropping an archive (for example, a zipped file) containing several NMR data sets creates an *Archive* object. In the Object Properties of an archive object, you can see a list of experiments and extract the ones you are interested in as Scientific Data objects. .. note:: Always click on the connect icon to deactivate the connect tool after connecting the desired objects. .. tip:: You can change the position of the anchor the left and right of an icon by clicking on the Anchors pane of File Object Properties. .. tip:: For each object, you can see relevant help by clicking on the *Documentation* pane to expand it in the Object Properties window.