Contents

The following text styling is applied in this document. Commands, paths or filenames are denoted by: command, or path\filename.ext. Buttons in the graphical user interface are shown as [Button]. Keys on the keyboard are denoted by [Key]. A parameter to be set is denoted by parameter, and a value of a parameter or an option in a menu is denoted by option.

Install and startup

Quick start

• On Windows computers with Matlab you can usually just move the folder CC to your preferred destination and start the program by double click on the Chrombox C.exe file.
• Follow the instructions below if you install on a Mac or Linux computer, or if you install the program on a network drive.

Windows computers

• Download the installation and unzip the archive cc.zip
• Move folder CC to the preferred destination, e.g. C:\CHROMBOX\. This will be the C-root folder
• If Installed on a local disk or on a memory stick Chrombox C can usually be started by using the "Chrombox C.exe" file in the C-root folder.

If installed on a server you may have to use one of the methods described below:

• Find the file cstart.m in the folder …\cc\various and move it to somewhere in your Mathlab path. This is the only file that needs to be in the Matlab path. Possible destinations may be found by starting Matlab and typing path.
• Open the cstart.m and edit the last line after the run command so that it points to the file cc_startscript (see example below).
• You should now be able to start Chrombox C by typing cstart in the Matlab command window.

An example of cstart.m is shown below:

xxxxxxxxxx
% Startupscript for Chrombox C
% Starts startscript by the run command.
% Startscript must be located in the C root, 
% dstart must be in the matlab searchpath
% run c:\CC\cc_startscript
​
run C:\CHROMBOX\CC\cc_startscript

You can also create a desktop shortcut by copying the shortcut to Matlab and adding the following to the destination /automation /r cstart An example of how it can look is shown below:

C:\MATLAB6p5\bin\win32\matlab.exe /automation /r cstart

Mac computers (OS X)

• Download the installation and unzip the archive cc.zip

• Move the folder CC to the preferred destination, for example /Users/yourname/Documents/CHROMBOX/CC, This will be the C-root folder

• The shell script macstart_c.command stored in the C-root folder can be used to start the program if the file is executable and Matlab can be started with the terminal command ./matlab. Note that the extension .command may be hidden in Finder.

• To check if Matlab can executed by ./matlab open the terminal and type ./matlab. If Matlab does not start you can do the following:

  • Put a symbolic link to Matlab in your path by opening the terminal and typing sudo ln -s /Applications/MATLAB_RXXXXx.app/bin/matlab /usr/local/bin where RXXXXx should be replaced by the Matlab version number, for example "R2017a". Alternatively, open Applications in Finder. Locate Matlab, right-click and select Show Package Contents. Open the folder bin and locate the application file matlab. In terminal type sudo ln -s without pressing enter. Thereafter drag the matlab application file to the terminal. Ensure there is a space between "-s" and "/Applications" and press enter.

• To make macstart_c.command executable, do the following:

• Open the terminal. Use cd to change directory to the C root where the macstart_c.command is located or open the terminal at the C root folder if that is an option. Type chmod +x macstart_c.command. Alternatively, type chmod +x without pressing enter and drag the macstart_c.command file from Finder to the terminal. Ensure there is a space between "+x" and "macstart_c.command" and press enter.

• Thereafter double-click on macstart_c.command in Finder to start the program. Depending on your security settings you may get the following message: "macstart_c.command can’t be opened because it is from an unidentified developer". To solve this, open System Preferences – Security and Privacy – General and press [Open anyway] next to the message regarding the file. An alternative way of allowing the file to be executed is to open the file in TextEdit and saving it again. Then it will no longer have status as downloaded from the Internet.

As an alternative to the above procedure, Chrombox C can be started by the following method:

• Find the file cstart.m in the folder …/cc/various and move it to somewhere in your Matlab path. Possible destinations may be found by starting Matlab and typing path.
• Open the cstart.m and edit the last line after the run command so that it points to the file cc_startscript (see example below).
• You should now be able to start Chrombox C by typing cstart in the Matlab command window.

An example of cstart.m is shown below:

xxxxxxxxxx
% Startupscript for Chrombox C
% Starts startscript by the run command.
% Startscript must be located in the C root,
% cstart must be in the matlab search path
% run C:\CC\cc_startscript
​
run /Users/yourname/Documents/CHROMBOX/CC/cc_startscript.m

Linux computers

• Download the installation and unzip the archive cc.zip

• Move folder CC to the preferred destination, for example /home/yourname/CHROMBOX/CC, This will be the C-root folder

