NAME
s.menu - Accesses and manipulates GRASS site location data.
(GRASS Sites Program)
SYNOPSIS
s.menu
OVERVIEW
The s.menu 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.
DESCRIPTION
The s.menu 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 s.menu 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
arch_sites, 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.menu 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 functions.
Note: Site lists can be created and placed into a GRASS data base
using s.menu 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 site_lists 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 (r.random, s.db.rim, v.mkquads, v.to.sites),
or the user can use UNIX programs like awk and sed to format
other GRASS programs' output in the form of a site list file
(d.what.rast, d.what.vect).
- 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.mask,
the category values selected designate the areas of the map in which
information will remain. Areas assigned category values not
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.mask
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.menu.
Once saved, these site list files can be used with other GRASS programs,
like d.sites, d.points, d.icons, p.icons, s.surf.idw, and s.db.rim.
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.menu.
See the GRASS manual entry sites.format
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 sites.format).
You can create a non-binary raster map layer representation of your site list
by creating the site list in the format:
"E|N|"
"#n label"
where E is the Easting, N is the Northing, and #n label
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 label
for n.
If the user does not include a description field starting with
#n
beside the Easting and Northing on every line 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.region).
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 locational information.
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 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 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 statistical mode).
See the GRASS manual entry for sites.occur 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.menu,
run S on an S data base, and issue the S command
source file
to bring the data into the S data base.
(Of course, file
would be the name of the actual file supplied by the user.)
See manual entry sites.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., awk)
or user-written programs.
See GRASS manual entry sites.report for details on this format.
FILES
$LOCATION/site_list/<file >
SEE ALSO
AUTHORS
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