file: 00README G. Moody 3 February 2009 This directory contains software for converting MIMIC II Clinical Database logs between the available formats. See http://physionet.org/physiobank/tutorials/using-mimic2/ for background and details about MIMIC II logs. These files are included here: logtxt.c converts annotation logs to text logs txtlog.c converts text logs to annotation logs loghtml.c converts annotation logs to HTML logs mimic2.h functions to convert source codes to strings and back Makefile 'make' description file to automate compilation 00README this file To compile the software in this directory: 1. Install the WFDB Software Package (see http://physionet.org/physiotools/wfdb.shtml). 2. If your version of the WFDB Software Package is earlier than version 10.4.13, copy wfdblib.h from the lib subdirectory of the source tree into the same directory where wfdb.h is installed (in a default installation, this will be /usr/include/wfdb/). 3. Return to this directory and run "make". Doing so will produce three executable programs (logtxt, txtlog, and loghtml). To use these programs, put them somewhere in your execution PATH, then (in a terminal window) type their names without command-line arguments for (very) brief instructions on using them. The rest of this note provides more detailed instructions. logtxt ====== This program reads an annotation log (and its accompanying header file) and creates a text log on the standard output containing the same information. For example, the command logtxt -r s00318 -a log >s00318.txt creates the text file s00318.txt, from the information contained in s00318.log (the annotation log file) and s00318.hea (the header file). In this example, "s00318" is the record name, and "log" is the annotator name; note that the -r and -a options of all of the programs described here are followed by record and annotator names, not by filenames. Annotation files are binary files that contain time intervals and additional information. Annotation files do not contain absolute timestamps. A header file is a short text file that specifies the base timestamp used in the annotation file; it is needed in order to calculate the timestamps in the log from the information recorded in the annotation file. This also implies that all of the timestamps can be shifted equally, simply by changing the base timestamp in the header. Note that, like all other WFDB applications, logtxt finds its annotation and header input files by searching the WFDB path, which begins by default in the current directory. If the inputs are not found in the first location, they are sought in the second one, etc. By default, the second location is /usr/database (this may vary if you chose a non-standard WFDB path when installing the WFDB Software Package, or if you set the WFDB environment variable explicitly), and the third location is http://physionet.org/physiobank/database Since the annotation logs for the MIMIC II Clinical Database are found within http://physionet.org/physiobank/database/mimic2cdb/ it is possible for logtxt (and any other WFDB application) to read the same input files as in the example above, but directly from the PhysioNet web server, by specifying the record name as 'mimic2cdb/s00318/s00318', like this: logtxt -r mimic2cdb/s00318/s00318 -a log If you run the command above exactly as shown, a great deal of output will appear in your terminal window. If you want that output to be written to a file, redirect it as in the previous example, using the syntax ">desired-output-file" (without the quotation marks). There are a few useful options that can be used when running logtxt. First, you can select log entries that occur only after a time you choose, using the -f option, like this: logtxt -r mimic2cdb/s00318/s00318 -a log -f "[11:00:00 14/07/2009]" If the time you choose follows the last entry in the log, no output will appear. Note that the timestamp must be quoted in the example above (otherwise, the shell interprets the brackets and the embedded space character in the timestamp before logtxt starts). It's also possible to provide the time elapsed from the base date/time in the header instead of an absolute timestamp: logtxt -r mimic2cdb/s00318/s00318 -a log -f 35:00:00 In this case, since the base timestamp is [00:00:00 13/07/2009], the elapsed time given (35 hours, 27 minutes, and 0 seconds) is equivalent to the absolute timestamp in the previous example, and the output of this command will be the same as that of the previous one. Similarly, you can select log entries that occur only before a time that you specify using the -t option, as in: logtxt -r mimic2cdb/s00318/s00318 -a log -f 35:00:00 -t 35:30:00 The -f and -t options can be used together, as in this example, or one at a time. Finally, you can select only entries with a specific source code, using the -s option and the two-character mnemonic source code of interest, as in this example, which also uses -f and -t to specify a time interval of interest: logtxt -r mimic2cdb/s00318/s00318 -a log -f 35:00:00 -t 35:30:00 -s me A list of the two-character source codes appears at: http://physionet.org/physiobank/tutorials/using-mimic2/#log-sourcecodes txtlog ====== This program does the inverse of what logtxt does: it reads a text log from its standard input, and creates an annotation file (and an accompanying header file), with record and annotator names specified by command-line arguments. The annotation file contains the same information as the text file, provided that the text file is properly formatted. Specifically, the text file must contain timestamps in the correct format, valid two-character source codes, and no more than about 270 characters per line. The first entry must have the earliest primary timestamp in the log. It is not necessary, however, for the remaining entries to appear in chronological order; any out-of-order entries will be written in chronological order in the output annotation file. For example, the command txtlog -r s00318 -a log s00318.html You can select a time interval and/or a source code of interest using -f, -t, and -s options as for logtxt, so, for example: loghtml -r mimic2cdb/s00318/s00318 -a log -f 35:00:00 -t 35:30:00 -s me produces an HTML version of the same log entries as selected in the final logtxt example above. (The HTML is written to the standard output; you will not want this in your terminal window, so redirect it to a file as discussed above. To see it as intended, open the file with your favorite web browser.) The top of the HTML file will contain links to text and annotation logs that do not exist unless you have created them (using logtxt and/or txtlog, for example). Provided that the MIMIC II code dictionaries are available, loghtml translates the encoded numeric values in cg, cu, de, id, and io name-value pairs into strings that should be more comprehensible. If you wish to improve the translations, download your own copies of the code dictionaries from http://physionet.org/physiobank/database/dictionaries/ and edit them to taste, then install them in a "dictionaries" subdirectory within some location in your WFDB path that occurs before the PhysioBank database directory, such as /usr/database/dictionaries/. (If you find typographical or other errors in the dictionaries, please send us corrections!) If you do not wish to have the encoded values translated, use the -e option when running loghtml, and they will appear untranslated in the HTML output.