• The shell scripts linstart_c.sh stored in the C-root folder can be used to start the program, if the file is executable and Matlab can be started with the terminal command matlab.

• On Ubuntu you can use the following procedure to make linstart_c executable:

  • Right-click on the file and select Properties. Select Permissions and Allow executing file as program.

• It should now be possible to start Chrombox C by double-click on linstart_c.sh and selecting the option run in terminal. If you don’t get the run in terminal option while double-clicking the file you will have to edit the preferences in the file manager. Choose Edit in the menu for Files, thereafter Preferences and select the Behaviour tab. Select Ask each time as the option for executable text files.

• There is also a file linstart_c_term.sh in the C-root folder. The difference between linstart_c and linstart_c_term is that linstart_c runs the application disconnected from the terminal while linstart_c_term runs in the terminal. Chrombox C will continue to run if you close the terminal if it was initiated by linstart_c, while it will close together with the terminal if it was initiated by linstart_c_term.

As an alternative to the above procedure you can also start Chrombox C by cstart.m as described for Mac computers above.

Starting Chrombox C from the Matlab desktop (on all systems)

On all operating systems you can use the following procedure to start Chrombox C.

• Start Matlab in the regular way, so that the Matlab desktop is opened.

• Change the current working directory of Matlab to the C-root folder, either by the line showing the working directory or by browsing in the panel in the left side of the Matlab desktop.

• You can now start Chrombox C by one of the following methods:

  • Select cc_startscript.m in the panel showing the contents of the working directory, right-click and select run.
  • type run cc_startscript in the Matlab command window.

In a minimized Matlab session (running in terminal without Matlab desktop) you can use the cd command to set the working directory and run cc_startscript to start the program.

Changing settings

• The program should normally start without the need to change any settings. But you may want to adjust parameters such as window size. These are specified in the cc_localsettings file in the C-root folder.
• Open cc_localsettings (.sdv or .csv) in an editor such as Notepad and edit the paths for raw data, etc, if necessary.
• An example of “cc_localsettings” is shown below. Parts to check or edit are shown in blue.

xxxxxxxxxx
defaultfolders; 1; Overrides path settings with default values (cc_root\rawdata,export,libraries,method,reports,results)
defaultmethod; Default; Method to load on startup
path_export; I:\INSTALL_C\CC\export; Folder for exported data
path_libraries; I:\INSTALL_C\CC\libraries; Folder for retention index libraries
path_method; I:\INSTALL_C\CC\methods; Folder for methods
path_qqres; O:\CHROMBOX\QQ\results; Folder for Chrombox Q results (For generation of libraries)
path_rawdata; I:\INSTALL_C\CC\rawdata; Folder for rawdata folders (Chemstation, TXT, ASC, CSV, RAX, etc)
path_reports; I:\INSTALL_C\CC\reports; Folder for reports
path_results; I:\INSTALL_C\CC\results; Folder for results files
path_templates; I:\INSTALL_C\CC\templates; Folder for retention index templates
tracker; 0; For development purposes, 0 or 1
version; C-19-03; Code version to use
windowpos; [ 0.05 0.06 0.9 0.9]; Window position and size [leftposition lowerposition width height] in fractions of screen size

• windowpos is position of the window in fractions of the screen size. The two first numbers in the vector is the position of the lower left corner. As specified above the lower left corner is 10% from the bottom of the screen and 10% from the left. The height and width is 75% of the screen size. Ensure that the sums of numbers 1 and 3 and numbers 2 and 4 are less than 1.
• If defaultfolders is set to 1 the program will use the standard setup for subfolders and it is not necessary to edit the paths even if they are not correct. If the parameter is set to 1 you will have to specify the location of each path for data and methods. Data can be read from other folders than the ones are specified. Folders can also be changed by using the [Settings] option within the program.
• version refers to the current version of the code. The parameter can also be updated from within the program.
• If you have created a method that you want to import on startup you specify this as defaultmethod.

Updating

• Download the new version from www.chrombox.org/C
• Unzip the archive with the new code.
• The folder containing the code, e.g. C-19-03 should be placed in the folder code in the C root folder.
• Open the file cc_localsettings.sdv (may also have .csv extension) that is found in the C root folder and update the version to the folder name of the new code. The part to be edited is shown in blue in the example below.
• Note that it is not necessary to delete the folders with old code. Keeping these allows you to run previous versions if necessary.

The part to edit in cc_localsettings.sdv is between the two semicolons in the line shown below.

xxxxxxxxxx
version; C-19-03; Code version to use

