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



NNAAMMEE
       vv..aappppllyy..cceennssuuss	- Calculate/Import Demographics from Cen-
       sus 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  util-
       ity) 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.



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 | -  (std-
	      out) 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	represen-
	      tation   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 operators (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 num-
	      ber 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 inter-
       pretation of characters such as * / (  ) and spaces (which
       may  be	used  to increase readability, but are not neces-
       sary).  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 characters).	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 demographic 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 Documentation 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-col-
	      umn 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 "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 _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 popu-
	      lation 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
       programs  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  produced  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  identifier
       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 indicated 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 (SUMLEV=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  boundaries 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	     ffoorr--
       mmuullaa==tract.pop=P0010001	 (or)  vv..aappppllyy..cceennssuuss  iinn==037.140
       oouutt==atts ffoorrmmuullaa==tract.pop=I301




	      Produce  a  tabular report of the census tract num-
	      bers and the number of Hispanics per square kilome-
	      ter:


       vv..aappppllyy..cceennssuuss	 iinn=037.140    oouutt==table:TRACTBNA    ffoorr--
       mmuullaa=="m=(P0080001/AREALAND)*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 parame-
       ter causes the named file to be read and each formula con-
       tained therein to be processed 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  beginning  with '#' as manditory formula separators
       and comment lines.  Also note that expressions may be con-
       tinued  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 descrip-
       tions
       # 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 values 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)
