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 program 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 message in parentheses  "current
       list:   no  sites."   This message 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  cur-
	      rent 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	there-
	      fore  "read an existing site list" file BEFORE performing any of
	      the other sites menu functions.
	      Note:  Site lists can be created and placed into	a  GRASS  data
	      base  using  _s_._m_e_n_u option 5 (edit) followed by option 3 (save).
	      However, the user can also create site lists using other methods
	      or programs.  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
	      $LOCATION/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	categories  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 multiple references
	      to  the  same site.  This option attempts to recognize duplicate
	      sites.  Duplicates are displayed to the user and can be  removed
	      automatically  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 repre-
	      sent a site.  The minimum is one cell per  site.	 The  alterna-
	      tives 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 representa-
	      tion 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 cate-
	      gory value 1.  Non-site cells will be coded as category value 0.


       Note  that only sites within the current geographic region will be con-
       sidered.  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 occur-
	      rence)
	      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 lay-
	      ers 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  locational  informa-
	      tion.   The 'description' is an identification 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 arche-
	      ologic 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 information,  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  characteristic  is  the  most
	      frequently  occurring  cell category in the site (i.e., the sta-
	      tistical 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  pro-
	      vides a file to contain the information.	Once the file is writ-
	      ten, 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)
