r.le.setup(1)	       Grass User's Manual	    r.le.setup(1)



NNAAMMEE
       _r_._l_e_._s_e_t_u_p  - The _r_._l_e_._s_e_t_u_p program is used to set up the
       sampling and analysis framework that will be used  by  the
       other _r_._l_e programs.

       _(_G_R_A_S_S _R_a_s_t_e_r _P_r_o_g_r_a_m_)

SSYYNNOOPPSSIISS
       rr..llee..sseettuupp

DDEESSCCRRIIPPTTIIOONN
       The  first  menu  allows  the user to define a rectangular
       sampling frame, select how sampling will be done (regions,
       sampling  units,  moving  window),  setup  the  limits for
       groups and classes, and change the color table.	 Use  the
       left mouse button to make your choice.


       Information  about  the	structure  of  the  landscape  is
       obtained by overlaying a set of sampling areas on top of a
       specified  part	(the  sampling	frame of a map layer, and
       then calculating specific structural measures for the part
       of the map layer that corresponds to the area in each sam-
       pling area.


       To setup a ssaammpplliinngg ffrraammee click on SAMPLING FRAME  in  the
       main  menu.  The program will ask "Will the sampling frame
       (total area within which sampling units	are  distributed)
       be  the whole map? (y/n)  [y]"  Just hit a carriage return
       to accept the default, which is to use the whole map.  You
       do  not	need to setup a sampling frame if you want to use
       the whole map, as this is the default.  To setup a differ-
       ent  sampling frame type "n" in response to this question.
       Then use the mouse and a rubber	band  box  to  outline	a
       rectangular  sampling  frame  on screen.  This box will be
       moved to the nearest row and column of the map.	You  will
       be  asked  last	whether  you  want to "Refresh the screen
       before choosing more setup?"  If you don't like	the  sam-
       pling  frame  you just setup, answer yes to this question,
       then click on SAMPLING FRAME again to redo  this  part  of
       the setup.  This sampling frame will be used in all subse-
       quent setup procedures unless  you  change  it.	 You  can
       change it at any time by simply clicking on SAMPLING FRAME
       again.


       A ssaammpplliinngg aarreeaa may be one of four things.  First,  it  is
       possible  to  treat  the  entire map layer as the one (and
       only) sampling area.  Second, if  the  map  layer  can  be
       divided	into  meaningful geographical regions, then it is
       possible to  treat  the	regions  themselves  as  sampling
       areas.  The third option is that the sampling areas may be
       sampling units of fixed shape and size (also called scale)
       that  are  placed  within  the  map layer as a whole.  The
       fourth and final option is that the sampling area  may  be
       moved systematically across the map as a moving window.


       If regions are to be used as the sampling areas , then the
       user can use _r_._l_e_._s_e_t_u_p to draw regions	or  any  existing
       map  of	regions  can  simply  be  used directly.  To draw
       regions and create a new regions map in _r_._l_e_._s_e_t_u_p  select
       "REGIONS"  from the first _r_._l_e_._s_e_t_u_p menu, and the user is
       asked to do the following:

       1.  "ENTER THE NEW REGION MAP NAME:". Only  a  new  raster
       map name is acceptable. The user
	   can	type  LIST  to	find  out the existing raster map
       names in this location and mapset.

       2. "PLEASE OUTLINE REGION # 1". The user should	move  the
       mouse cursor into the graphic
	  monitor window and use the mouse buttons as instructed:
       Left button: where am I.to display the current coordinates
       of the cursor.
       Middle  button: Mark start (next) point. to enter a vertex
       of the region boundary.
       Right button: Finish region-connect to 1st point to  close
       the region boundary by setting
	  the last vertex to be equal to the first one.

       3.  A  "REGION  OPTIONS:"  menu	is displayed and the user
       should use the mouse to select one of
	  the options:

       "DRAW MORE": repeat the above process  and  setup  another
       region.
       "START  OVER":  abandon	the  previous setup and start all
       over again.
       "DONE-SAVE": save the regions outlined  so  far	and  exit
       this procedure.
       "QUIT-NO  SAVE":  quit  the  procedure  without saving the
       regions.


       Once the "DONE-SAVE" option is selected,  the  new  raster
       map  of the sampling regions is generated. It is displayed
       on the monitor window for  several  seconds,  the  monitor
       window is refreshed, the main menu is displayed again, and
       the program is ready for other setup work.  Note that  you
       cannot  draw  regions in areas outside the mask, if a mask
       is present (see _r_._m_a_s_k command).


       The user can also use the GRASS _r_._d_i_g_i_t	or  _v_._d_i_g_i_t  pro-
       grams  to  digitize  circular  or polygonal regions and to
       create a sampling regions map  without  using  _r_._l_e_._s_e_t_u_p.
       Or,  as	mention above, an existing raster map can be used
       as a regions map.


       If sampling units are to be used  as  the  sampling  areas
       (Fig.  2),  then  choose  "SAMPLING  UNITS" from the first
       _r_._l_e_._s_e_t_u_p menu.  The program checks the _r_._l_e_._p_a_r_a  subdi-
       rectory for an existing "units" file from a previous setup
       session and allows the user to rename this file	(to  save
       it) before proceeding.  The r.le.setup program will other-
       wise overwrite  the  "units"  file.   Then  the	following
       choice is displayed followed by a series of other choices:

	    Which do you want to do?
	       (1) Use the keyboard to enter sampling unit param-
       eters
	       (2) Draw the sampling units with the mouse
					  Enter 1 or 2:



       When  sampling  units  are defined using the keyboard, the
       user inputs the shape and size  (scale)	of  the  sampling
       units  by  specifying  dimensions in pixels using the key-
       board.  When sampling units are drawn with the mouse,  the
       user  clicks the mouse to define the sampling units in the
       GRASS monitor window, and then actually	places	the  sam-
       pling  units  for each scale onto the map.  By placing the
       units with the mouse the user can directly  determine  the
       method of sampling unit distribution as well as the shape,
       size, and number of sampling units.


       If the choice is made to define sampling units  using  the
       keyboard,  the  following  series  of  questions  must  be
       answered:

	    How many different SCALES do you want (1-15)?


       The user is asked to specify the  number  of  scales  that
       will  be used.  The _r_._l_e programs allow the user to simul-
       taneously sample the same map with the same measures using
       sampling areas of different sizes.  Currently there can be
       between 1 and 15 scales that  can  be  sampled  simultane-
       ously.  Substantial  output can be produced if many scales
       are used.


       Sampling units must be placed  spatially  into  the  land-
       scape.  There are five options for doing this :


       _R_a_n_d_o_m _n_o_n_o_v_e_r_l_a_p_p_i_n_g

       Sampling  units	are  placed  in the landscape by randomly
       choosing numbers that specify the location  of  the  upper
       left  corner  of  each  sampling unit, subject to the con-
       straint that successive sampling units not  overlap  other
       sampling units or the edge of the landscape, and that they
       must be entirely within the area defined by the mask  (see
       _r_._m_a_s_k command) if one exists.


       _S_y_s_t_e_m_a_t_i_c _c_o_n_t_i_g_u_o_u_s

       Sampling  units	are  placed side by side across the rows.
       The user will be able to enter a row and column	to  indi-
       cate  where  the  upper left corner of the systematic con-
       tiguous framework should be  placed.   Rows  are  numbered
       from  the  top  down  beginning with row 1 of the sampling
       frame.  Columns are numbered from left to right, beginning
       with  column  1	of the sampling frame.	A random starting
       location can be obtained by using a standard random number
       table   to  choose  the	starting  row  and  column.   The
       _r_._l_e_._s_e_t_u_p program does not avoid placing the set of  sam-
       pling  units  over  areas outside the mask.  The user will
       have to make sure that sampling units do not  extend  out-
       side  the  mask	by choosing a particular starting row and
       column or by drawing a sampling frame before  placing  the
       set of sampling units.


       _S_y_s_t_e_m_a_t_i_c _n_o_n_c_o_n_t_i_g_u_o_u_s

       The user must specify the starting row and column as in #2
       above and the amount of spacing (in pixels)  between  sam-
       pling  units.  Horizontal and vertical spacing are identi-
       cal.  Sampling units are again placed side  by  side  (but
       spaced)	across	the  rows.  As in #2 the program does not
       avoid placing sampling units outside the masked area;  the
       user will have to position the set of units to avoid areas
       outside the mask.


       _S_t_r_a_t_i_f_i_e_d _r_a_n_d_o_m

       The strata are rectangular areas within which single  sam-
       pling  units  are  randomly  located.  The user must first
       specify the starting row and column as in #2 above.   Then
       the user must specify the number of strata in the horizon-
       tal and vertical directions.   As in #2 the  program  does
       not  avoid placing sampling units outside the masked area;
       the user will have to position the set of units	to  avoid
       areas outside the mask.


       _C_e_n_t_e_r_e_d _o_v_e_r _s_i_t_e_s

       The  user  must	specify the name of a sitefile containing
       point locations.  A single sampling unit  is  placed  with
       its  center  over  each	site in the site file.	This is a
       useful approach for determining	the  landscape	structure
       around  points,	such  as  around the location of wildlife
       observations.


       The user is prompted to enter a	ratio  that  defines  the
       shape  of the sampling units.  Sampling units may have any
       rectangular shape, including square as a special  case  of
       rectangular.  Rectangular shapes are specified by entering
       the ratio of columns/rows  (horizontal  dimension/vertical
       dimension)  as  a  real	number.  For example, to obtain a
       sampling unit 10 columns wide by 4 rows long  specify  the
       ratio as 2.5 (10/4).

	    Recommended maximum SIZE is m in x cell total area.

	    What  size (in cells) for each sampling unit of scale
       n?


       The user is then given the  recommended	maximum  possible
       size  for  a  sampling unit (in pixels) and asked to input
       the size of sampling units at each scale.  Sampling  units
       can  be	of  any size, but the maximum size is the size of
       the landscape as a whole.  All the  sampling  units,  that
       make up a single sampling scale, are the same size.  After
       specifying the size, the program  determines  the  nearest
       actual number of rows and columns, and hence size, that is
       closest to the requested size, given the  shape	requested
       earlier.

	    The  nearest size is x cells wide X y cells high = xy
       cells
	    Is this size OK?  (y/n)  [y]

	    Maximum NUMBER of units in scale n is p?
	    What NUMBER of sampling units do you want to  try  to
       use?


       The  maximum  number  of units that can be placed over the
       map, given the shape and size of the units, is then given.
       The  user  can then choose the number of sampling units to
       be used in the map layer.  It may not always  be  possible
       to  choose the maximum number, depending upon the shape of
       the sampling units.  In the case of systematic  contiguous
       and  noncontiguous,  the  program  will	indicate how many
       units will fit across the columns and down the rows.   The
       user  can  then specify a particular layout (e.g., 6 units
       could be placed as 2 rows of 3 per row or as 3 rows  of	2
       per row).

	    Is this set of sampling units OK?  (y/n)  [y]


       Finally,  the  set  of  sampling units is displayed on the
       screen (e.g., Fig. 1) and the user is asked whether it  is
       acceptable.   If  the answer is no, then the user is asked
       if the screen should be refreshed before redisplaying  the
       menu  for  "Methods of sampling unit distribution" so that
       the user can try the sampling unit setup again.


       The choice is made to  define  sampling	units  using  the
       mouse,  then  the following menu for use with the mouse is
       displayed:

	    Outline the standard sampling unit of scale n.
	       Left button:	Check unit size
	       Middle button:	Move cursor
	       Right button:	Lower right corner of unit here


       The user can then use the mouse and the rubber band box to
       outline the standard sampling unit.  Once it has been out-
       lined, the number of columns and rows  in  the  unit,  the
       ratio  of width/length and the size of the unit, in cells,
       will be displayed.  After this  first  unit  is	outlined,
       then a new menu is displayed:

	    Outline more sampling units of scale n?
	       Left button:	Exit
	       Middle button:	Not used
		Right  button:	  Lower right corner of next unit
       here


       The user can then place more units identical to the  stan-
       dard  unit by simply clicking the right mouse button where
       the lower right corner of the unit should be placed.   The
       rest  of  the rubber band box can be ignored while placing
       additional units.  The program is set  up  so  that  units
       cannot  be  placed  so  they  overlap one another, so they
       overlap the area outside the mask, or so they overlap  the
       edge  of  the sampling frame.  Warning messages are issued
       for all three of these errors and a sampling unit is  sim-
       ply not placed.


       Using this procedure a rectangular "window" or single sam-
       pling area is moved systematically across the map to  pro-
       duce  a	new  map (Fig. 2,3).  This sampling procedure can
       only be used with the measures that produce a single value
       or with a single class or group when measures produce dis-
       tributions of values (Table 1).	The first class or  group
       specified  when	defining  class  or group limits (section
       2.3.2.) is used if distributional measures are chosen with
       the moving window sampling method.  In this case, the user
       should manually edit the _r_._l_e_._p_a_r_a_/_r_e_c_l___t_b  file  so  that
       the  desired  group  is	listed as the first group in this
       file.


       Sampling begins with the upper left corner of  the  window
       placed  over  the upper left corner of the sampling frame.
       It is strongly recommended that the user read the  section
       on  the GRASS mask (section 2.2.2) prior to setting up the
       moving window, as this mask can be used to  speed  up  the
       moving  window operation.  The value of the chosen measure
       is calculated for the window area.  This value is assigned
       to  the location on the new map layer corresponding to the
       center pixel in the window if the window has odd (e.g. 3 X
       3)  dimensions.	 The value is assigned to the location on
       the new map layer corresponding to the first  pixel  below
       and  to	the  right  of	the center if the window has even
       dimensions (e.g. 6 X 10).  If this  pixel  has  the  value
       "0,"  which  means  "no data" in GRASS, then this pixel is
       skipped and a value of "0" is assigned to the  correspond-
       ing  location in the new map.  The window is then moved to
       the right (across the row) by one pixel, and  the  process
       is  repeated.   At the end of the row, the window is moved
       down one pixel, and then back across the row.  This option
       produces  a new map layer, whose dimensions are smaller by
       approximately (m-1)/2 rows and columns,	where  m  is  the
       number of rows or columns in the window.


       If  the "MOVE-WINDOW" option in the main menu is selected,
       first the program checks for an existing "move_wind" file,
       in  the	r.le.para  subdirectory, containing moving window
       specifications from a previous session.	The user is given
       the  option  to	avoid overwriting this file by entering a
       new file name for the old "move_wind" file.  Users  should
       be  aware  that	moving	window	analyses  are  very slow,
       because a large number of sampling units are,  in  effect,
       used.  See the appendix on "Time needed to complete analy-
       ses with the r.le programs" for some ideas about how  mov-
       ing  window size and sampling frame area affect the needed
       time to complete the analyses.


       The _r_._l_e  programs  _r_._l_e_._d_i_s_t  and  _r_._l_e_._p_a_t_c_h  allow  the
       attribute categories in the input map to be reclassed into
       several attribute groups, and reports the analysis results
       by  each  of  these  attribute groups.  It is necessary to
       setup group limits for all measures that say "by gp"  when
       typing  "_r_._l_e_._d_i_s_t _h_e_l_p" or "_r_._l_e_._p_a_t_c_h _h_e_l_p" at the GRASS
       prompt.	The same reclassing can be done with the measure-
       ment  indices  (e.g.,  size),  except  that  each "cohort"
       (class) of the reclassed indices is called an index  class
       instead	of  a group.  It is also necessary to setup class
       limits for all measures that say "by  class"  when  typing
       "_r_._l_e_._d_i_s_t _h_e_l_p" or "_r_._l_e_._p_a_t_c_h _h_e_l_p" at the GRASS prompt.


       Group/class limits are setup by choosing "GROUP/CLASS LIM-
       ITS"  from  the main menu upon starting _r_._l_e_._s_e_t_u_p, or you
       can create the files manually using a  text  editor.   The
       program	checks	for  existing  group/class limit files in
       subdirectory _r_._l_e_._p_a_r_a and allows the user to rename these
       files  prior  to continuing.  If the files are not renamed
       the program will overwrite  them.   The	files  are  named
       recl_tb	(attribute  group  limits), size (size class lim-
       its), shape_PA  (shape  index  class  limits  for  perime-
       ter/area  index),  shape_CPA (shape index class limits for
       corrected perimeter/area index),  shape_RCC  (shape  index
       class limits for related circumscribing circle index), and
       from_to	(for  the  _r_._l_e_._d_i_s_t  program  distance   methods
       m7-m9).


       Attribute  groups  and index classes are defined in a dif-
       ferent way.  In the _r_._l_e  programs  attribute  groups  are
       defined as in the following example:

	    1, 3, 5, 7, 9 tthhrruu 21 = 1 (comment)
	    31 tthhrruu 50 = 2 (comment)
	    eenndd


       In  this  example, the existing categories 1, 3, 5, 7, {9,
       10, ... 20, 21} are included in the  new  group	1,  while
       {31, 32, 33, ..., 49, 50} are included in the new group 2.
       The characters in  bold	are  the  "key	words"	that  are
       required  in  the  definition.	Each  line  is called one
       "reclass rule".


       The GRASS reclass convention is adopted here with a little
       modification  (see "_r_._r_e_c_l_a_s_s" command in the GRASS User's
       Manual).  The difference is that r.le only allows one rule
       for  each  group  while the GRASS _r_._r_e_c_l_a_s_s command allows
       more than one. The definition of "from" and "to" groups is
       simply  the  extension  of  the	GRASS  reclass rule.  The
       advantage of using the GRASS reclass  convention  is  that
       the  user  can  generate  a permanent reclassed map, using
       GRASS programs, directly from the _r_._l_e setup results.


       The _r_._l_e measurement index  classes  are  defined  by  the
       lower limits of the classes, as in the following example:

	    0.0, 10.0, 50.0, 200.0, --999999


       This means:

	    if	v  >=  0.0  and v < 10.0 then  v belongs to index
       class 1;
	    if v >= 10.0 and v < 50.0 then  v  belongs	to  index
       class 2;
	    if	v  >=  50.0 and v < 200.0 then v belongs to index
       class 3;
	    if v >= 200.0 then v belongs to index class 4;


       where v is the calculated index value and --999999  marks  the
       end  of	the index class definition. The measurement index
       can be the size index, one of the three shape indices,  or
       one  of	the  three distance indices.  The program is cur-
       rently designed to allow no more than 25 attribute groups,
       25  size  classes, 25 shape index classes, and 25 distance
       index classes.  As an alternative, the user  may  want  to
       permanently group certain attributes prior to entering the
       _r_._l_e programs.  For example, the user may  want	to  group
       attributes  1-10, in a map whose attributes are ages, into
       a single attribute representing young patches.	The  user
       can  do	this  using  the  GRASS  _r_._r_e_c_l_a_s_s and _r_._r_e_s_a_m_p_l_e
       commands, which will create a new map layer that can  then
       be  analyzed  directly  (without  setting up group limits)
       with the _r_._l_e programs.

SSEEEE AALLSSOO
       The _r_._l_e Programs Users Guide

       _v_._d_i_g_i_t

AAUUTTHHOORR
       William L. Baker, Department of Geography and  Recreation,
       University of Wyoming

       _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_4 _$



GRASS 5.0					    r.le.setup(1)
