subsetpolygon             package:ssBase             R Documentation

_P_o_l_y_g_o_n _S_u_b_s_e_t _o_f _E_v_e_n_t_s

_D_e_s_c_r_i_p_t_i_o_n:

     Selects events within a specified polygon from a given catalogue.
     Note that 'subset.polygon' is deprecated; it conflicts with the
     generic function 'subset'. Change to 'subsetpolygon'; it has the
     same arguments.

_U_s_a_g_e:

     subsetpolygon(x, polylong, polylat, mindepth=0, maxdepth=Inf,
                   minmag=-Inf, maxmag=Inf, minday=-Inf, maxday=Inf,
                   report.count=TRUE, na.rm=TRUE, ...)

     #   Deprecated Usage:
     subset.polygon(x, polylong, polylat, mindepth=0, maxdepth=Inf,
                    minmag=-Inf, maxmag=Inf, minday=-Inf, maxday=Inf,
                    report.count=TRUE, na.rm=TRUE, ...)

_A_r_g_u_m_e_n_t_s:

       x: catalogue name. 

polylong: vector containing the longitudes of the polygon corners in
          the order as one  travels the perimeter. Specified as degrees
          east of Greenwich (0 to 360). 

 polylat: vector containing the latitudes of the polygon corners in the
          order as one  travels the perimeter. Specified as degrees
          north (positive) or south (negative)  of the equator (-90 to
          90). 

mindepth: minimum depth in kilometres. 

maxdepth: maximum depth in kilometres. 

  minmag: minimum magnitude. 

  maxmag: maximum magnitude. 

  minday: the number of days (and fractions) after 00:00 hrs on 1
          January 1970 from which events are required. See Details. 

  maxday: the number of days (and fractions) after 1 January 1970
          denoting the upper bound of the time interval containing the
          required events. See Details. 

report.count: Boolean. Report the number of events referred to by the
          new subset. Default is 'TRUE'. 

   na.rm: Boolean. Determines whether those events with missing values
          of the subsetting variables should be excluded, see Details. 
          Default is 'TRUE'. 

     ...: other options for restricting Catalogue data. These must take
          the form 'option == value', where 'option' is a component of
          the specified catalogue. 

_D_e_t_a_i_l_s:

     Events are initially selected within the rectangle defined by
     'range(polylong)' and 'range(polylat)'. The 'outside' component in
     the returned object are the indices of those events within this
     rectangle but outside the polygon. Events with a missing latitude
     or longitude will always be excluded regardless of the value of
     the argument 'na.rm'.

     The subsetting then determines those events within the required
     magnitude-depth-time window. The default settings for each of
     these variables is to take all events. The function only works
     through each of the "min" and "max" values _included in your
     function call_. Those arguments _not explicitly listed will have
     no effect_. Events within the required magnitude-depth-time window
     are then divided into those 'inside' and 'outside' of the polygon.
     A logical vector is constructed with the same length as the number
     of events in the catalogue, and indicates whether a given event
     satisfies the subsetting criteria. From this, the vector of
     indices of the required events is created.

     Historical events often have missing values, particularly the
     magnitude and depth. Consider the situation where 'minmag=6'. The
     logical vector within the function will contain 'TRUE''s and
     'FALSE''s for those events that satisfy or not satisfy this
     condition, respectively. However, for those historical events with
     a missing magnitude ('NA'), the elements in the logical vector
     will also be 'NA'. The argument 'na.rm' determines whether these
     events should be removed ('TRUE') or included ('FALSE') in the
     subset. The default setting is to remove such events, though in
     the context of large historical events, it would be more sensible
     to include them, i.e. 'na.rm=FALSE'.

     The arguments 'minday' and 'maxday' represent the boundary
     _points_ of the time interval, and can represent fractions of
     days. For example, 00:00 hrs on 1 Jan 1970 is represented as
     'minday=0', whereas 18:00 hrs on 2 Jan 1970 is represented as
     'minday=1.75'. Similarly, 18:32:24 hrs on 30 Sept 1990 could be
     specified as 'minday = julian(9,30,1990) + 18/24 + 32/(24*60) +
     24/(24*60*60)'. Note that 'maxday = julian(1,1,1990)' represents
     the _point_ 00:00 hrs on 1 Jan 1990, and therefore will not
     include events on 1 Jan 1990 after midnight.

_V_a_l_u_e:

     Returns an object of type list of class '"subset"'. All values of
     optional arguments  above, plus the specified values of 'polylong'
     and 'polylat', are included as elements within  the list. Other
     components within the list are:

 indices: an array of indices for events in catalogue x satisfying the
          selection criteria. 

 catname: catalogue name. 

 outside: see details. 

    type: type of subset, set to '"Polygon"'. 

_S_e_e _A_l_s_o:

     'subsetcircle', 'subsetrect',  'subsetsphere', 'print.subset', 
     'summary.subset'

_E_x_a_m_p_l_e_s:

     #  Select events from NZ55 within following polygon
     polylong <- c(173.8, 174.3, 174.8, 174.4, 174.8, 175.6,175,174.5)
     polylat <- c(-41.5, -40.5, -40.9, -41, -41.4, -41, -41.8, -41.25)

     data(NZ55)
     a <- subsetpolygon(NZ55, polylong, polylat)

     #  plot points within polygon
     plot(NZ55$longitude[a$indices], NZ55$latitude[a$indices], cex=2,
          xlim=range(polylong), ylim=range(polylat), pch=16, col="red")
     points(c(polylong,polylong[1]), c(polylat, polylat[1]), type='l', lty=2)

