ASTM E2078-00(2016)

This international standard was developed in accordance with internationally recognized principles on standardization established in the Decision on Principles for the
Development of International Standards, Guides and Recommendations issued by the World Trade Organization Technical Barriers to Trade (TBT) Committee.
Designation: E2078 − 00 (Reapproved 2016)
Standard Guide for
Analytical Data Interchange Protocol for Mass
Spectrometric Data
This standard is issued under the fixed designation E2078; the number immediately following the designation indicates the year of
original adoption or, in the case of revision, the year of last revision. A number in parentheses indicates the year of last reapproval. A
superscript epsilon (´) indicates an editorial change since the last revision or reapproval.
1. Scope 2. Referenced Documents
2.1 ASTM Standards:
1.1 This guide covers the implementation of the Mass
Spectrometric Data Protocol in analytical software applica- E2077 Specification for Analytical Data Interchange Proto-
col for Mass Spectrometric Data
tions. Implementation of this protocol requires:
2.2 Other Standard:
1.1.1 Specification E2077, which contains the full set of
data definitions. The mass spectrometric data protocol is not NetCDF User’s Guide
2.3 ISO Standards:
based upon any specific implementation; it is designed to be
independent of any particular implementation so that imple- 8601:1988 Data elements and interchange formats, (First
edition published 1988-06-15; with Technical Corrigen-
mentations can change as technology evolves. The protocol is
implemented in categories to speed its acceptance through dum 1 published 1991-05-01)
actual use.
3. List of Contents and Use
1.1.2 Specification E2077 contains a full description of the
contents of the data communications protocol, including the 3.1 NetCDF Toolkit—The protocol is an application pro-
analytical information categories with data elements and their gramming interface (API) layered on top of the public domain
attributes for most aspects of mass spectrometric tests. NetCDF toolkit. NetCDF is a set of tools that facilitate reading
or writing platform-independent, self-describing data files. All
1.2 The analytical information categories are a practical
data in a NetCDF file is written using the external data
convenience for breaking down the standardization process
representation (XDR). XDR was developed by Sun Microsys-
into smaller, more manageable pieces. It is easier for develop-
tems and is used for platform-independent file systems for all
ers to build consensus and produce working systems based on
workstations and personal computers. Each NetCDF data
smaller information sets, without the burden and complexity of
element is self-describing - it has a name, type, and dimen-
the hundreds of data elements contained in all the categories.
sionality. A NetCDF file contains three parts: a dimensions
The categories also assist vendors and end users in using the
section, which defines the names and size of all dimensions
guide in their computing environments.
used to describe variables; a variables section, which defines
1.3 The network common data format (NetCDF) data inter-
the names, data types, dimensionality, and attributes for all
change system is the container used to communicate data
variables used in the file; and finally, a data section, which
between applications in a way that is independent of both
contains the actual values assigned to the variables. Attributes
computerarchitecturesandend-userapplications.Inessence,it
are numbers or strings which augment the description of
is a special type of application designed for data interchange.
variables or the file as a whole.
3.1.1 For example, a variable “x_axis_ values” might con-
1.4 The common data language (CDL) template for mass
tain an array of numbers representing the abscissa of a
spectrometry is a language specification of the mass spectrom-
two-dimensional data set. It would have a dimension, possibly
etry dataset being interchanged. With the use of the NetCDF
named “x_axis_size,” which would specify the number of
utilities, this human-readable template can be used to generate
an equivalent binary file and the software subroutine calls
needed for input and output of data in analytical applications.
For referenced ASTM standards, visit the ASTM website, www.astm.org, or
contact ASTM Customer Service at service@astm.org. For Annual Book of ASTM
Standards volume information, refer to the standard’s Document Summary page on
the ASTM website.
1 3
This guide is under the jurisdiction of ASTM Committee E13 on Molecular Available from Russell K. Rew, Unidata Program Center, University Corpora-
Spectroscopy and Separation Science and is the direct responsibility of Subcom- tion for Atmospheric Research, P.O. Box 3000, Boulder, CO 80307-3000, http://
mittee E13.15 on Analytical Data. www.unidata.ucar.edu/.
Current edition approved April 1, 2016. Published June 2016. Originally Available from International Organization for Standardization (ISO), ISO
approved in 2000. Last previous edition approved in 2010 as E2078 – 00 (2010). Central Secretariat, BIBC II, Chemin de Blandonnet 8, CP 401, 1214 Vernier,
DOI: 10.1520/E2078-00R16. Geneva, Switzerland, http://www.iso.org.
Copyright © ASTM International, 100 Barr Harbor Drive, PO Box C700, West Conshohocken, PA 19428-2959. United States
E2078 − 00 (2016)
abscissa points. The variable might have some descriptive would be required external to the NetCDF file to translate the
attributes,suchas“units”(withavalueof“Seconds,”perhaps), number into something meaningful.
“scale_factor” (with a value of 1000.0, specifying that all
storedabscissavaluesshouldbemultipliedby1000.0togetthe 4. Conventions
actual value), or “long_name” (with value“ Time”, which
4.1 The format convention adopted in this guide is as
might be used to label the abscissa when drawing a plot).
follows:
3.1.2 The NetCDF toolkit has been placed in the public
(1) Normal text is presented in this font (Times New
domain by the Unidata Program Center, a non-profit software
Roman).
support organization for the University Corporation for Atmo-
(2) API symbols (functions, formal types, etc.) are pre-
spheric Research. The Unidata Program Center is funded by
sented in boldface Helvetica font.
the National Science Foundation, National Center for Atmo-
(3) Parameters to API functions are presented in italic
spheric Research, and other organizations and provides ongo-
Helvetica font.
ing development and support of NetCDF and related tools.
(4) Example code is presented in normal Helvetica font.
3.1.3 The NetCDF version currently supported in this
4.2 Other Conventions—All indices begin at zero (C con-
implementation is 2.3.2.
vention). In several data structures, a scan_no or inst_no
element must be loaded before reading or writing. This
3.2 Data Structures—Each of the analytical information
identifies the scan or instrument component number for which
class tables in the specification document has a corresponding
data will be read or written. In all cases, scan or instrument
data structure; however, not every field in each table has a
component numbers begin at zero.
corresponding data element in a structure, and the data struc-
4.2.1 All date/time stamps are formatted using the ISO
tures may have elements that do not appear in any class table.
standard 8601 format referenced in the specification. An API
Most of these differences are due to details of the implemen-
utility function is provided for conversion between date/time
tation which could not be hidden.
information in numeric form and ISO-8601 string format (see
3.2.1 The data structures provide the mapping between the
ms_convert_date(), below).
attribute name and data type described in the specification and
the field and actual data type in the file. The actual NetCDF
5. Mass Spectrometric Data Protocol Distribution Kit
dimension, variable, and attribute names are hidden from the
5.1 It is intended that potential users of this implementation
API level. These names in fact are irrelevant for application
programs; it is the data structure which provides the informa- can obtain a complete NetCDF and API distribution kit from
various instrument vendors’ websites. Information on how to
tion interchange between the application and the file.
obtain the kit will be posted on the ASTM website
3.2.2 Each data structure and its mapping to an analytical
(www.astm.org) under Committee E01.25.
information class are described in detail later in this guide.
3.2.3 Application Programming Interface Functions: 5.2 The Analytical Data Interchange Protocol for Mass
Spectrometric Data distribution kit contains:
3.2.3.1 The application programming interface provides
5.2.1 Software—NetCDF distribution kit from Unidata
programmatic access to the contents of the files. Mass spectral
(withthemodifiedmakefileneededtomakethekitcompileout
data occurs in three forms: global information, which relates to
of the box).
thecontentsoftheentirefile,informationwhichdescribeseach
5.2.2 NetCDF User’s Guide—supplied by Unidata Program
part of a multi-component instrument, and information which
Center.
changes on a scan-by-scan basis for spectra and library entries.
5.2.3 Specification E2077.
API functions are provided for opening a file for reading or
5.2.4 Guide E2078.
writing; closing a file; reading and writing global, per-
component instrument, and per-scan spectral and library infor-
6. Hardware and Software
mation; initializing and clearing data structure contents; and a
few miscellaneous utility functions. Each of these functions is
6.1 This section describes the hardware and software con-
described in detail in a later section of this guide.
figurations used for testing. In general, the NetCDF system
3.2.4 Enumerated Sets—Many of the attributes listed in the puts very few requirements on the hardware because most
Analytical Data Interchange Protocol for Mass Spectrometric routines are left on disk. Only routines being used at any
Dataspecificationhaveanenumeratedsetofassociatedvalues. particulartimearekeptinmemory.Anylimitationsfoundwere
The attribute may take only one value from that restricted set. typically those not imposed by NetCDF but ones imposed by
In the implementation, each such attribute is defined as a the operating system or environment.
formal C type, and the allowed values are defined as an 6.1.1 Hardware (Personal Computers)—The personal com-
enumerated set of that formal type. Each enumerated value is puter system hardware originally used for testing was:
associated with a unique string literal, and it is these string 6.1.1.1 Intel 80286 processor,
literals, not the enumeration values, which are written to or 6.1.1.2 640K minimum,
read from the file. This practice both enforces the use of the 6.1.1.3 Monochrome, EGA, VGA graphics,
proper enumeration values and follows the NetCDF dictum 6.1.1.4 20 megabyte minimum, 80 megabyte hard-disk is
that files be self-describing. If the enumeration values were typical, and
written instead of the strings, then some lookup mechanism 6.1.1.5 A mouse (optional).
E2078 − 00 (2016)
6.1.1.6 NetCDF works well on AT-class machines and
UTIL
XDR
higher. NetCDF does not have the items in 6.1.1.1 – 6.1.1.5 as
SRC
requirements. These are just the minimum, base-level systems
NCDUMP
that were used.
NCGEN
NCTEST
6.1.2 Software—NetCDF runs on MS-DOS, OS/2,
Macintosh, Windows 95, and Windows NT operating systems
7.3.1 The UTIL and XDR makefiles work as distributed
for personal computers. NetCDF was originally ported from
using NMAKE with Microsoft C V6.0.
UNIX to DOS running on an IBM-PS/2 Model 80. It was
recently ported to the Macintosh OS. NetCDF is written in the
8. CDL Template Structure
C programming language, and there are FORTRAN jackets
8.1 ANetCDF template is built from CDLstatements and is
available for applications that want to use FORTRAN calls.
structured into three sections: (1) dimension declarations, (2)
The personal computer software originally employed for test-
variable declarations, and (3) the data section.
ing and developing NetCDF applications was:
6.1.2.1 Microsoft DOS V3.3 or above, 8.2 AfewpointsofclarificationabouttheCDLlanguageare
6.1.2.2 Microsoft C Compiler V6.0, given here to facilitate its understanding. For more in-depth
informationonCDL,pleaseconsultthe NetCDF User’s Guide.
6.1.2.3 Microsoft Windows V3.0,
6.1.2.4 Microsoft Windows SDK, and 8.2.1 A NetCDF template starts with the word “NetCDF”
6.1.2.5 NetCDF Version 2.0.1. followed by the dataset name.
6.1.3 Workstations and Servers—NetCDF runs easily on
8.2.2 CDL comments are indicated by two forward slash
UNIX workstations such as Sun 3, Sun 4, VAXstations, characters (//).
DECstation 3100, VAXstation II running ULTRIX or VMS,
8.2.3 Section indicators (dimensions:, variables:, and data:)
and IBM RS/6000. There are no particular hardware require-
end with a colon character (:). These are the only tokens that
ments for workstation class machines, since all workstations
end with a colon character.
have the minimum hardware outlined for personal computers
8.2.4 Statements within sections end with the semicolon
in 6.1.1.
character (;).
8.2.5 Variable names beginning with numbers must be
7. Significance and Use
preceded by an underline character (_). Otherwise the ncgen
7.1 General Coding Guidelines—The NetCDF libraries are parser will flag an error.
supplied to developers as source code. End users receive the
8.2.5.1 Underline characters were chosen for this protocol
libraries in compiled binary form as part of a vendor’s
over hyphen characters, because some compilers may interpret
application.
hyphens as subtraction operators. The feature of CDL that
7.1.1 Developers setting out to write a program to convert
allows implicit numerical datatyping of attributes in not being
their data files to the Mass Spectrometric Data Protocol should
used in the first version of the template. Instead, all floating
consider using the NetCDF utilities ncgen and ncdump. After
point attributes are being handled as strings. This forces
developers create the NetCDF file they should use the ncdump
programmers to explicitly type variables, thereby encouraging
program to generate the ASCII representation of the data file,
more deliberate programming styles. For example:
and examine it to ensure the data are being correctly put into
:aia_template_revision = “0.8”; //M12345
the file.
:netcdf_revision = “2.0.1”; //M12345
Consult the NetCDF User’s Guide for more complete
7.2 Make Files for NetCDF Libraries and Utilities—In
information on CDL syntax and usage.
generalthecompilationisstraightforward.Themakefileswere
8.2.6 Underline characters only can be used as separators
modified after they were received from the Unidata
between words within variable names, like:
Corporation, because they did not compile the first time on
PCs. The changes needed to get the Unidata distribution to run
aia-template-revision, or aia_template_revision.
on DOS are (1) rename the file MAKEFILE to UNIX.MK, and
8.2.7 Numerical data types for single values can be declared
(2) rename MSOFT.MK to MAKEFILE, and then run
implicitly by putting numbers on the right side of an assign-
NMAKE. The default switches in the Unidata distribution use
ment statement, like:
the switches for the floating point coprocessor and Microsoft
peak_number=2; //number of peaks
Windows options.
These numerical datatypes can be floating point or integer
7.2.1 The protocol kit contains some complete makefile
values, and can be implicitly datatyped as such.
examples for Microsoft C V6.0 running on DOS. The Micro-
:floating_point_attribute = 1.11; //M12345
soft C V6.0 compiler manual should be consulted for the exact
meaning of the compiler and linker options.
8.2.8 Numerical data types can be declared explicitly by
7.2.2 The VMS and SunOS compilation instructions are in
preceding the variable definition by its data type. Datatype
directories for those operating systems.
assignments can be for either single value variable definitions
or for array variable definitions, for example:
7.3 NetCDF Library Build Order—The NetCDF libraries
float detector_maximum_value;
must be built in a specific order. The correct order to build the
float ordinate_values(point_number);
NetCDF directories is:
E2078 − 00 (2016)
There is also a way to explicitly declare datatypes on the 10. Data Structures
right side of an assignment operator. Please consult the
10.1 The protocol data structures form the heart of the
NetCDF User’s Guide for details.
information interchange. When reading a file, the API loads
8.2.9 Metadata are associated with a particular variable by
information from the file into the fields of the data structures.
attachingittothatvariablewithacoloncharacter,forexample:
The application program is responsible for preparing the data
ordinate_values:uniform_sampling_flag=“ Y”;
structures for use by the API functions, for removing the
ordinate_values:autosampler_position=“ 1.01”;
information returned by the API, and for clearing the data
8.2.10 Global metadata can be declared simply by not
structuresforsubsequentuseinanotherAPIcall.Whenwriting
attaching it to any variable, for example:
a file, theAPI extracts information from the data structures and
:aia_template_revision= “0.8”; //M12345
writes it to the file. The application program is again respon-
8.2.11 String attributes can be as long as needed, and are sible for preparing and loading information into the data
declared by enclosing the strings in quotation marks, for structures and then clearing them after the API call.
example:
10.1.1 It is important to emphasize that the application
:retention_unit= “time in seconds”; program is responsible for the data structure contents.API
functions are provided to initialize and clear data structure
8.3 Notes About the Mass Spectrometric Data Protocol
contents. These functions make several assumptions; in order
Usage of CDL—Some mandatory indicator codes (M-codes)
to ensure proper interaction of the protocol and applications
for data elements such as M1234, M1, etc., are given in some
and to avoid memory allocation errors, these rules must be
comment fields of the protocol template. These are not part of
followed:
CDL syntax. These refer to whether a given data element is
(1) When using API functions to read from a file, the API
mandatory for particular information categories, for example,
allocates memory for character strings and numeric arrays.
M1234 specifies that the data element is mandatory for
It is the applications’ responsibility to free this memory (using
Categories 1, 2, 3, and 4. These M-codes are also given in the
free()) after the data structure contents have been used. Failure
Specification E2077.
to do so will result in a memory leak.
9. Other Usage Tips
(2) When using API functions to write to a file, the API
assumes that the application has allocated memory for
9.1 Filename Extensions—The recommended filename ex-
character strings and numeric arrays. The API file writing
tension is “.cdf,” so that the full name for a NetCDF file would
functions do not free this memory; however, API functions
be “filename.cdf.” This is used so that parsers used to select
whichcleardatastructurecontentsassumethatanynon-NULL
files can parse filenames based on the “.cdf” extension rather
pointers reference allocated memory, and will free the memory
than some other non-standard file extension.
and clear the pointers. It is acceptable to use pointers to
9.2 Handling of a Missing Variable—The absence of a
statically declared storage, but the application must ensure that
variable implies that it is not in the file. For example, if a get
pointers to such storage are not passed to the data structure
operation returns an error condition, this implies that the
initialization routines.
variable does not exist in that file.
(3) When reading an interchange file, a NULL pointer will
9.3 Performance Tip For Data Value Access—The point_
bereturnedincharacterstringornumericarrayfieldsforwhich
number dimension was originally declared as“ unlimited”;
no data is present in the file.
however,thiswaschangedtoafinitevaluebecausethischange
(4) When writing an interchange file, NULL pointers may
allows getting and putting of an entire array at once. This
be passed in most cases for character strings or numeric arrays
change is minor and will not affect programs, however, it
for which no data are present or which are inappropriate or
greatly improves performance. Using point_num as unlimited
inapplicable. Exceptions are noted in the sections below.
restricts get/put operations to single values at a time, that is,
10.2 Administrative Information Class—MS_Admin_
they are treated as records.
Data. The MS_Admin_Data data structure maps the admin-
9.4 Getting Valid Date Time Stamps—In order to get the
istrative information class attributes and data types. It is only
correct date-time-stamp values in datasets originating from
referencedonceincode,eitherwhenreadingfromorwritingto
DOS and OS/2 systems, the environment variable for time
a file. MS_Admin_Data is a typedef. Table 1 describes the
zone must be set correctly. The recommended procedure is to
data structure fields, formal types, and mapping to administra-
set the offset form Greenwich Mean Time (GMT) at product
tive information class attributes.
installation time. Some examples of how to set the time-zone
10.2.1 ms_admin_expt_t: Experiment Type—The default
environment variable are as follows:
value is shown in grey. See Table 2.
9.4.1 The command “DOS-PROMPT>tz pst 8 pdt” sets the
time-zone variable to have a GMT offset of Pacific Standard 10.3 Instrument-ID Information Class—MS_Instrument_
Time (pst), with a value of8hoffset from GMT, at Pacific Data. Instrument data occurs on a per-component basis (that
Daylight Time (pdt). is, an instrument may be composed of one or more instrument
9.4.2 The command “DOS-PROMPT>tz est 5 edt” sets the components. The total number of components is defined using
time-zone variable to have a GMT offset of Eastern Standard the ms_open_write () or is read from the interchange file
Time (est), with a value of5hoffset for GMT, at Eastern during ms_open_read () (see below). When writing, the
Daylight Time (edt). MS_Instrument_Data structure is filled with the data for
E2078 − 00 (2016)
TABLE 1 Data Structure Fields
10.3.1 When both reading and writing, the inst_no field
MS_Admin_Data must be filled with the index number of the component. These
A B
Type Field Name E M Specification Attribute index numbers are arbitrary, but must be sequential beginning
C C
char dataset_completeness x data set completeness
withzero.Otherfieldsmustbefilledinbytheapplicationwhen
C C
char ms_template_revision x template revision level
C writing, or are filled by theAPI when reading. The application
char comments administrative comments
C
char dataset_origin data set origin is responsible for initializing the MS_Instrument_Data
C
char dataset_owner data set owner
structure before use, and for clearing its contents betweenAPI
C
char experiment_title experiment title
C calls. See Table 3.
char experiment_date_time x experiment date/time stamp
D
(1) experiment_type x experiment type
10.4 Sample Description Information Class—MS_Sample
C
Char experiment_x_ref_0 experiment cross-
E
_Data. The MS_Sample_Data structure occurs once per
references
C
char experiment_x_ref_1 experiment cross-
interchange file. See Table 4.
E
references
10.4.1 ms_sample_state_t:—sample state. See Table 5.
C
char experiment_x_ref_2 experiment cross-
E
references
10.5 Test Method Information Class—MS_Test_Data.The
C
char experiment_x_ref_3 experiment cross-
E MS_Test_Data structure occurs once per interchange file.
references
C
char netcdf_date_time x NetCDF file date/time stamp Depending on the specifics of the experiment which generated
C C
char netcdf_revision x NetCDF revision level
the data set, many fields will most likely be inappropriate or
C
char operator_name operator name
C inapplicable. Only those fields which are appropriate need be
char source_file_reference source file reference
C
char source_file_format source file format changed from the default values set during initialization, and
C
char source_file_date_time source file date/time stamp
only those which have non-default values will be read from or
C E
char external_file_ref_0 external file references
C E written to the interchange file. See Table 6.
char external_file_ref_1 external file references
C E
char external_file_ref_2 external file references
10.5.1 ms_test_separation_t:— separation method. See
C E
char external_file_ref_3 external file references
Table 7.
C C
char languages x languages
10.5.2 ms_test_inlet_t:—mass spectrometer inlet. See
Long number_times_processed number of times processed
Long number_times_calibrated number of times calibrated
Table 8.
C E
char calibration_history_0 calibration history
10.5.3 ms_test_ioniz_t:—ionization method.SeeTable9.
C E
char calibration_history_1 calibration history
C E
10.5.4 ms_test_polarity_t:—ionization polarity. See
char calibration_history_2 calibration history
C E
char calibration_history_3 calibration history
Table 10.
C
char post_expt_program_name post-experiment program
10.5.5 ms_test_detector_t:—detector type. See Table
name
C
11.
char pre_expt_program_name pre-experiment program
name
10.5.6 ms_test_res_t:—resolution type. See Table 12.
C
char error_log error log
10.5.7 ms_test_function_t:—scan function. See Table
F
Long number_instrument_ (none)
13.
components
A
The E column indicates that this is an enumerated set field. It is recorded in the
interchange file as a string literal, but is represented as an enumerated type in the
data structure.
B
The M column indicates that this is a required field. When reading or writing an
TABLE 3 MS_Instrument_Data
interchange file, an error will be generated if a mandatory field is not filled in.
C
These fields are present in the data structure, but do not need to be filled by the
NOTE 1—There are no enumerated sets associated with MS_
application program when writing an interchange file. The API fills these fields with
Instrument_Data.
the appropriate values. However, on reading a file, the contents of these fields are
filled with allocated strings, and must be freed by the caller.
NOTE 2—All string fields in this structure are restricted to 32 characters
D
(1) Data type is ms_admin_expt_t
(including terminal NULL).
E
These fields are defined in the specification as “string array” types. For
Type Field Name E M Specification Attribute
convenience of the implementation and to conserve space in the interchange file,
they are defined as separate strings here.
Long inst_no x instrument component number
F
A
The number of instrument components is returned in this field only when reading
char name instrument component name
A
an interchange file. It is not used when writing files.
char id instrument component id
A
char manufacturer instrument component manu-
facturer
A
char model_number instrument component model
TABLE 2 Experiment Type
number
A
ms_admin_expt_t char serial_number instrument component serial
number
Value String literal Specification description
A
char comments instrument component id com-
expt_centroid Centroided Mass Spectrum centroided mass spectrum
ments
expt_continuum Continuum Mass Spectrum continuum mass spectrum
A
char software_version instrument component software
expt_library Library Mass Spectrum library mass spectrum
version
A
char firmware_version instrument component firmware
version
A
char operating_system operating system revision
A
char application_software application software revision
each instrument component in turn, and then is written to the
A
interchange file using successive API calls. When reading, the These fields are present in the data structure, but do not need to be filled by the
application program when writing an interchange file. The API fills these fields with
number of instrument components is returned in the MS_
the appropriate values. However, on reading a file, the contents of these fields are
Admin_Data structure. Data for each component is returned
filled with allocated strings, and must be freed by the caller.
with successive API calls.
E2078 − 00 (2016)
TABLE 4 MS_Sample_Data TABLE 6 MS_Test_Data
Type Field Name E M Specification Attribute E M Specification
Type Field name
Attribute
A
char owner sample owner
A
char receipt_date_time sample receipt date/time stamp ms_test_separation_t separation_type x separation
A
char internal_id internal sample id experiment type
A
char external_id external sample id ms_test_inlet_t ms_inlet x mass spectrometer
A
inlet
char procedure_name sampling procedure name
A
char prep_procedure sample preparation procedure Float ms_inlet_temperature mass spectrometer
B
inlet temperature
(1) state x sample state
A
char matrix sample matrix ms_test_ioniz_t ionization_mode x ionization mode
A
char storage sample storage information ms_test_polarity_t ionization_polarity x ionization polarity
A
char disposal sample disposal information Float electron_energy electron energy
A
char history sample history Float laser_wavelength laser wavelength
A
A
char reagent_gas reagent gas
char prep_comments sample preparation comments
A
char comments sample id comments Float reagent_gas_pressure reagent gas
A
pressure
char manual_handling manual handling precautions
A
char fab_type FAB type
A
These fields are present in the data structure, but do not need to be filled by the
A
char fab_matrix FAB matrix
application program when writing an interchange file. The API fills these fields with
Float source_temperature source temperature
the appropriate values. However, on reading a file, the contents of these fields are
Float filament_current filament current
filled with allocated strings, and must be freed by the caller.
Float emission_current emission current
B
Data type is ms_sample_state_t
Float accelerating_potential accelerating
potential
ms_test_detector_t detector_type x detector type
Float detector_potential detector potential
TABLE 5 ms_sample_state_t
Float detector_entrance_potential detector entrance
Value String Literal Specification Description
potential
ms_test_res_t resolution_type x resolution type
state_solid Solid solid
A
char resolution_method resolution method
state_liquid Liquid liquid
ms_test_function_t scan_function x scan function
state_gas Gas gas
state_supercrit Supercritical Fluid supercritical fluid ms_test_direction_t scan_direction x scan direction
ms_test_law_t scan_law x scan law
state_plasma Plasma plasma
state_other Other State other state Float scan_time scan time
A
char mass_calibration_file mass calibration file
name
A
char external_reference_file external reference
file name
10.5.8 ms_test_direction_t:—scan direction. See Table
A
char internal_reference_file internal reference
14. file name
A
char comments instrument
10.5.9 ms_test_law_t:—scan law. See Table 15.
parameter
comments
10.6 Raw Data Information Classes:
A
10.6.1 Raw Data Global Information Class—MS_Raw_ These fields are present in the data structure, but do not need to be filled by the
application program when writing an interchange file. The API fills these fields with
Data_Global.The MS_Raw_Data_Global structure occurs
the appropriate values. However, on reading a file, the contents of these fields are
once per interchange file. The only required field is nscans,
filled with allocated strings, and must be freed by the caller.
the number of spectral scans or library spectra recorded in the
set. See Table 16.
10.6.1.1 ms_data_mass_t:—mass axis units. See Table
17.
read or write library information for experiment types other
10.6.1.2 ms_data_time_t:—time axis units. See Table 18.
than expt_library.As in MS_Raw_Per_Scan, the
10.6.1.3 ms_data_intensity_t:—intensity axis units. See
scan_no variable must be set to the desired scan index before
Table 19.
both reading and writing. An out-of-range index results in an
10.6.1.4 ms_data_format_t:—data format. See Table 20.
error. There are no enumerated types. See Table 22.
10.8.1 Size Restrictions on other Library String Fields
10.7 Raw Data Per-Scan Information Class—MS_Raw_
(including terminalNULL):
Per_Scan.Acopyofthisstructureiscompletedonceforeach
scan in the interchange file. When reading or writing, the entry_id 32 bytes
source_data_file_reference 32 bytes
scan_nofieldisusedtoindicatetheindexnumberofthescan
chemical_formula 64 bytes
(beginning at zero) to be read or written, respectively. Scans
wiswesser 128 bytes
smiles 255 bytes
can be read or written in ascending or descending order;
other_structure 128 bytes
however, an error will occur if a scan number outside the range
retention_reference_name 128 bytes
of one to ( nscans (see MS_Raw_Data_Global, above) is
other_info 255 bytes
specified.
10.9 Raw Data Per-Scan-Group Information Class—MS_
10.7.1 Therearenoenumeratedtypesinthe MS_Raw_Per
Raw_Per_Group. This structure is only used when the scan
_Scan data structure. See Table 21.
function is selected ion detection (function_sid), and occurs
10.8 Library Data Per-Scan Information Class—MS_Raw once per scan group.The group_no variable must be set to the
_Library —This structure occurs once per spectrum, but only desired group index before both reading and writing. An
forexperimenttype expt_library.Forotherexperimenttypes, out-of-range index results in an error.
this structure is not used. An error will result when trying to There are no enumerated types. See Table 23.
E2078 − 00 (2016)
TABLE 7 ms_test_separation_t TABLE 10 ms_test_polarity_t
Value String Literal Specification Description Value String Literal Specification Description
polarity_plus Positive Polarity positive
separation_glc Gas-Liquid Chromatography gas-liquid chromatography
polarity_minus Negative Polarity negative
separation_gsc Gas-Solid Chromatography gas-solid chromatography
separation_nplc Normal Phase Liquid normal phase liquid
Chromatography chromatography
separation_rplc Reverse Phase Liquid reverse phase liquid
TABLE 11 ms_test_detector_t
Chromatography chromatography
Value String Literal Specification Description
separation_ielc Ion Exchange Liquid ion exchange liquid
Chromatography chromatography
detector_em Electron Multiplier electron multiplier
separation_selc Size Exclusion Liquid size exclusion liquid
detector_pm Photomultiplier photomultiplier
Chromatography chromatography
detector_focal Focal Plane Array focal plane array
separation_iplc Ion Pair Liquid ion pair liquid
detector_cup Faraday Cup Faraday cup
Chromatography chromatography
detector_dynode_em Conversion Dynode Electron conversion dynode
separation_olc Other Liquid Chromatography other liquid chromatography
Multiplier electron multiplier
separation_sfc Supercritical Fluid supercritical fluid
detector_dynode_pm Conversion Dynode conversion dynode
Chromatography chromatography
Photomultiplier photomultiplier
separation_tlc Thin Layer Chromatography thin layer chromatography
detector_multicoll Multicollector multi-collector
separation_fff Field Flow Fractionation field flow fractionation
detector_other Other Detector other detector
separation_cze Capillary Zone Electrophoresis capillary zone
electrophoresis
separation_other Other Chromatography other chromatography
separation_none No Chromatography no chromatography TABLE 12 ms_test_res_t
Value String Literal Specification Description
resolution_constant Constant Resolution constant
resolution_proportional Proportional Resolution proportional
TABLE 8 ms_test_inlet_t
Value String Literal Specification Description
inlet_membrane Membrane Separator membrane separator
TABLE 13 ms_test_function_t
inlet_capillary Capillary Direct capillary direct
inlet_opensplit Open Split open split
Value String Literal Specification Description
inlet_jet Jet Separator jet separator
function_scan Mass Scan mass scan
inlet_direct Direct Inlet Probe direct inlet probe
function_sid Selected Ion Detection selected ion detection
inlet_septum Septum septum
function_other Other Function other function
inlet_pb Particle Beam particle beam
inlet_reservoir Reservoir reservoir
inlet_belt Moving Belt moving belt
inlet_apci Atmospheric Pressure atmospheric pressure
TABLE 14 ms_test_direction_t
Chemical Ionization Inlet chemical ionization
Value String Literal Specification Description
inlet_fia Flow Injection Analysis flow injection analysis
inlet_es Electrospray Inlet electrospray inlet
direction_up Up up
inlet_infusion Infusion infusion
direction_down Down down
inlet_ts Thermospray Inlet thermospray inlet
direction_other Other Direction other direction
inlet_probe Other Probe other probe inlet
inlet_other Other Inlet other inlet
TABLE 15 ms_test_law_t
Value String Literal Specification Description
TABLE 9 ms_test_ioniz_t
law_linear Linear linear
Value String Literal Specification Description
law_exponential Exponential exponential
ionization_ei Electron Impact electron impact
law_quadratic Quadratic quadratic
ionization_ci Chemical Ionization chemical ionization
law_other Other Law other law
ionization_fab Fast Atom Bombardment fast atom bombardment
ionization_fd Field Desorption field desorption
ionization_fi Field Ionization field ionization
ionization_es Electrospray Ionization electrospray ionization
ionization_ts Thermospray Ionization thermospray ionization 11.1.4 Reading and writing per-scan raw and library data,
ionization_apci Atmospheric Pressure atmospheric pressure
11.1.5 Data structure initialization and clearing, and
Chemical Ionization chemical ionization
11.1.6 Utility routines.
ionization_pd Plasma Desorption plasma desorption
ionization_ld Laser Desorption laser desorption
11.2 There are some additional API functions of lesser
ionization_spark Spark Ionization sparkionization
importance; these are not required for normal use of the
ionization_thermal Thermal Ionization thermal ionization
ionization_other Other Ionization other ionization
protocol, but are described for completeness.
11.2.1 Note that, the header file “ms10.h” referenced below
existed in earlier, preliminary, non-ASTM implementations
11. Application Programming Interface also named “ms11.h” and subsequently “ms12.h”. It was
finally named, perhaps confusingly, “ms10.h” to indicate a
11.1 There are a number of commonly used functions
version “1.0” for the originally intended AIA standard.
available in the application programming interface. These are
grouped as follows: 11.3 File Open and Close—Interchange files are opened
11.1.1 Opening and closing interchange files, either for reading or writing. On most operating systems,
11.1.2 Reading and writing global data, opening a file for writing will destroy any existing file of the
11.1.3 Reading and writing per-component instrument data, same name (on VMS, a new version is created). A file opened
E2078 − 00 (2016)
TABLE 16 MS_Raw_Data_Global TABLE 19 ms_data_intensity_t
Type Field name E M Specification Attribute Value String Literal Specification Description
Long nscans x number of scans intensity_counts Total Counts total counts
Long starting_scan_no starting scan number intensity_cps Counts Per Second counts per second
A
Int has_masses (none) intensity_volts Volts volts
A
Int has_times (none) intensity_current Current current
B
Double mass_factor mass axis scale factor intensity_arbitrary Arbitrary Intensity Units arbitrary units
B
Double time_factor time axis scale factor intensity_other Other Intensity other units
Double intensity_factor intensity axis scale
B
factor
C
Double intensity_offset intensity axis offset
TABLE 20 ms_data_format_t
ms_data_mass_t mass_units x mass axis units
ms_data_time_t time_units x time axis units
Value String Literal Specification Description
ms_data_intensity_t intensity_units x intensity axis units
A
data_short Short short (16-bit signed integer)
ms_data_intensity_t total_intensity_units x total intensity units
B
data_long Long long (32-bit signed integer)
ms_data_format_t mass_format x mass axis data format
data_float Float float (32-bit floating point)
ms_data_format_t time_format x time axis data format
data_double Double double (64-bit floating point)
ms_data_format_t intensity_format x intensity axis data format
A A
char mass_label mass axis label
Default for mass and time data.
A
B
char time_label time axis label
Default for intensity data.
A
char intensity_label intensity axis label
D
Double mass_axis_global_min mass axis global range
D
Double mass_axis_global_max mass axis global range
D
Double time_axis_global_min time axis global range
functionsdomuchmorethanopenthefile;theyreadinorwrite
D
Double time_axis_global_max time axis global range
out NetCDF dimension names and sizes and variable names
Double intensity_axis_global_ intensity axis global
D
and dimensionalities, respectively, and place the file in the
min range
Double intensity_axis_global_ intensity axis global
appropriate mode for further operations.
D
min range
11.3.1 ms_open_read—open an interchange file for read-
D
Double calibrated_mass_min calibrated mass range
D
ing:
Double calibrated_mass_max calibrated mass range
Double run_time actual run time
Double delay_time actual delay time
Syntax:
Short uniform_flag uniform sampling flag
A
char Comments raw data global #include “ms10.h”
comments
int ms_open_read ( char * filename )
A
These fields are used only when reading an interchange file, and indicate the
presence of mass or time data, or both, in the interchange file. This allows
Description:
applications to set up in advance to receive mass or time data or both.
B
The ms_open_read routine opens the interchange file
Scale factors default to 1.0. Scale factors are used as follows: When reading
data arrays, the values returned in the arrays should each be multiplied by the
named by filename and associates a file identifier with it.Any
respective scale factor to obtain the true values. When writing data arrays, the
dimensions and variables defined in the file are read into
scale factor represents the divisor applied to the true values to obtain the values
internal API data structures. The file must exist, be readable,
recorded in the interchange file. In either case, the numbers present in the mass,
time, and intensity values arrays (see MS_Raw_Per_Scan data structure, below)
and be an interchange format file.
represent the scaled, not the true values. The application is responsible for
performing the appropriate scaling when reading or writing.
C
The intensity axis offset defaults to 0.0. There are no offsets for the time or mass Return values:
axes. When reading, the offset should be added to the recorded intensity values
If successful, the ms_open_read routine returns a non-
(after scaling) to obtain the true intensity values. When writing, the offset should
negative int file identifier for use in subsequent API calls. On
be subtracted from the true values (before scaling).
D
These fields are defined in the specification as ranges; for convenience of
error, the routine returns the error code MS_ERROR (defined
implementation, they are split into separate variables for minimum and maximum
in ms10.h).
values.
11.3.2 ms_open_write—open an interchange file for writ-
ing:
TABLE 17 ms_data_mass_t
Syntax:
Value String Literal Specification Description
#include “ms10.h”
mass_m_z M/Z m/z
int ms_open_write ( char * filename , ms_admin_
mass_arbitrary Arbitrary Mass Units arbitrary units
mass_other Other Mass Units other units
expt_t expt_type, long nscans, long ninst, ms_data_
format_t mass_fmt, ms_data_format_t time_fmt, ms_
data_format_t inty_fmt, int has_masses, int has_times)
TABLE 18 ms_data_time_t
Value String Literal Specification Description
Description:
time_seconds Seconds seconds
The ms_open_write routine creates and opens the inter-
time_arbitrary Arbitrary Time Units arbitrary units
changefilespecifiedbyfilenameandassociatesafileidentifier
time_other Other Time Units other units
with it. The NetCDF dimension and variable definitions are
written to the file, then the file is placed in data recording
mode. The application must have the file system permissions
for reading must already exist. There are two file open API necessary to create and write to the file.
calls, one for read access and one for write access. These The other arguments are:
E2078 − 00 (2016)
TABLE 21 MS_Raw_Per_Scan TABLE 22 MS_Raw_Library
Type Field name E M Specification Attribute
NOTE1—Mass,time,andintensityarraysaredeclaredas void *.Inuse,
Long scan_no x (none)
however, they are declared as arrays of type appropriate to the mass, time,
A A
char entry_name x entry name
and intensity data format (see MS_Raw_Data_Global
...