s.menu(1)	       Grass User's Manual		s.menu(1)



NNAAMMEE
       ss..mmeennuu	-  Accesses  and  manipulates GRASS site location
       data.
       _(_G_R_A_S_S _S_i_t_e_s _P_r_o_g_r_a_m_)

SSYYNNOOPPSSIISS
       ss..mmeennuu

OOVVEERRVVIIEEWW
       The _s_._m_e_n_u program provides the user with  the  capability
       of interfacing site location data with the geographic data
       in raster map  layers.	Two  types  of	spatial  analysis
       reports on sites can be generated, and an interface to the
       "S" statistical package is provided.

DDEESSCCRRIIPPTTIIOONN
       The _s_._m_e_n_u program is an interface to functions that allow
       the user to manipulate GRASS site "lists".  A site list is
       a list of eastings and northings describing  the  location
       of  some  point	feature.   It can also contain a category
       value and category label for each site location.  The pro-
       gram  is  interactive.  After typing ss..mmeennuu on the command
       line, the user selects site functions from a menu.


       The main menu is shown below:


       SITES MAIN MENU	  (current list: no sites)

       LOCATION: spearfish    REGION 4928000.00(N)  4914000.00(S)
       100.00 (RES)
       MAPSET:	 PERMANENT	      609000.00(E)   590000.00(W)
       100.00 (RES)
       MASK:  none

       Please select one of the following

	  1  Read an existing site list
	  2  Mask current site list
	  3  Save the current site list in your mapset

	  4  Check site list for duplicate sites
	  5  Edit site list using a UNIX editor

	  6  Convert site list to raster file (0/1)
	  7  Convert site  list  to  raster  file  (frequency  of
       occurrence)

	  8  Run reports on the current site list

       stop  Leave the s.menu program

       At  the	top  of the menu is general information about the
       user's current MAPSET, LOCATION, etc.  Note the above mes-
       sage  in parentheses "current list:  no sites."	This mes-
       sage will vary depending on the status of the  list.   For
       example,  after the user reads the existing site list file
       _a_r_c_h___s_i_t_e_s, the message would read (given  the  geographic
       region  indicated): "current list: 25 sites, 24 in current
       region."

	       Read an existing site list
	      This option will copy an existing  site  list  file
	      into the current site list within the sites server.
	      Existing site lists are stored under a  GRASS  data
	      base and are pulled into the _s_._m_e_n_u server via this
	      option.  Other sites menu functions operate only on
	      the  current  site  list	file in the server -- you
	      must therefore "read an existing	site  list"  file
	      BEFORE performing any of the other sites menu func-
	      tions.
	      Note:  Site lists can be created and placed into	a
	      GRASS  data  base using _s_._m_e_n_u option 5 (edit) fol-
	      lowed by option 3 (save).  However,  the	user  can
	      also  create site lists using other methods or pro-
	      grams.  One simple way to do this is  to	create	a
	      site  list file in the appropriate format using any
	      text editor (e.g., "vi"), and to put this site list
	      file  under  the	_s_i_t_e___l_i_s_t_s  directory  under  the
	      user's current GRASS  mapset  (i.e.,  under  $LOCA-
	      TION/site_lists).   The  user  can  do  this either
	      inside of GRASS or outside of GRASS.   Alternately,
	      the  user can run other GRASS programs which format
	      their  output   as   a   GRASS   site   list   file
	      (_v_._t_o_._s_i_t_e_s),  or  the  user  can use UNIX programs
	      like _a_w_k and _s_e_d to format  other  GRASS	programs'
	      output   in   the   form	 of   a  site  list  file
	      (_d_._w_h_a_t_._v_e_c_t).



	       Mask current site list
	      The site list can  be  reduced  to  a  subset  that
	      includes	only  sites  which fall in specific cate-
	      gories within a specified raster	map  layer.   The
	      user  will be asked to specify the name of a raster
	      map layer to form the basis for the mask, and  will
	      then  be	allowed  to  specify categories from this
	      raster map that will limit the site list.  As  with
	      _r_._m_a_s_k,  the category values selected designate the
	      areas of the map in which information will  remain.
	      Areas assigned category values _n_o_t selected will be
	      re-assigned to category value "0" ("no data").

	      Note:  This masking  operation  is  performed  only
	      against  the site list itself and not against other
	      raster map layers.  If the user wishes  to  analyze
	      masked  raster  map layers, a mask should be create
	      using the _r_._m_a_s_k program.



	       Save the current site list in your mapset
	      The current site list can be stored permanently  in
	      your  current mapset with this option.  You will be
	      asked to name the saved site list and to provide	a
	      short  description  of it.  Saved site lists can be
	      retrieved (option 1) during later runs  of  _s_._m_e_n_u_.
	      Once  saved, these site list files can be used with
	      other GRASS programs, like _s_._d_b_._r_i_m.

	      Note:  Saved lists will be  removed  if  the  GRASS
	      mapset
	       under which they are stored is removed.



		Check site list for duplicate sites
	      It is not desirable that a site list contain multi-
	      ple references  to  the  same  site.   This  option
	      attempts	to recognize duplicate sites.  Duplicates
	      are displayed to the user and can be removed  auto-
	      matically if the user desires.  Duplicates can also
	      be removed by hand using option 5
	      (edit).



		Edit site list using a UNIX editor
	      The user can modify the current site list or create
	      a  new  site list by hand using a UNIX editor.  You
	      will be asked to specify the text editor you prefer
	      to  use.	 You  should  exercise	some  care if you
	      select this option.  Lines in the site  list  which
	      have  invalid formats will be (silently) ignored by
	      _s_._m_e_n_u.  See the GRASS  manual  entry  _s_i_t_e_s_._f_o_r_m_a_t
	      for a description of the site list format.

	      Note:   This  option will only modify the site list
	      copied into the server.  It  does  not  modify  the
	      original site list stored under a GRASS mapset.  If
	      you wish to modify a stored  site  list  file,  you
	      will have to combine options 1 (read), 5 (edit) and
	      3 (save).



		Convert site list file to raster file (0/1)
	      You can create a raster data representation of  the
	      site list in your GRASS mapset.

	      Once  created,  this  raster  map layer can be used
	      with other raster map layers in  further	analyses.
	      Allowing	the  user to create a raster map layer of
	      sites opens up the full analysis	capabilities  for
	      site  data that are available for raster map layers
	      within GRASS.
	      You have the option of  specifying  the  number  of
	      cells to represent a site.  The minimum is one cell
	      per site.  The alternatives are squares around  the
	      site:  3x3, 5x5, 7x7, etc.
	      The  number of categories present in the new raster
	      map layers will depend on the format of  your  site
	      list  file  (see	_s_i_t_e_s_._f_o_r_m_a_t).	 You can create a
	      non-binary raster map layer representation of  your
	      site list by creating the site list in the format:
	      ""EE||NN||"" _"_#_n _l_a_b_e_l_"

	      where  EE	is the Easting, NN is the Northing, and _#_n
	      _l_a_b_e_l is the description	field.	 The  description
	      field  consists  of  a pound sign # followed by the
	      category value _n to be associated with  the  site's
	      cell  location, and the category label _l_a_b_e_l for _n.

	      If the user does not include  a  description  field
	      starting with

	      _#_n

	      beside  the  Easting  and Northing on _e_v_e_r_y _l_i_n_e in
	      the sites list file, a binary raster map layer will
	      be  created  instead.   In  the binary raster file,
	      each site will be represented as the category value
	      1.   Non-site cells will be coded as category value
	      0.


       Note that only sites within the current geographic  region
       will  be considered.  However, if the size of the sites is
       more than one cell ( 3x3, 5x5, etc.)  and a site lies near
       an  edge  of  the geographic region, some of the cells for
       the site may fall outside the  geographic  region.   These
       cells  will  not  appear  in the raster map layer, and the
       site will no longer be 3x3 or 5x5 but will be  clipped  to
       fit the geographic region.



		Convert  site list file to raster file (frequency
	      of occurrence)
	      You can  also  create  a	frequency  of  occurrence
	      raster  map  layer  representation of the site list
	      file.
	      The raster category values will  be  coded  as  the
	      number of sites that fall within the cell.
	      In  this	function,  you	do NOT have the option of
	      specifying the number of cells to represent a site.



		Run reports on the current site list
	      The  current  list of sites is passed to the report
	      server after  removing  sites  which  do	not  fall
	      within  the geographic region of the user's current
	      GRASS mapset (see _g_._r_e_g_i_o_n).  The user then selects
	      the  names  of  one  or  more raster map layers for
	      analysis.  Data at (or near)  the  sites	extracted
	      from these raster map layers form the basis for all
	      reports.
	      The user specifies the 'size' of a site  in  cells.
	      The 'size' may be specified as a single cell, or as
	      a 3x3 square around the site, or 5x5, or	7x7,  etc
	      (where the size is an odd integer).




       The following menu of reports is then presented:

       SITES REPORT MENU

       Please select one of the following

	  1  Site characteristics report
	  2  Site occurrence report

	  3  Convert data to S input format
	  4  Produce machine-readable data file

       stop  return to SITES MAIN MENU


		Site characteristics report
	      This  report  provides geographic information about
	      each site.
	      Each site is identified by  description  and  loca-
	      tional  information.  The 'description' is an iden-
	      tification of the site.  The site  location  is  an
	      easting  and  a  northing.   (The location does not
	      denote the extent of the site, since, for  example,
	      an  archeologic  site  which  takes up two hectares
	      would be represented as a single point).
	      The information reported for each site is displayed
	      by  raster  map  layer, and, within each map layer,
	      gives the categories (i.e.,  characteristics)  that
	      occurred	at  the  site  (as well as a count of the
	      number of cells in each category).
	      This can easily generate a massive amount of infor-
	      mation,  which  is  difficult  to  handle or digest
	      quickly.	Therefore, option 2 produces  a  synopsis
	      of the information.



		Site occurrence report
	      This  report provides aggregate site characteristic
	      information organized by	raster	map  layer.   The
	      report  produces	chi-square  statistics	for  each
	      raster map  layer,  measuring  number  of  expected
	      sites  (assuming	a  random  distribution of sites)
	      against actual site occurrence.  The  site  charac-
	      teristic is the most frequently occurring cell cat-
	      egory in the site  (i.e.,  the  statistical  mode).
	      See  the	GRASS  manual  entry  for _s_i_t_e_s_._o_c_c_u_r for
	      details on this report.



		Convert data to S input format
	      This function converts the GRASS data extracted for
	      the  sites  into a form usable by the S statistical
	      package.	The user provides a file to  contain  the
	      information.   Once  the	file is written, the user
	      must exit _s_._m_e_n_u, run S on  an  S  data  base,  and
	      issue the S command


       ssoouurrccee _f_i_l_e


       to  bring the data into the S data base.  (Of course, _f_i_l_e
       would be the name of  the  actual  file	supplied  by  the
       user.)  See manual entry _s_i_t_e_s_._S for an explanation of the
       S data structures created by this interface.



		Produce machine-readable data file
	      This option provides a mechanism for  the  user  to
	      write  his/her  own  reports.   The data is written
	      into a user-specified file as a  text  file,  which
	      has a format readable by UNIX utilities (e.g., _a_w_k)
	      or user-written programs.  See GRASS  manual  entry
	      _s_i_t_e_s_._r_e_p_o_r_t for details on this format.



