MultiTrace Configuration files

From MassFinder

Jump to: navigation, search
MultiTrace 3: Manual

MultiTrace offers several options and settings to customise its behaviour and to enable or disable certain advanced features. Usually, only the MultiTrace administrator of a team should be entitled to change the configuration files, and in most cases assistance by or delegation to the IT support team of a company is advised.

MultiTrace reads up to three configuration files:

  • MultiTrace3-user.ini contains mostly settings that can be set by the user interactively inside MultiTrace using the options dialog.
  • MultiTrace3-global.ini contains settings that are intended to apply to all users of a team. Some of these options overwrite the local settings of user.ini.
  • MultiTrace3-db.ini contains settings related to the database connectivity, e.g. LIMS access or the result file ID feature.

Contents

MultiTrace3-user.ini

MultiTrace3-user.ini contains mostly settings that can be set by the user interactively inside MultiTrace using the options dialog. These options are local and apply only to each user's own installation. The user.ini file is the only configuration file which is written to each time MultiTrace is closed.

In addition, the administrator can set some permissions which determine whether certain features are available to the user; these local permissions can be overwritten by the global configuration file.

The user.ini file must reside in the MultiTrace installation folder, i.e. in the same folder as the executable.

Log file

MultiTrace can create a log file while running. Several important routines like open, save, and database accesses are logged. This might help you or the MultiTrace support team to solve problems.

[Log]
Enabled=0
ResetAtStart=1
Debug=0

The entire section may be absent.

  • Enabled -- Log file is written (=1); default is off (=0).
  • ResetAtStart -- If enabled, MultiTrace clears the log file at each start, otherwise continues writing to the same log file for several sessions.
  • Debug -- If enabled, the log file will contain several more entries of very internal nature. Default is off. Leave this setting off if you want to analyse database access (which is the most often aim of log file usage by customers).

ini-files

The entire section may be absent. If absent, the global.ini is found in the installation folder with the default filename of MultiTrace3-global.ini. If present, both global.ini and db.ini may be located anywhere, e.g. on network drives.

The token dbINI is only necessary if database connectivity is actually used.

[inifiles]
GlobalINI=R:\MultiTrace3\MultiTrace3-global.ini
dbINI=R:\MultiTrace3\MultiTrace3-db.ini

Permissions

These permission settings enable or disable certain features, most of them only needed for method maintenance.

[Permissions]
ChangeWindow=1
ShowMethodEditor=1
ShowSetEditor=1
ShowConvertMethod=1
ShowVersionControl=1
ShowMSLegend=1
ShowTIC=1

The entire session may be absent. Default is off for all options.

  • ChangeWindow -- If enabled, users can change the visible time window and search time window interactively as describe in the Tutorial: Optimising Time Windows. We recommend to turn this feature off for all users but methods administrators.
  • ShowMethodEditor -- If enabled, the button method editor is visible. We recommend to turn this feature off for all users but methods administrators.
  • ShowSetEditor -- If enabled, the button method set editor is visible. We recommend to turn this feature off for all users but methods administrators.
  • ShowConvertMethod -- If enabled, the option dialog's tab sheet convert method is visible. We recommend to turn this feature off for all users but methods administrators.
  • ShowVersionControl -- If enabled, the option dialog's about page contains the [[MultiTrace Version control|version control] information.
  • ShowMSLegend -- If enabled, all mass spectra show an m/z list of the selected ion traces and can be used to delete, add and modify the ions. This is intended for easy method creation and maintenance. We recommend to turn this feature off for all users but methods administrators.
  • ShowTIC -- If enabled, the button TIC is visible, which opens a dialog with the total ion chromatogram. Generally, for SIM analysis this is not necessary and the button can be turned off.

Other sections

All other sections not mentioned so far directly correspond to options that can and should be set interactively inside MultiTrace by the end-user. They are self-explanatory. Most checkboxes and edit fields show bubble hints when then mouse hovers over them.

MultiTrace3-global.ini

MultiTrace3-global.ini contains settings that are intended to apply to all users of a team. Some of these options overwrite the local settings of user.ini. The global.ini file can reside in the MultiTrace installation folder (default, if no path to global.ini is provided in the user.ini) or at any other place, e.g network drives, in which case the user.ini file must provide the path and filename to the global.ini.

Permissions

By default, the permissions section of the global.ini file is absent. The permissions section of the global.ini overwrites the identically named tokens of the user.ini file. Please only add those tokens to the global.ini's permissions section that you intentionally want to overwrite the local setting, so that all users have the same settings. If a token is absent in global.ini, the value of user.ini is taken.

[Permissions]
ShowMSLegend=1
ShowMethodEditor=1
ShowSetEditor=1
ShowConvertMethod=1
ShowVersionControl=1  
ShowTIC=1 
ShowMT2=1            
ShowSeqSummary=1
ShowOverlay=1     

The typical scenario is to have a larger group of users that do evaluation and one or a few administrative users that to both evaluation and method development. We recommend to delete all permissions from all user.ini files, then only to include those permissions in the administrator's user.ini files that they need for method development, and to include the permissions free to all users in the global.ini file. That way, the general permissions can be changed easily in the global.ini file and the user.ini file is as concise as possible.