Alternatively, you may select the new code by the following procedure:

• Open Chrombox C
• Press the [Settings] button down in the right corner
• Select [Load/Files]
• Select the code version and press [Save local settings]
• Restart Chrombox C.

Tutorial 1 - Basic functions

The main purpose of this tutorial is to get used to basic functions in the program, how to use retention indices for identification, and basics of quantification and reporting. Fatty acid methyl esters (FAME) in two samples of marine algae will be identified and quantified using a predefined template.

1.1. Startup and select method

• Start Chromboc C using one of the methods explained above. The main window should look as in Figure 1.1.
• Start by selecting the method Tutorial-1.
• Thereafter select [Import Box] that will take you to the window for importing new data.

1.2. Importing chromatograms:

• The Import Box window is shown in Figure 1.2.
• The raw data you should work with is from the Agilent Chemstation. Check that the data type is Chemstation.
• Select the folder Tutorial-1. The files in the folder are shown in the data files list.
• When the right folder is selected press [Import All].
• The name next to Save as will be the name of you data box that contains all data and results. You can change it to any legal file name. By default it is the same as the folder name for the raw data.
• Finish by pressing [Accept as new]. This will take you back to the main window where the chromatograms will be displayed.

1.3. Retention index calibration

Identifications in this tutorial are based on the use of retention indices. Since the analytes are fatty acid methyl esters (FAME), the retention index scale is Equivalent Chain Lengths (ECL) where the ECL value for a saturated compound by definition is equal to the number of carbons in the fatty acid chain.

• Select the file Saturated in the box to the right in the main window or by the [<] and [>] buttons and press the [Integrate] button. This integrates the chromatogram, and it also calculates ECL values. You choose between Time (retention times), Index (retention indices) and Scan no. (scan numbers) as the retention axis (x-axis) by using the radio buttons under the chromatogram.
• Select Index as the retention scale. The major peaks in the chromatogram are saturated FAMEs from C12 to C27 (excluding C13 and C23), for which the ECL values are given by definition. Ideally, each of the major peaks should therefore be found at an integer value on the index scale. As you can see, this is not the case. The cause is that the data was acquired at a different time than the reference mixture used for calibration of the template, and that chromatographic conditions have changed in the meantime.
• The next task is therefore to calibrate the retention index scale. Press [Calibrate RI], which will take you to the window for calibration shown in Figure 1.3.
• The yellow labels on the peaks show the correct ECL value that is given by definition. To calibrate the scale, select the peaks by clicking on the labels and type the correct value in the Def. RI field. You will see that the numbers in the table and the plot of retention index (vertical axis) vs retention time (horizontal axis) will change each time you input a new number.
• The plot should show a smooth relationship between ECL and retention time that is linear over the main part of the chromatogram. It should be similar to the one shown in Figure 1.3.
• Press [Update] when you have typed in the last number and leave the window by pressing [Accept].

The chromatogram in the main window should now show peaks that have integer retention indices. You can also verify the retention index by clicking on a peak and inspect the information box.

1.4. Integration and identification

• You can now press [Integr. All] followed by [Ident. All]. Some of the peaks in the “SATURATED” sample will not be identified because they are not in the template. This is not important for the further work.
• Select the different chromatograms by the [<] and [>] buttons and inspect them. Identified peaks will be shown in dark blue, while unidentified peaks are shown in light blue. In the samples there are some peaks that are unidentified because they do not match any retention indices in the template.
• You can zoom and scroll in the chromatograms by the [+]/[-] buttons and the slider. If the [()] button is selected the chromatogram will be zoomed around the selected peak.
• If you select Show Templ. in the checkbox next to the blue button line the template will be shown.

1.5. Editing peaks

You can edit areas and identifications in the chromatogram. An example for the area around the 18:1-monoenes is shown in figure 1.4. The peak to the left is identified as 16:4 n-1. However, it has a shoulder, and the template says that the shoulder should be 18:1 n-9. You can correct this by the following procedure:

• Click on the 16:4 n-1 peak to select it. Click thereafter on the red marker on the right of the peak and move the baseline to where you mean 16:4 ends.
• You now have a space where you can add 18:1 n-9. Right-click on the background in the chromatogram and select Add and identify. Place the vertical axis of the cross where you want to add the peak and click the left mouse button.
• 18:1 n-9 should now be added. If the peak is not automatically identified you can right-click on the peak and select Identify. This will show a list of the peaks in the template, and the correct ID is usually one of the first peaks in the list. Click on 18:1 n-9 and press [Accept].
• You may need to adjust the areas of the added peak, and also adjust areas of 18:1 n-7. When peaks are edited by the user they are shown in green as in the lower chromatogram in Figure 1.4. This means that they are locked and they are not affected by the automated integration and identification procedures. You can lock or unlock peaks by right-click on the area, and you can lock/unlock regions in the chromatogram by right-click on the background.

