.TH v.apply.census .SH NAME \fIv.apply.census\fR \- Calculate/Import Demographics from Census STF1 Files .br .I "(GRASS Vector Program)" .SH SYNOPSIS \fBv.apply.census\fR .br \fBv.apply.census help\fR .br \fBv.apply.census [-d] [-p] [-l] [-u]\fR .br \fBv.apply.census input_stf1=name [out=name] [ef=name] [formula=mapname=expression] [name_field=name] [zone=value] [spheroid=name]\fR .br .nf Flags: .IP -d 5 Output IDENTIFICATION SECTION to stdout (20 pages) .sp -0.5 .IP -p 5 Output STF1 MATRIX TABLE to stdout (30 pages) .sp -0.5 .IP -l 5 Output PL94-171 MATRIX TABLE to stdout (1 page) .sp -0.5 .IP -u 5 Output STF1 SUMLEV TABLE to stdout (4 pages) .IP Note: 7 Only the first flag given will be executed; the program exits after sending one table to stdout. Other parameters are ignored. .IP Parameters: .IP input_stf1 12 Path/name of STF1 or PL94 input file .sp -0.5 .IP out 12 Type of output: site | atts | table:Lxxx | - (stdout) default: - .sp -0.5 .IP ef 12 Path/name of text file with formula expression(s) .sp -0.5 .IP formula 12 map=expression .sp -0.5 .IP name_field 12 field name for parsing stdin lines (-a to ignore) default: -a .sp -0.5 .IP zone 12 UTM zone number; default is location zone options: 1-60 default: 10 .sp -0.5 .IP spheroid 12 Spheroid for LL to UTM conversion; see m.gc.ll default: clark66 .fi .IP NOTE: Only one of the "ef" or "formula" input fields may be used. .SH DESCRIPTION This program reads a previously selected subset of STF1 or PL94-171 U.S. Census Bureau demographic records (see \fIm.in.stf1.tpe\fR and \fIm.in.stf1.db3\fR), and writes one of the following: .nf GRASS site list (coordinates and a value). GRASS vector polygon attribute labels file (coordinates and a label value). Text report to stdout in one of two formats. .fi Any arithmetic expression combining constants with any of the more than 900 hundred demographic (numeric) fields can be defined and will be evaluated (by the Unix \fIbc -l\fR utility) to compute the value for each input record. The location coordinates for the polygon label point or the site location is obtained from certain columns (269-287) in the input records, making this program quite specific for the specified types of STF1 and PL94-171 input file records. Use with other types of input data is not advised. .SH SOME PARAMETERS EXPLAINED BRIEFLY .nf out= att for results to vector map attribute file site for results to site list - for results to stdout; this is the default table: for results in table form to stdout with the column value(s) represented by the ':Lxxx:Lxxx' string preceeding the expression value instead of easting and northing. Lxxx is in same choice of representation as column designation in formula (see below). formula= mapname=Computation with STF1A columns, constants and \fIbc\fR operators (see below). mapname of vector or site map to make is required in all cases (but ignored for '-' or 'table:' output modes). name_field= name is Keyword in stdin stream preceeding the number of a STF1 record to read from input_stf1 file. The number is a physical sequence number, not a record identification number. This parameter is appropriate only in special uses of this program. If '-a' is given, or this parameter is omitted, all records in STF.file will be processed. .fi .SH THE "formula" PARAMETER The string after the '=' in this parameter almost always must be enclosed in quotes to protect it from Shell interpretation of characters such as * / ( ) and spaces (which may be used to increase readability, but are not necessary). This string is always of the form \fImapname=expression\fR. The \fImapname\fR string can be any legal GRASS map name (up to 14 characters). The second '=' is required and may be preceeded and followed by a space. In the \fIexpression\fR, great flexibility is provided for the computation of interesting combinations of the data fields contained in the demographic records. The usual operators used in the \fIexpression\fR include: +, -, *, /, and %. The user should review the Unix manual entry for the \fIbc\fR calculator for the complete list of available functions and other operators. Parentheses are used in the normal algebraic manner. The operands in the \fIexpression\fR may consist of any mixture of: integer constants real constants functions allowed by \fIbc\fR numeric fields from the demographic records Numeric fields from both the IDENTIFICATION and MATRIX SECTIONS of the demographic records may be used. Review the User and Technical Documentation for these demographic files; or use the \fI-p\fR option of this program to print the MATRIX SECTION document (the demographic data fields), or \fIm.in.stf1.db3\fR to print a simplified list of IDENTIFICATION SECTION field names. When substituting values from the numeric fields into the expression, characters are replaced by zero. (Spaces, which are rare in the demographic data, are usually the result of missing values or restricted information). The numeric fields from the demographic records may be designated in one of three ways in the \fIexpression\fR. 1. 'Lcccc', where 'L' is an upper case alphabetic letter which indicates the length of the numeric field in the data records: A=1, B=2, ... , I=9, J=10, O=15, etc; and 'cccc' is the starting column number for the data field of interest: 301 for 100% population count, 7221 for total number of four-room housing units, 58 for 101st Congressional District, etc. The proper specification of the Congressional District number would be 'B58' because it is a two-column field. 'I301' would indicate that the 100% poplation should be used in the calculation; it's a nine-column field. 2. 'Pnna0nnn' or 'Hnna0nnn', where 'n' is a digit and 'a' is a digit or (rarely) upper case letter. These forms represent the MATRIX field naming schemes used in the CD-ROM "dBase 3" files. They can be used in processing STF1 records extracted from the CD-ROM or TAPE distribution media. All eight characters of the field name must be used. (Note: this form cannot be used in processing the PL94-171 records.) 3. 'ID_NAME'. The STF1 and PL94-171 files use the same set of IDENTIFICATION SECTION field names (67 fields) for the "locational" information contained in the first 300 characters of each record. The field name, in all upper case letters, may be used if the numeric value of the field is needed in the \fIexpression\fR. Two of the most useful fields are AREALAND and AREAWAT which allow the direct computation of population density values. The \fIbc\fR calculator usually returns a value with a very large number of decimal places. Vector attributes are automatically truncated(!) to integers by the v.support program when the topology file is built. Site list descriptions are likewise truncated to integers by GRASS programs which use the descriptions as numeric values (e.g., sites to cell in \fIs.menu\fR). .SH THE 'out=table:' PARAMETER The default operation of \fIv.apply.census\fR when tabular reports are produced to \fIstdout\fR (when not making a sites list or vector attribute file) is to print the easting and northing coordinates and then the value resulting from the \fIexpression\fR. Often the user wishes to have an identifier different from the coordinates. The construction \fIout=table:field\fR will replace the coordinates with the character string indicated by \fIfield\fR, which may have any of the three forms used for numeric fields in the formula \fIexpression\fR, see above. Note: a special case exists for the 66 character description field which begins in column 192; the entire field will be printed if designated by either of these two forms: \fIout=table:ANPSADPI\fR or \fIout=table:Z192\fR. Complex tables may be produced by making multiple runs of \fIv.apply.census\fR, redirecting the tabular output to files, and using the Unix tools \fIcut, paste,\fR and \fIcolrm\fR to combine the resulting files. .SH EXAMPLES [These examples assume that STF1 records for the census tracts (SUMLEV=140) in a particular county (CNTY=037) have been extracted from the distribution source (with \fIm.in.stf1.db3\fR or \fIm.in.stf1.tpe\fR and saved in a file named 037.140 in the current directory.] 1. Create a site list where the label values are the percentage of females in each input record: v.apply.census in=037.140 out=site formula='pct.female = 100 * (I373 / I301)' 2. Label an existing vector map (named tract.pop) of tract boundaries with the total population of each tract (run \fIv.support\fR and build topology after creating the attributes file): v.apply.census in=037.140 out=atts formula=tract.pop=P0010001 (or) v.apply.census in=037.140 out=atts formula=tract.pop=I301 3. Produce a tabular report of the census tract numbers and the number of Hispanics per square kilometer: v.apply.census in=037.140 out=table:TRACTBNA formula="m=(P0080001/AREALAND)*1000" 4. Produce a tabular report of the number of people per housing unit for each tract and the coordinates of the internal (label) point: v.apply.census in=037.140 formula="map=P0010001/H0010001" .SH FORMAT OF THE FORMULA TEXT FILE Running this program with the \fIef=file\fR command line parameter causes the named file to be read and each formula contained therein to be processed as if it were entered on the command line. The \fIout=\fR parameter may optionally be respecified in this file; each \fIout=\fR selection remains in effect until explicitly changed. The program exits after the last formula is processed. The following is a sample formula file. Note the use of lines beginning with '#' as manditory formula separators and comment lines. Also note that expressions may be continued on successive lines; the lines are concatenated to a maximum of 500 characters for a single formula. Blank lines are ignored. .nf .in +5 popden.sqkm = 1000 * P0010001 / (AREALAND+AREAWAT) # that computes population density in people per sq. km. # # next do people per sq. mile as a vector attribute file out=att popden.sqmi = 2.59*1000 * P0010001 / (AREALAND+ AREAWAT) # # next do total population as a vector attribute file total.pop = I301 # # output the county identification numbers as the descriptions # in a site list out=sites county = CNTY # # output the 66 char. description and FIPS Place Code as a table out=table:ANPSADPI map=PLACEFP # optional ending comment line .in -5 .fi .SH BUGS/FEATURES Computational errors in \fIbc\fR are not handled too gracefully: a warning is output and a zero result is used. \fIbc\fR tends to output lots of decimal places. The user must clean this up for output sent to stdout. The GRASS site list output format used includes the '#' before the label value to facilitate the production of raster maps with cell values representing the results of the formula execution. If using the "name_field" and "ef" parameters, the formula file may contain only one formula. .SH "SEE ALSO" \fIm.in.stf1.tpe\fR is used as a preprocessor to select subsets of STF1 or PL-171 tape format records for input to this program. \fIm.in.stf1.db3\fR is used as a preprocessor to select subsets of STF1 records from the CD-ROM in "dBase 3" format. Unix utility programs such at \fIgrep\fR or \fIawk\fR can also be used to select subsets of lines from the PL94-171 files, but not from the STF1 tape files due to their very long record lengths. .SH AUTHOR Dr. James Hinthorne, GIS Laboratory, Central Washington University. July, 1992.