[Permissions]
PermissionEurofins=0
PermissionEvaExport=0  
PermissionRecovery=0   

These three special permissions are exclusive to the Eurofins holding. They enable result data export to Eva 2.x software, automatic recovery statistics export and some database connectivity with LIMS read and write access. For Eurofins Specht, Hamburg, all three options should be turned on at all times. All other companies should keep these settings absent.

Version control

The version control feature enables to enforce certain versions or inform users about available updates.

[Version]
required=3.03-26
available=3.03-26
NotifyOnAvailable=1
NotifyOnRequired=1
BlockOnRequired=0
  • required --- Version number of MultiTrace required with regards to your internal company's decision.
  • available --- Most current version number of MultiTrace available in your company.
  • NotifyOnRequired -- If enabled, MultiTrace informs the user, that a version number of at least the given number or higher is required, if the version of the executed instance is lower than the given version number. If all users use the same global.ini, you can inform users, if certain update are obligatory for internal reasons, e.g. if reports have been altered or bug fixes installed. The user can click OK and continue anyway, if BlockOnRequired is off or MultiTrace will quit automatically, if BlockOnRequired is on.
  • NotifyOnavailable -- If enabled, MultiTrace informs the user, that a newer version is available than the version of the executed instance. Use this options to let users decide when to update their version.
  • BlockOnRequired -- see NotifyOnRequired.

The options dialog shows the version information on its about tab sheet.

Processing

The section processing controls how MultiTrace attempts to extract dilution factor, weight factor, and sampleID from the raw data file.

[Processing]
ExtractDE=FDE

There are several possible values, a few of which are exclusively for certain customers. We recommend to discuss this issue with the laboratory supervisor, the company's IT support team and the MultiTrace support team in order to find the most convenient and efficient solution for you.

Weight factor and dilution factor can be entered manually in MultiTrace by clicking on the respective edit fields of the query panel (which can be shown using the screen layout menu or toggled on/off by hitting "q"). However, we strongly recommend to find an automatic solution in order to save time and reduce typing errors. This is the only issue in which the laboratory conventions might be necessary to be slightly adjusted in order to use MultiTrace most efficiently.

The token ExtractDE might have the following values:

  • FDE -- All values are taken from the ChemStation data folder filename, which has the following format: "SAMPLEID_Dxxxx_Eyyyy.D", and where SAMPLEID is your LIMS primary sample identifier (barcode number, reference number, sample number), where "xxxx" is the dilution factor and "yyyy" is the weight factor. If "Dxxxx" is missing, the default dilution factor is 1. If "Eyyyy" is mssing, the default weight factor is 1000. The order of "Dxxxx" and "Eyyyy" does not matter, nor does the number of digits. -- Example: 93431_D1_E1184.D give the barcode number 93431, the dilution factor 1 and the weight factor 1184.
  • D_E -- All values are taken from the ChemStation DATA.MS data file's SAMPLENAME field which is set in the sequence table or acquisition form. The format is identical to that of FDE.
  • Express -- SampleID and dilution factor are taken from the folder filename, which has the following format: "SAMPLEID_Dxxxx" with the same meaning as described at FDE. The weight factor is taken from ChemStation DATA.MS raw data file's MISCINFO field, which may only contain digits, e.g. "1184".

Generally, we are able to create processing routines that take values from the folder.D filename or from the SAMPLENAME and MISCINFO fields of the DATA.MS raw data file. If more than one value shall be taken from a single field, we recommend to use the character "_" (underscore) as delimiter. We are also willing to take further values like the LIMS test code from any of this fields.

Alternatively, it is possible to take only the sample identifier from any of the fields and do a database query to fill in the other parameters like dilution factor, weight factor, test code and even matrix, country of origin, target time and so on.

Online help

The help section controls what content is shown in the online help dialog, which can be opened by clicking on the "?"-button in the upper right corner of the main view.

[Help]
HotkeyURL=R:\MultiTrace3\help.html
HomeURL=http://massfinder.com/wiki/MultiTrace_Manual
  • HotkeyURL gives a path and filename of any HTML file that is displayed when first opening the online help or after selecting the hotkey button. You may install a proprietary file here, e.g. linking to your intranet, or you may edit our help.html file in order to include further text or hyperlinks to your intranet. If absent, default is "help.html" in the installation folder of MultiTrace.
  • HomeURL give a URL that is displayed when clicking on the home button. Default is our official wiki website with the MultiTrace manual. However, you are free to set this to any internet or intranet page.

The entire section may be absent. The default values will apply and provide sufficient online help.

Instruments

The instruments section enables to set-up a list of paths linking directly to the sequence folders of your MS instruments or to any other local or network folders often used.

This list of paths is offered in the upper-left combo box of the open new sequence, add reference or open sample dialogs. If speeds-up selecting the instrument's sequence folder compared to clicking through a Windows explorer tree.

