(1) Getting started - making a new project

Start R_start

enviMass organizes data inputs and tasks into projects. Each such project can contain its own inputs and settings and can be copied to other file locations. To set up a new project, first start the workflow user interface (UI) by opening the R console and executing the commands:

library(enviMass)
webMass()

After some loading, the enviMass startup UI appears. Its sidebar (shown to the right) allows you to set up a new project: specify a path to a folder that will contain the project (the project directory) and specify a name for your project. After pressing the Start button, the project directory should now contain a folder with the project name. This folder contains several subfolders and a file called logfile.emp. The latter keeps track of your project and must not be modified.

To erase a project, simply delete the folder with the project name. To copy a project to a different location, you must copy the full project folder. Given the size of LC-MS files, make sure the project directory has plenty of space and can be written to.

(2) Open an existing project

Windows explorer start

The left sidebar of the enviMass startup UI also allows to open an existing project in two ways. On the one hand, you can specify the path to the project folder (i.e., not only the project directory. In windows, you can simply browse to the project folder and copy&paste the path as shown on the right). Alternatively, you can browse via the button logfile select to the project folder and select the logfile.emp. In both cases, press Open after you made a project selection.

If you open a project which was generated with an older enviMass version with a newer version, the project will automatically be updated while opening. For some updates and for large projects, such updating may take a few moments.

(3) Workflow control

Workflow

Once you have opened a project, the enviMass workflow UI appears. It consists of a sidebar and several main tabs.

The sidebar displays the project name, the current workflow state, a table with a workflow task overview (which changes between running a calculation and being outside a calculation session) and several buttons. Of these, the button Check project allows you to check your project for consistency; it can be pressed at any time outside a calculation session. In turn, the button Calculate initiates a calculation session, which depends on the changes, workflow selections and data inputs that you have introduced to your project since the last (if any) calculation session.

A calculation session is indicated by a calculation message; do not interrupt until finished. If you nonetheless intend to, press Esc in the R console, whereupon the browser UI turns gray and the R command prompt reappears. You should be able to start enviMass anew, open the project and resume calculations later. Similarly, any eventual breakdowns of the workflow will also lead to a gray browser UI. Don`t panic. Again, press Esc in the R console and resume - or contact us.

Two more buttons allow you to return to the enviMass startup UI (Back) from where you can open other projects or shut the UI down (Exit).

(4) Workflow tabs

Workflow enviMass organizes workflow contents into tabs, which appear to the right of the UI control sidebar. From data inputs to result outputs, the tabs are:
  • Files. This tab enables you to load LC-MS measurement files into your project. This is further covered later on in a → data input tutorial.
  • Compounds. This tab enables you to upload compounds. This is also covered in the → data input tutorials.
  • Workflow options. The Workflow options tab shown to the right allows you to specify which calculation nodes are to be included in your workflow by changing, e.g., Include? among the different node sections. Having made your selections, you must press the button Apply to make them permanent and to have them included in the next calculation session. Some intial workflow node sections, such as Peak picking, are included per default. It is wise to start with a small selection, foremost the one for compound screening. This allows you to check if expected compound masses are picked and sucessfully screened; it also allows first estimates on the mass accuracy and retention time tolerances of your measurements; you may check the → topic on quality control later on.
  • Settings. Parameters must be specified for most of the selected workflow nodes, adapted to the experimental setup, measurements and needs of a project. These settings are detailed in the different → topics for the individual nodes. As with the selection of workflow nodes, parameter changes are only activated after clicking on the Apply button!
  • Calibration. This tab can be used to define calibration models for quantification, as defined in a → topic on calibration.
  • Results. Depending on your selected workflow nodes, a variety of results are available after each calculation session:
    • Data viewer. For each file, the tab enables you to interactively view both the raw data and picked peaks as well as extracted ion chromatograms (EICs) for which peaks have been picked.
    • Quality control. Contains comparative distributions of file properties. See → topic on quality control.
    • Processing. This tab displays results on the preprocessing and filtering for each selected file, e.g., for the → mass recalibration or → LOD estimation.
    • Screening and quantification. As the tab name says; further covered in the → topic on calibration and the one → on screening.
    • Profiles. This tab lists results on profiling and trend detection, spread over several subtabs described in the → topic on profiles.
  • Help & About

(5) IDs

Workflow

Data inputs and most results are managed by assignment of IDs. For example, IDs are automatically assigned to files and need to be specified for all compounds by the workflow user. In turn, IDs are also assigned to the chromatograms extracted from a file and in turn to the peaks picked from these chromatograms. Extracted trend profiles are also distinguished by IDs, which can change over the course of different calculation sessions if new input data has been included or settings changed. As a consequence, search and comparison of data and results among different workflow tabs are all handled via such IDs.

→ Next: load data into a project.