v.apply.census(1)	      Grass User's Manual	     v.apply.census(1)



NNAAMMEE
       vv..aappppllyy..cceennssuuss  - Calculate/Import Demographics from Census STF1 Files
       _(_G_R_A_S_S _V_e_c_t_o_r _P_r_o_g_r_a_m_)

SSYYNNOOPPSSIISS
       vv..aappppllyy..cceennssuuss
       vv..aappppllyy..cceennssuuss hheellpp
       vv..aappppllyy..cceennssuuss [[--dd]] [[--pp]] [[--ll]] [[--uu]]

       vv..aappppllyy..cceennssuuss iinnppuutt__ssttff11==name
	      [oouutt==name]	 [eeff==name]	  [ffoorrmmuullaa==mapname=expression]
	      [nnaammee__ffiieelldd==name] [zzoonnee==value] [sspphheerrooiidd==name]

DDEESSCCRRIIPPTTIIOONN
       This program reads a previously selected subset	of  STF1  or  PL94-171
       U.S. Census Bureau demographic records (see _m_._i_n_._s_t_f_1_._t_a_p_e), and writes
       one of the following: 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.



       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 _b_c _-_l utility) to compute  the  value  for  each
       input record.


       The  location coordinates for the polygon label point or the site loca-
       tion 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.



OOPPTTIIOONNSS
   FFllaaggss::
       --dd     Output IDENTIFICATION SECTION to stdout (20 pages)

       --pp     Output STF1 MATRIX TABLE to stdout (30 pages)

       --ll     Output PL94-171 MATRIX TABLE to stdout (1 page)

       --uu     Output STF1 SUMLEV TABLE to stdout (4 pages)



       NNoottee::  Only  the  first	flag given will be executed; the program exits
	      after  sending  one  table  to  stdout.	Other  parameters  are
	      ignored.




   PPaarraammeetteerrss::
       iinnppuutt__ssttff11==_n_a_m_e
	      Path/name of STF1 or PL94 input file

       oouutt==_n_a_m_e
	      Type of output: site | atts | table:Lxxx | - (stdout) default: -

       _a_t_t    for results to vector map attribute file

       _s_i_t_e   for results to site list

       -      for results to stdout; this is the default

       _t_a_b_l_e  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).


       eeff==_n_a_m_e
	      Path/name of text file with formula expression(s)

       ffoorrmmuullaa==_m_a_p_=_e_x_p_r_e_s_s_i_o_n
	      mapname=Computation with STF1A columns, constants and _b_c	opera-
	      tors  (see  below).   mapname  of  vector or site map to make is
	      required in all cases (but ignored for '-'  or  'table:'	output
	      modes).

       nnaammee__ffiieelldd==_n_a_m_e
	      field name for parsing stdin lines (-a to ignore)

	      default: -a

	      _n_a_m_e  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.

       zzoonnee==_v_a_l_u_e
	      UTM zone number; default is location zone

	      options: 1-60

	      default: 10

       sspphheerrooiidd==_n_a_m_e
	      Spheroid for LL to UTM conversion; see m.gc.ll

	      default: clark66



       NOTE:  Only one of the "ef" or "formula" input fields may be used.



TTHHEE ffoorrmmuullaa PPAARRAAMMEETTEERR
       The string after the '='  in  this  parameter  almost  always  must  be
       enclosed  in  quotes to protect it from Shell interpretation of charac-
       ters such as * / (  ) and spaces (which may be used to  increase  read-
       ability,  but  are  not	necessary).  This string is always of the form
       _m_a_p_n_a_m_e_=_e_x_p_r_e_s_s_i_o_n.


       The _m_a_p_n_a_m_e string can be any legal GRASS map name (up  to  14  charac-
       ters).  The second '=' is required and may be preceeded and followed by
       a space.


       In the _e_x_p_r_e_s_s_i_o_n, great flexibility is provided for the computation of
       interesting  combinations  of  the  data  fields contained in the demo-
       graphic records.


       The usual operators used in the _e_x_p_r_e_s_s_i_o_n include: +, -, *, /, and  %.
       The  user should review the Unix manual entry for the _b_c calculator for
       the complete list of available functions and other operators.


       Parentheses are used in the normal algebraic manner.


       The operands in the _e_x_p_r_e_s_s_i_o_n may consist of any mixture of:


       integer constants real constants functions allowed by _b_c 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  Docu-
       mentation  for  these  demographic  files; or use the _-_p option of this
       program to print the MATRIX  SECTION  document  (the  demographic  data
       fields).   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 _e_x_p_r_e_s_s_i_o_n.



	      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.



	       '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.)



	      IDENTIFICATION SECTION field names (67 fields)  for  the	"loca-
	      tional"  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 _e_x_p_r_e_s_-
	      _s_i_o_n.  Two of the most useful fields are	AREALAND  and  AREAWAT
	      which allow the direct computation of population density values.



       The _b_c 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 pro-
       grams which use the descriptions as numeric values (e.g., sites to cell
       in

       _s_._m_e_n_u ).



