Read Me

README to cdfread
Document revision date: 2021-10-30.
===================================

NAME

cdfread - a program to read single mass spectra and mass chromatograms
          from data files in netCDF (Andi-MS) format.


SYNOPSIS

        cdfread [-v] [-h] [-i] [-m] [-g /path/to/gnuplot]
                [-p peakwidth] datafile.cdf


DESCRIPTION

'cdfread' is a program that implements the routines to read individual
mass spectra and mass chromatograms (with variable width) from data
files in netCDF format.

The main purpose of the program is to provide platform-independent
routines to read data files in the netCDF format. This program is
NOT a full-fledged data evaluation suite - it has inly a simple user
interface, and a simple graphic display that relies on gnuplot.

If you are not working with mass spectrometry, if you are neither
chemist nor physicist, then this program is probably not for you ;-)


LICENSE

This program and its documentation are Copyright (C) 2001...2009 by Joerg Hau.

This program is free software; you can redistribute it and/or modify it under
the terms of version 2 of the GNU General Public License ("GPL") as published
by the Free Software Foundation. See the file LICENSE for details.

If you use this program (or *any* part of it) in another application, note
that the resulting application becomes also GPL. In other words, GPL is a
"contaminating" license.

This program is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License (file
LICENSE) for more details.


OBTAINING THE PROGRAM

The latest version can be obtained from the project homepage 
on sourceforge.net:

    http://cdfread.sourceforge.net/


FILES

    README              The file you are just reading.
    README.WIN32    	Information for compiling cdfread under MS Windows.
    LICENSE		The license (GPL).
    src/cdfread.c	The 'C' source code for cdfread

To install, just copy the executable to any location you desire.


WHAT ELSE DO YOU NEED?

The graphic display makes use of gnuplot (http://www.gnuplot.info/), a free 
software for scientific data plotting. Please use version 4 or later.



RUNNING THE PROGRAM

The program is invoked by typing its name and that of the file to be
read on the command line:

	cdfread /path/to/my/datafile.cdf

There are some command-line options:

	-h      shows a short Help screen and exits.

	-m      disables the use of the mouse in the display (gnuplot).
            This as provided for compatibility with older versions
 		    of gnuplot (mouse functionality in gnuplot is available
		    from version 3.8 onwards).

	-v      be verbose: gives a lot of additional information from
		    the data file. Make sure the window is long enough ;-)

	-i      information only. Same as -v, but without graphics.
		    Good for obtaining info from the file, e.g. in batch mode.

	-p x    read chromatograms with a window of +- 'x'/2 amu around
		    the given mass. The default is 1.0 (i.e. +- 0.5 units),
		    which corresponds to most commercial data systems.

    -g /path/to/gnuplot
            if gnuplot is not in your PATH, you can specify its location
            using the "-g" switch. Note that under MS Windows you have to
            specify the "pgnuplot.exe" file (not "gnuplot.exe"), as
            MS Windows is not a POSIX compliant environment.

            A typical MS Windows batch file would look as this:

                cdfread.exe -g c:\apps\gnuplot\pgnuplot.exe %1

            You simply drag-and-drop a datafile on this batch file.

The program opens the data file and enters a "dialog mode". As mentioned
above, the "user interface" provided here is rather primitive and was
written mainly for testing purposes. Type "q" to quit, "h" for help, and
follow the instructions on the screen ;-)

When the program exits, one of the following exit codes is passed to the
operating system:

	0 program execution was successful,
	1 no file specified, or wrong command line option,
	2 problem reading the cdf file,
	3 problem communicating with gnuplot
	4 internal error occurred (memory allocation etc.).



NOTES

Reading mass chromatograms can be very slow. This is due to the structure
of a netCDF file, which is "spectrum-focused" and does not allow a simple
reconstruction of individual mass chromatograms. Instead, all spectra have
to be read and processed sequentially.

The x-axis keeps the settings from the previous zoom or display operation.
Use "x" to reset ("unzoom") the scale to the mass/scan range specified
inside the CDF file.

The program makes use of gnuplot to display data. If you use gnuplot 3.8
or later, there is mouse support ... you can use the mouse to:

  - zoom in with the right mouse button

  - while the cursor is on the display window: type "p" to unzoom
    to the previous zoom level, "n" to re-zoom, "u" to fully unzoom,
    "h" for help. See the gnuplot help file for details.

  - annotate the current cursor position using the middle mouse button
    (to erase an annotation, use Ctrl-MB2)

There is no "really interactive" display/processing ... as I said, this
is NOT a full-fledged data evaluation suite.

The MS-Windows port is not fully explored is mainly provided for convenience.



RE-COMPILING

If you want/need to recompile, you need (besides a C compiler ;-) some more stuff:

- The netCDF library. The current release of netCDF is available from
  Unidata at ftp.unidata.ucar.edu, in the /pub/netcdf directory.

  A number of pre-built libraries for different OS are located at the same
  server in the /pub/netcdf/contrib tree. For MS-Windows, pre-compiled
  NetCDF 3.4 libraries are kindly provided by Arlindo da Silva (NASA/GSF
  1998), ftp://niteroi.gsfc.nasa.gov/pub/djgpp/netcdf/. Read the README file!

- The public part of the original ANDI-MS (netCDF) distribution, which
  is available at http://andi.sourceforge.net. It contains the documents 
  for the ANDI/MS specification, C source code for reading/writing ANDI/MS 
  files, and test data sets from a number of manufacturers. According 
  to David Stranz, this code dates from 1994 and has not been updated since.

- optinally, the GNU readline library.

- If you compile under MS Windows, read the file README.WIN32 first.


(1)  Build (if necessary) and install the netCDF libraries,
     e.g. in /usr/local.

(2)  Put ms10aux.c, ms10enum.c and ms10io.c (from the ANDI-MS
     distribution) together with cdf2msg.c into one directory.
     Compile these auxiliary files to obj code:

	    gcc -c -O3 ms10aux.c ms10enum.c ms10io.c

(3)  Compile and link with cdfread.c (put this all on one line):

	    gcc -O3 -Wall -o cdfread cdfread.c ms10aux.o ms10enum.o \
		    ms10io.o /usr/local/lib/libnetcdf.a

(3a) If you want to use the GNU readline library, add "-lreadline":

	    gcc -O3 -Wall -o cdfread cdfread.c ms10aux.o ms10enum.o \
		    ms10io.o -lreadline /usr/local/lib/libnetcdf.a

(3b) If you compile under MS Windows, read README.WIN32 first. Then,
     change the executable's name to "cdfread.exe" and #define WIN32:

	    gcc -O3 -DWIN32 -Wall -o cdfread.exe cdfread.c ms10aux.o \
            ms10enum.o ms10io.o -lreadline /mingw/lib/libnetcdf.a

This was tested without problems with gcc under Linux and MSYS+MinGW
under MS Windows.



GOING FURTHER

If you want to use the extracted data with other software, note that
all "intermediate" data are written to plain ASCII files. As you have
the source code, you may want to modify the program to store these data
to a "permanent" file and in any desired format.

The four functions

	open_cdf_ms()
	close_cdf_ms()
	readscan()
	readchro()

form the 'core' of this application. They have been pretty well tested
and should not need any modification. Most of the error checking is
done inside these routines.



GETTING CDF FILES

To get CDF files from your data acquisition package:

- Micromass MassLynx: Start > Programs > MassLynx > DataBridge.
- Finnigan Xcalibur: "Roadmap View" > Tools > File Converter.
- Finnigan ICIS2: ICIS Executive > File > Convert > "DAT to ANDI-MS".
- Agilent ChemStation: File > "Export MS Data to AIA"; there is also a
                       batch mode from the same menu.
- Sciex Analyst: Reportedly there is a macro available upon request from Sciex.
- (others? Please contribute if you can ...)


ACKNOWLEDGEMENTS

- David Stranz (for pointing me to the initial ANDI-MS distribution and code)
- Herbert Kratky (for useful hints on compiling)
- Arlindo da Silva (for making his pre-compiled libraries publicly available)
- Unidata (for making all the nice netCDF stuff available)
- Jonathan Katz (for great inspiriation around the menu)
- Ethan Merritt (for valuable gnuplot hints)
- Steve Cepa (for various manufacturer's CDF conversions)



HISTORY

2001-05-xx: First draft written by JHa.
2001-09-18: First public release.
2003-04-15: Included mouse commands for gnuplot.
2003-08-13: Added some more error checks.
2003-09-15: Additional error check on gbnuplot start.
            Support for mouse zoom.
	        Support for annotation with middle mouse button.
2003-06-17: Added "-i" command line switch.
2003-09-25: changed peakwidth from "-w" to "-p".
    	    Added GNU readline() and a "menu" (inspired by from "comspari.c").
	        Added mouse label functionality.
2003-10-06: added "?" key in dialog engine.
2003-11-02: added WIN32 stuff (JHa)
2004-03-25: updated documentation about obtaining netCDF files (JHa)
2006-11-15: updated documentation about header files on sourceforge.net (JHa)
2009-03-07: updated documentation to reflect hosting on sourceforge (JHa). 
            License now GPL *v2*
2021-10-30: updated contact info in the documentation (JHa)


BUGS

Switching from SPEC to CHRO does not erase previous annotations.

If you find any bugs or observe some "behaviour" that is not mentioned in 
the manual, please file a bug report via the sourceforge.net project page.

If possible, submit not only a bug report but also a bug fix ;-),


AUTHOR

	Dr Jörg Hau, PMP
	Route du Marchairuz 29
	CH-1188 St-George
	Switzerland
	code at schweizerschrauber.ch

Thank you for your interest, and ... have fun!

--eof--