FFIILLEESS
       $LOCATION/site_list/

SSEEEE AALLSSOO
       _d_._i_c_o_n_s	 _d_._g_r_a_p_h   _d_._p_o_i_n_t_s   _d_._s_i_t_e_s	_p_._i_c_o_n_s  _r_._r_a_n_d_o_m
       _d_._w_h_a_t_._r_a_s_t  _d_._w_h_a_t_._v_e_c_t  _r_._w_h_a_t  _s_._i_n_._a_s_c_i_i   _s_._o_u_t_._a_s_c_i_i
       _s_._d_b_._r_i_m    _s_._s_u_r_f_._i_d_w	_s_._s_u_r_f_._r_s_t   _v_._d_b_._r_i_m	_v_._m_k_q_u_a_d_s
       _v_._t_o_._s_i_t_e_s _s_i_t_e_s_._f_o_r_m_a_t _s_i_t_e_s_._r_e_p_o_r_t _s_i_t_e_s_._o_c_c_u_r _s_i_t_e_s_._S

AAUUTTHHOORRSS
       Michael	 Shapiro,   U.S.Army   Construction   Engineering
       Research Laboratory


       James Farley, Arkansas Archeological Survey, University of
       Arkansas
       contributed the frequency  of  occurrence  sites  to  cell
       function

       _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						s.menu(1)