1.6. Quantification and reporting

When you have edited areas and identifications it is time for quantification of the samples.

The GLC793 sample is applied for calculation of response factors and contains equal amounts of common fatty acids. Before you can quantify the peaks you must ensure that this sample has correct identifications. It should contain the following fatty acids: 12:0, 14:0, 14:1 n-5, 15:0, 16:0, 16:1 n-7, 17:0, 17:1 n-7, 18:0, 18:1 n-9, 18:2 n-6, 18:3 n-3, 18:3 n-6, 20:0, 20:1 n-9, 20:2 n-6, 20:3 n-3, 20:3 n-6, 20:4 n-6, 20:5 n-3, 22:0, 22:1 n-9, 22:4 n-6, 22:5 n-3, 22:6 n-3, 24:0 and 24:1 n-9. It is possible that 20:0 is identified as 18:4 n-3 since these two peaks has almost identical retention indices.

• Select the GLC793 sample and zoom in around 20 on the retention index scale (approx 28.3 min on the time scale). If the peak is not identified as 20:0, right click on the peak, select Identify, select 20:0 in the list and press [Accept].
• When all peaks are correctly identified you can press the [Quantify] button. The program will issue a warning telling that the internal standard was not found in chromatogram number 1. This is not a problem since chromatogram 1 is the reference sample used for calibrating the retention index scale. It is not used for any quantitative purpose.
• The [Quantify] button is a toggle button that must be manually released. As long as the button is activated the quantitative results will be updated by any change you make in the chromatograms. If you for instance edit a reference sample used for calculating response factors, all the chromatograms will be updated. If there are many chromatograms in the box the program may therefore run slowly when the button is active. If you report amounts or adjusted areas (corrected by response factors) the [Quantify] button must be pressed before you are allowed to report the results.
• You have now finished the editing of the chromatograms and the calculations. You can save your edited data by pressing [Save Box]. If you type * in the search string field, all the saved boxes will be listed. Data boxes are loaded by selecting them in the list and pressing the [Load Box] button. If Incl. Meth. is checked, the method (as it was when you saved the box) will also be loaded.
• To generate reports of the two algal samples, select the chromatograms and press [Report Sgl.]. This will generate a report and usually also open it (on some systems the report may not open, but it can be found in the “reports” folder.). The default report format is Excel, but other report formats and report settings can be selected by pressing [Settings] followed by [Reports].

The reports are generated according to the template. Unidentified peaks are summarized and reported as “other”. In most cases, the fields of interest are adjusted area percents and amounts. The amounts are calculated according to the internal standard. The amounts of the internal standard are specified in the method settings, but the amounts can also be edited in the “IS Amt.” field in the main window.

Note that the reported area percent, adjusted area percent and the amount of the internal standard (23:0) is zero, even though it is present in the sample. This is because the internal standard is added, and not originally present in the sample.

The amounts are in this case μg FAME present in the samples. Selected fields for “ALGAE 40” are presented in Table 1.1.

Keyboard shortcuts

Scaling / scrolling

• Scroll Chromatogram: [Arrow L/R]
• Scale Y-axis: [Arrow U/D] or [mouse wheel]
• Zoom in: [+] or [Z]
• Zoom out: [-] or [X]
• Zoom on cursor: [C] or [Shift+mouse wheel]
• Autoscale on/off: [A] / [Shift+A]

Selection

• Next peak: [N]
• Next chromatogram: [Shift+N]
• Previous peak: [B]
• Previous chromatogram: [Shift+B]

Integration

• Reintegrate [R]
• Adjust peak baseline to lower: [J]
• Adjust peak baseline to upper: [Shift+J]

Add and identify peaks

• Add peak: [P]
• Add and identify: [Shift+P]
• Identify peak: [I]
• Identify direct (no window): [Shift+I]

Locking and unlocking

• Lock peak: [L]
• Unlock peak: [Shift+L]
• Lock visible [V]
• Unlock visible [Shift+V]

Labels and plotting

• Change ID type: [D]
• Peak numbers on/off: [O]
• Peak labels on/off: [Shift+O]
• Hide/show template: [H]