3. DATA FILE AND COMPUTER TAPE INFORMATION 3.1 GUIDE [GUIDE, 4] 3.1.1 Introduction to Tape Organization A single data set is referred to as a data file. Each separate data file comprises one computer tape file. Sections of informational text such as the data descriptions and data file and computer tape information are also divided into distinct computer tape files. Section 2, the Data Description (tape file 3) contains brief descriptions of each atmospheric area covered by the Handbook data files: definition of data file variables, ranges, and units, listing of data file names, and description of data source. Section 3.1, the Guide, (tape file 4) gives general user notes and technical information needed to access or understand the computer tape, data files, and computer programs. Section 3.2, Data File Formats (tape file 5), summarizes technical information on each data file in tabular form: data file variable definitions, units, and ranges in the order in which they appear on each line of a given data file, FORTRAN format statements used to create the data files, temperature, source, and computer tape file number. Appendix A (tape file 0) contains a list of all data files on the Handbook tape along with their corresponding tape file numbers. Appendix B (tape file 9) briefly describes the contents of single or groups of files on the tape. The computer programs for retrieving attenuation coefficient data and microwave refractive index data are located in tape files 171-187 and 188-217 respectively. There are numerous cross references throughout the Handbook between section name and number and tape file name and number, both at the beginning of a section and within the text. In general, tape file name (in capital letters) and number are given in brackets following a section name. A typical use of the Atmospheric Handbook might entail three steps: (1) Find the area of interest in the table of contents. Look up and read about your topic in the data description, section 2. Take note of the pertinent file name(s). (2) Read through the Guide until any general technical questions you may have are answered and you are familiar with the data file formats, notation, and composition. Look up the specific format, parameter, and tape file number information on your desired files in Data File Formats. (3) Load the file(s) from the tape onto your disk. 3.1.2 Data File Structure Each tape file corresponds to a single data file. In general, sections of files are grouped according to atmospheric area. All tape files contain no more than 80 characters per line. Numerical values in the data files are arranged in increasing order, where applicable. Data values of "-1" indicate the value was not given in the original source. The first line of all data files, except those associated with programs ATTENCOEF and MICRO, is informational text, in most cases identifying the data type, substance, and source. Precaution should be taken to read over or delete this line when accessing disk files after they have been loaded from the tape. 3.1.3 Deciphering File Names File names consist of capital letters, numbers, and the delimiter "X". The "X" is used as one might use a period to visually, or logically, break up the parts of information used in naming files. Within the informational text of the Handbook, three types of abbreviating methods are used to refer to sets of data files with similar names. A "+" following a file name and preceding a parenthesized set of numbers indicates an alphanumeric extension; it is not part of the actual file name; e.g. "FIL+ (1A,2,3)" refers to three files, "FIL1A", "FIL2", and "FIL3". A "+" following a file name not followed by a parenthesized set of numbers indicates an alphanumeric extension of some type; the specific type isn't pertinent in the given context. A file name ending in the character set "E,O", such as "FILE,O", actually refers to two separate data files, "FILE" with data for the Extraordinary ray, and "FILO" with data for the Ordinary. An entry such as "FIL1 - 4" refers to four distinct files; the dash is not part of the actual data file name. On some computer systems the length of the file names as given will be too long. All data file names are intended only as suggestions. At the time of loading a file from the tape onto disk, the naming of the file is at the discretion of the user. The refractive index data file name prefixes "RF", "RFI", and "RFC" refer to real, imaginary, and complex refractive index data sets, respectively. 3.1.4 Unit Notation All Handbook data files are uniformly in Systeme Internationale Units ("MKS": Meters, Kilograms, Seconds) with the exception of: the attenuation coefficient data files, for which altitude is measured in kilometers, and absorption and scattering are measured per kilometer; and the standard atmosphere data files for which altitude, pressure, temperature, and density are measured in kilometers, millibars, kelvins, and molecules per cubic centimeter, respectively. A double asterisk, "**", stands for "raised to the power of", e.g., "m**-3 m**-1" means "per meter cubed per meter". In a numerical context, the letter "E" refers to exponent, e.g., "2.5E-3" means "2.5 X 10**-3", where "X" is multiplication. 3.1.5 Significant Figures In instances where our data sources reported an error estimate for their experiments, this estimate was included in the data description. Our refractive index and relative reflectance data have six digits after the decimal. This large number of significant figures was implemented to ensure sufficient space for increased accuracy in the event of interpolation on small computer systems. In most cases the refractive index data are good to 3 or 4 decimal places. Generally, Handbook data with 4 digits after the decimal can be considered significant to 2 to 3 places, unless otherwise specified. The original source should be consulted by those to whom the accuracy precision is important. The number of figures quoted in the tables is not a good guide to significance. 3.1.6 Computer Programs: ATTENCOEF (files 171-187) and MICRO (files 178, 188-217) Program ATTENCOEF gives the attenuation coefficients as a function of altitude for five atmospheric and two aerosol models. The altitude range is 0 to 85 kilometers, and wavelength = 0.6943 micrometers. Program MICRO gives the refractive indices for select water and ice data in the microwave region. Both programs were written following standard FORTRAN 77 guidelines; however some Data General FORTRAN V options were used. The drivers of both programs list all non-standard FORTRAN characteristics; for easy identification their occurrences within the program are delimited by a "C" in column one followed by a series of "+" signs. Additionally, non-standard format codes are listed by their statement label in the comment section at the beginning of each subroutine. Make sure to load all the files belonging to a program from the tape or the programs won't run. Additional ice refractive index data for the micro- wave region, located in files 222-225, were acquired after the completion of program MICRO, and thus are not available to the user through the program. Program ATTENCOEF will request the following information: (1) ATTENCOEF retrieves attenuation and scattering coefficients using user-entered parameters for atmospheric and aerosol types, and altitude. Do you want to enter each set of these three parameters individually, or multiply into an array? The maximum length for this array is 100. (2) Would you like your results typed to the screen, sent to a diskfile, or both? When either of the diskfile options are used, input is sent to one standard diskfile. Care should be taken to rename this file before subsequent runs of the program occur. (3) What atmospheric type: tropical, midlatitude summer, midlatitude winter, subarctic summer, or subarctic winter? (4) What altitude(s) in the 0.0 to 85.0 km range? (5) What aerosol type: clear or hazy? (6) You may be asked to make a choice between the coefficients nearest the altitude requested or the values derived from using a linear interpolation which approximates these coefficients by using available heights. (7) If (in response to question 1) you have been entering data parameters singly, after you receive the attenuation coefficients requested you may a) continue, using a different altitude, b) continue, using a different atmosphere, c) continue, but transfer to array entry mode, or d) terminate. If already in array entry mode, once your data parameter array has been exhausted, you may either start over in the entry mode of your choice or terminate. Program MICRO will request the following information: (1) Would you like your results typed to the screen, sent to a diskfile, or both? If either of the diskfile options are used, output is sent to one standard file. Care should be taken to rename this file before subsequent runs of the program occur. (2) Do you want refractive indices for water or ice? (3) The refractive indices are separated according to temperature and then sorted by wavelength. Do you want to request each temperature individually, or enter multiple temperatures into an array? Temperatures are in degrees C. (4) You will be shown the entire data file for each temperature requested. If using the diskfile option, you may have this entire file sent to disk. You will be asked if you would like interpolations between any of the wavelengths shown. These wavelengths must be entered in meters. Because of the spareness of data in the microwave region, interpolation may not be accurate. (5) If you have been entering temperatures singly, you have the choice to repeat step 4 with another temperature. Otherwise, you have the choice to repeat steps 2-4 or to terminate. The effort to make these programs easily adapted by computer systems other than the one it was written on resulted in cumbersome interactive user-input formats. Special care must be taken to enter data exactly as specified in the programs' main routines. The parameter lists for subroutine and function statements and calls in programs ATTENCOEF and MICRO were based on specifications as described in "A Technique for Making FORTRAN Programs More Readable" (J. Tant Priestley, NOAA/Wave Propagation Laboratory, unpublished). All parameter lists are divided into, and conform exactly with, the following categories: inputs, inputs/outputs, outputs. Priestley defines these categories: (1) Input - arguments that transmit information into the subprogram but whose values remain unchanged on output. (2) Input/Output - arguments used to transmit information both into and out of the subprogram, plus any other arguments that do not fit into categories 1 or 3. (3) Output - arguments that transmit information out of the subprogram but no information into the subprogram; their values on input are irrelevant. To distinguish between the three argument categories when referencing subprograms, the arguments are ordered according to category, and the categories separated by spaces. Priestley gives the following rules to ensure an unambiguous and uniform use of spaces: inputs are followed by a space, inputs/outputs are bracketed by spaces, and outputs are preceded by a space. Any double spaces are merged into a single space. Note that it is each category, not each individual argument, that is delimited by a space. Consult the main routines of each program for examples and additional useful information. 3.1.7 Data Retrieval Example "I have briefly read the Handbook Guide. I would like some microwave refractive index data for ice. How do I find it?" Looking at the Contents, note that section 2.7.3 contains the description of data for the refractive indices of ice in the optical, infrared, and microwave regions, and section 3.2.7.3 contains the data file format information. In 2.7.3 read about the sources of the data. Notice that there are two sets of microwave data, one which is handled by program MICRO. In 3.2.7.3, the entry key explains the data files' variables and their units, and the format key shows the FORTRAN format statements use to create the files. Check the wavelength and temperature ranges that the data files cover, and note the data file tape file numbers. Then turn back to the Guide to read the section on using program MICRO, which will retrieve select data. The final step is to load the desired files from the tape onto your disk. 3.1.8 Data Table Examples File Name, Entry Key, and Range information was taken from "Data File Formats" (section 3.2) and is not part of the data file. The first line of the data file contains identifying information in capital letters. File Name: RFXQUA2 Entry Key: Sequence #, Wavelength(m), wavenumber (cm**-1), Real Refractive Index (dimensionless) Range: 1.6E-4 to 3.49E-3 meters REFRACTIVE INDICES: SYNTHETIC QUARTZ, 47 DEGREES F. (LAIKIN) 1 1.596060E-04 6.265430E 01 1.760350E 00 2 1.616580E-04 6.185900E 01 1.750650E 00 3 1.644390E-04 6.081282E 01 1.738620E 00 4 1.647690E-04 6.069102E 01 1.737310E 00 5 1.651790E-04 6.054040E 01 1.735740E 00 6 1.849500E-04 5.406880E 01 1.677210E 00 7 1.942300E-04 5.148540E 01 1.659060E 00 8 2.378320E-04 4.204660E 01 1.608930E 00 9 2.536520E-04 3.942413E 01 1.598390E 00 10 2.652040E-04 3.770683E 01 1.592110E 00 (etc.) --------------------------------------------------------------- File Name: MLS Entry Key: Sequence #, Altitude (km), Pressure (mb), Temp. (K), Density (mols cm**-3) for H2O,CO2,O3,N2O,CO,CH4,O2,N2 Range: 0 to 100 km STANDARD ATMOSPHERE - MIDLATITUDE SUMMER 1 .0 1.0730E 03 2.9400E 02 4.6810E 17 8.0840E 15 7.5300E 11 6.8590E 12 1.8370E 12 3.9190E 13 5.1320E 18 1.9130E 19 2 1.0 9.0200E 02 2.9000E 02 3.1100E 17 7.3340E 15 7.5300E 11 6.2230E 12 1.6670E 12 3.5560E 13 4.6560E 18 1.7360E 19 3 2.0 8.0200E 02 2.8500E 02 1.9730E 17 6.6630E 15 7.5300E 11 5.6540E 12 1.5140E 12 3.2310E 13 4.2300E 18 1.5770E 19 4 3.0 7.1000E 02 2.7900E 02 1.1030E 17 6.0480E 15 7.7810E 11 5.1320E 12 1.3750E 12 2.9320E 13 3.8400E 18 1.4310E 19 5 4.0 6.2800E 02 2.7300E 02 6.3530E 16 5.4790E 15 8.0320E 11 4.6490E 12 1.2450E 12 2.6570E 13 3.4780E 18 1.2970E 19 (etc.)