[Instruments]
Count=1
InstrumentPath0=E:\MultiTrace3\data\Demo
InstrumentName0=Demo
  • Count gives the number of paths you have entered.
  • InstrumentPath0 gives the path of the first instrument.
  • InstrumentName0 gives a shortcut name for the first instrument.

You may install as many instruments as necessary.

Hotkeys

The hotkey section defines four comments that can be added to an ion of a parameter by simply hitting one functional key. This is the most efficient way of adding a comment to a certain ion trace.

F1..F4 apply to the four comments of the first ion, F5..F8 to the second ion and F9..F12 to the third ion.

[Hotkeys]
Hotkey_F1=shoulder
Hotkey_F2=interference
Hotkey_F3=matrix
Hotkey_F4=background

Comments

The comments section defines a number of comments that can be added to an ion of a paramter by hitting several times the appropriate key.

The key 'o' changes the comment of the first ion, the key 'p' of the second ion and the key 'ü' (German keyboard) or '[' (English keyboard) of the third ion. Repeatedly striking the same key, scrolls through all defined comments, i.e. the second stroke selects the second comment and so on, after the last comment it starts over with the first coment. This method is called rotational comments. Main advantage is the unlimited number of possible comments. Main disadvantage is the number of keystrokes necessary to enter a late comment.

We recommend to use hotkey comments and rotational comments concurrently.

File format

The file format section controls which raw data files can be opened with MultiTrace.

[FileFormat]
DataType=MSD
OpenDatafile=DATA.MS
OpenDatafilesMSD=DATA.MS,DATASIM.MS
OpenFilter=v,ref
  • DataType is at the moment alway MSD.
  • OpenDatafile is the last data type opened (selected interactively by end-user).
  • OpenDatafilesMSD is the list of possible data file names from which the user can select one. We recommend to delete all filenames that are end-users are not supposed to work with. For example, if you acquire DATA.MS (fullscan) and DATASIM.MS (single-ion monitoring) simultaneously and analysis is always done with the DATASIM.MS file, then remove DATA.MS. If your instruments acquire only DATA.MS (even in SIM mode), then only enter DATA.MS here.
  • OpenFilter -- In both open dialogs are filter buttons, which allow to display only references in the open reference dialog or only samples in the open sample dialog, respectively. This feature relies on references named along certain conventions, i.e. first letters of the file name. For example, if all references would start with either "ref..." or "VN...", MultiTrace could easily distinguish samples and references from each other. This would shorten the open dialog file lists and speed up selection. Discuss this issue with your laboratory supervisor and try to find an efficient way to name your files and to distinguish references from samples.


MultiTrace3-db.ini

MultiTrace3-db.ini contains settings related to the database connectivity, e.g. LIMS access or the result file ID feature. The db.ini can reside in the MultiTrace installation folder or at any other location. The path and filename must be provided in the user.ini or global.ini. If the path is found in the user.ini, this location is preferred, otherwise the global.ini path is taken. In case you use a global.ini at a different location (i.e. not the installation folder), we recommend to store db.ini at the same location. If no database connectivity is desired, the file may be absent.

MultiTrace uses an ADO interface connecting via ODBC drivers to your databases. For each database query or command you need to provide a connection string and an SQL. The SQL usually is a stored procedure defined on your database server. In some cases, the SQL can be a simple query. Please ask your database administrator to setup the db.ini file and to develop the necessary stored procedures and database tables.

Connecting strings

The ConnectionStrings section defines several connection strings. The names of the connection string tokens is your decision. You may define as many connection strings as needed and this depends on how many different databases you need to access. This is the only section where the tokens are not pre-defined by MultiTrace, but up to your choice.

[ConnectionStrings]
MyLIMS=DSN=HMLIMS

You will later use the connection strings defined here as shortcuts, so if you need to change the connection string for a certain database, you only need to update the definition rather to update each single database query.

Tokens in SQL

Queries, commands and stored procedures need certain parameters, i.e. values MultiTrace passes along to the SQL. The concept of transferring parameters to SQL commands, queries or stored procedures is that MultiTrace takes the given SQL text and replaces all occurences of pre-defined tokens of the form §TOKEN# with the appropriate content. For each database routine the manual entry will list which tokens are passed along.

Fields of result-sets

Usually, the queries, commands and stored procedures return a result-set. The names of the fields are your choice and MultiTraces accesses the correct fields by pre-defined tokens set to the returned result fields. Thus, the names of fields in your tables is independent from the internal field names implemented in MultiTrace. However, a synchronisation surely would help support and straight-forwardness of the db.ini definitions.

Fields of tables

Each database routine communicates through stored procedures and result-sets with your database. Which fields are actually stored in your tables and which fields are virtual or part of a view, does not matter. Your tables may have other fields, less fields, more fields, whatever is best suited for your database.

Generally, MultiTrace passes along the application identifier 'MultiTrace' and the user name (i.e. the Windows login name of the current user). This enables to possible use the same tables and stored procedures with other software products of Hochmuth Scientific Consulting. You are free to discard these parameters, but we recommend to save them and add a date-time stamp to each record you create.

Database connectivity

Details of each database routine are given in database connectivity.

Personal tools