rtoro                package:spatstat                R Documentation

_R_a_n_d_o_m _T_o_r_o_i_d_a_l _S_h_i_f_t _o_f _P_o_i_n_t _P_a_t_t_e_r_n

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

     Applies a random shift simultaneously to all the points of a point
     pattern, or to selected sub-patterns, with wraparound at the
     borders of the window.

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

        rtoro(X, which=NULL)

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

       X: Point pattern to be subjected to random shift. An object of
          class '"ppp"' or '"splitppp"'. 

   which: Identifies which components of the pattern will be shifted.
          Vector of marks (if 'X' is a multitype point pattern) or
          subset of 'names(X)' (if 'X' is a '"splitppp"' object). Each
          component will be shifted independently. 

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

     This operation randomises the locations of the points in a point
     pattern. It is useful for some hypothesis testing purposes.

     A `shift' is a simultaneous, parallel displacement of all points
     by the same displacement vector (delta.x, delta.y). Shifting a
     point pattern could leave some points outside the boundary of the
     window of observation, so we may (if the window is a rectangle)
     treat opposite edges of the window as identical, so that a point
     which disappears off the right-hand edge will re-appear at the
     left-hand edge. This is called a ``toroidal shift'' because it
     makes the rectangle topologically equivalent to the surface of a
     torus (doughnut). 

     The argument 'X' may be either

        *  a point pattern (an object of class '"ppp"')

        *  an object of class '"splitppp"' (basically a list of point
           patterns, obtained from 'split.ppp').

     If 'which=NULL', then

        *  If 'X' is a point pattern object, all the points of the
           pattern are shifted simultaneously by the same displacement
           vector.

        *  If 'X' is an object of class '"splitppp"' then each of the
           component point patterns is randomly shifted by a different
           displacement vector.

     The argument 'which' identifies which sub-patterns of 'X' will be
     subjected to random shifts. Different sub-patterns will be shifted
     by different displacement vectors. If 'which' is not 'NULL', then

        *  If 'X' is a point pattern object, it should be a multitype
           pattern (i.e. 'X$marks' must be a factor). Then 'which'
           should be a vector of types (i.e. a vector containing one or
           more levels of 'X$marks'). For each value 'a' in 'which',
           the sub-pattern of 'X' consisting of points of type 'a' only
           will be extracted, and subjected to a random toroidal shift.
           A different shift will be applied to different sub-patterns.
           The points not selected by 'which' will be unchanged.

        *  If 'X' is an object of class '"splitppp"', then 'which' can
           be any valid subset index for the list 'X'. For example
           'which' could be a vector of names of components in the list
           'X'. Each selected component point pattern will be shifted
           by a different displacement vector.

     In this implementation, every random displacement vector is
     generated with a uniform distribution over the range of  possible
     displacement vectors. That is, the coordinates delta.x, delta.y
     are independent and uniformly distributed.

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

     An object of the same type as 'X'.

_A_u_t_h_o_r(_s):

     Adrian Baddeley adrian@maths.uwa.edu.au <URL:
     http://www.maths.uwa.edu.au/~adrian/> and Rolf Turner
     rolf@math.unb.ca <URL: http://www.math.unb.ca/~rolf>

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

        data(amacrine)

        # point patterns:
        # shift all points simultaneously
        X <- rtoro(amacrine)
        # shift "on" and "off" points separately
        X <- rtoro(amacrine, which=amacrine$marks)
        # shift "on" points and leave "off" points fixed
        X <- rtoro(amacrine, which="on")

        # splitppp objects:
        Y <- split(amacrine)
        # shift "on" and "off" points separately
        Z <- rtoro(Y)
        # shift "on" points and leave "off" points fixed
        Z <- rtoro(Y, "on")
        # shift all points simultaneously
        Z <- split(rtoro(superimpose(Y)))
        