TTHHEE ''oouutt==ttaabbllee::'' PPAARRAAMMEETTEERR
       The  default  operation of _v_._a_p_p_l_y_._c_e_n_s_u_s when tabular reports are pro-
       duced to _s_t_d_o_u_t (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 _e_x_p_r_e_s_s_i_o_n.  Often the user wishes to have an  iden-
       tifier  different  from	the  coordinates.   The  construction  _o_u_t_=_t_a_-
       _b_l_e_:_f_i_e_l_d will replace the coordinates with the character string  indi-
       cated  by _f_i_e_l_d, which may have any of the three forms used for numeric
       fields in the formula _e_x_p_r_e_s_s_i_o_n, 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: _o_u_t_=_t_a_b_l_e_:_A_N_P_S_A_D_P_I or _o_u_t_=_t_a_b_l_e_:_Z_1_9_2.


       Complex	tables may be produced by making multiple runs of _v_._a_p_p_l_y_._c_e_n_-
       _s_u_s, redirecting the tabular output to files, and using the Unix  tools
       _c_u_t_, _p_a_s_t_e, and _c_o_l_r_m to combine the resulting files.



EEXXAAMMPPLLEESS
       [These  examples  assume  that STF1 records for the census tracts (SUM-
       LEV=140) in a particular county (CNTY=037) have been extracted from the
       distribution  source  (with  _m_._i_n_._s_t_f_1_._t_p_e)  and  saved in a file named
       037.140 in the current directory.]



	      Create a site list where the label values are the percentage  of
	      females in each input record:


       vv..aappppllyy..cceennssuuss  iinn=037.140 oouutt==site ffoorrmmuullaa=='pct.female = 100 * (I373 /
       I301)'




	      Label an existing vector map (named tract.pop) of  tract	bound-
	      aries with the total population of each tract (run _v_._s_u_p_p_o_r_t
	       and build topology after creating the attributes file):


       vv..aappppllyy..cceennssuuss  iinn==037.140  oouutt==atts  ffoorrmmuullaa==tract.pop=P0010001   (or)
       vv..aappppllyy..cceennssuuss iinn==037.140 oouutt==atts ffoorrmmuullaa==tract.pop=I301




	      Produce a tabular report of the census  tract  numbers  and  the
	      number of Hispanics per square kilometer:


       vv..aappppllyy..cceennssuuss  iinn=037.140 oouutt==table:TRACTBNA ffoorrmmuullaa=="m=(P0080001/ARE-
       ALAND)*1000"




	      Produce a tabular report of the number  of  people  per  housing
	      unit  for each tract and the coordinates of the internal (label)
	      point:


       vv..aappppllyy..cceennssuuss iinn==037.140 ffoorrmmuullaa=="map=P0010001/H0010001"





FFOORRMMAATT OOFF TTHHEE FFOORRMMUULLAA TTEEXXTT FFIILLEE
       Running this program with the _e_f_=_f_i_l_e command line parameter causes the
       named  file  to	be  read and each formula contained therein to be pro-
       cessed as if it were entered on the command line.  The  _o_u_t_=  parameter
       may optionally be respecified in this file; each _o_u_t_= 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 begin-
       ning 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.

       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


BBUUGGSS//FFEEAATTUURREESS
       Computational errors in _b_c are not handled too gracefully: a warning is
       output and a zero result is used.


       _b_c 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  val-
       ues representing the results of the formula execution.


       If  using  the  "name_field"  and "ef" parameters, the formula file may
       contain only one formula.



SSEEEE AALLSSOO
       _m_._i_n_._s_t_f_1_._t_a_p_e is used as a preprocessor to select subsets of  STF1  or
       PL-171 tape format records for input to this program.



       _U_n_i_x  _u_t_i_l_i_t_y  _p_r_o_g_r_a_m_s	_s_u_c_h _a_t _g_r_e_p or _a_w_k 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.



AAUUTTHHOORR
       Dr.  James  Hinthorne,  GIS  Laboratory, Central Washington University.
       July, 1992.



       _L_a_s_t _c_h_a_n_g_e_d_: _$_D_a_t_e_: _2_0_0_2_/_0_1_/_2_5 _0_5_:_4_5_:_3_5 _$



GRASS 5.0						     v.apply.census(1)
