# libpysal.weights.w_clip

libpysal.weights.w_clip(w1, w2, outSP=True, **kwargs)

  Clip a continuous W object (w1) with a different W object (w2) so only cells where w2 has a non-zero value remain with non-zero values in w1.

  Checks on w1 and w2 are performed to make sure they conform to the appropriate format and, if not, they are converted.

  Parameters:
    w1 `W`

      W, scipy.sparse.csr.csr_matrix Potentially continuous weights matrix to be clipped. The clipped matrix wc will have at most the same elements as w1.

    w2 `W`

      W, scipy.sparse.csr.csr_matrix Weights matrix to use as shell to clip w1. Automatically converted to binary format. Only non-zero elements in w2 will be kept non-zero in wc. NOTE: assumed to be of the same shape as w1

    outSP bool

      If True (default) return sparse version of the clipped W, if False, return W object of the clipped matrix

    **kwargs `keyword` `arguments`

      optional arguments for `pysal.weights.W`

  Returns:
    wc `W`

      W, scipy.sparse.csr.csr_matrix Clipped W object (sparse if outSP=Ture). It inherits `id_order` from w1.

  Examples

      >>> from libpysal.weights import lat2W

  First create a W object from a lattice using queen contiguity and row-standardize it (note that these weights will stay when we clip the object, but they will not neccesarily represent a row-standardization anymore):

      >>> w1 = lat2W(3, 2, rook=False)
      >>> w1.transform = 'R'

  We will clip that geography assuming observations 0, 2, 3 and 4 belong to one group and 1, 5 belong to another group and we don’t want both groups to interact with each other in our weights (i.e. w_ij = 0 if i and j in different groups). For that, we use the following method:

      >>> import libpysal
      >>> w2 = libpysal.weights.block_weights(['r1', 'r2', 'r1', 'r1', 'r1', 'r2'])

  To illustrate that w2 will only be considered as binary even when the object passed is not, we can row-standardize it

      >>> w2.transform = 'R'

  The clipped object `wc` will contain only the spatial queen relationships that occur within one group (‘r1’ or ‘r2’) but will have gotten rid of those that happen across groups

      >>> wcs = libpysal.weights.w_clip(w1, w2, outSP=True)

  This will create a sparse object (recommended when n is large).

      >>> wcs.sparse.toarray()
      array([[0.        , 0.        , 0.33333333, 0.33333333, 0.        ,
              0.        ],
             [0.        , 0.        , 0.        , 0.        , 0.        ,
              0.        ],
             [0.2       , 0.        , 0.        , 0.2       , 0.2       ,
              0.        ],
             [0.2       , 0.        , 0.2       , 0.        , 0.2       ,
              0.        ],
             [0.        , 0.        , 0.33333333, 0.33333333, 0.        ,
              0.        ],
             [0.        , 0.        , 0.        , 0.        , 0.        ,
              0.        ]])

  If we wanted an original W object, we can control that with the argument `outSP`:

      >>> wc = libpysal.weights.w_clip(w1, w2, outSP=False)
      >>> wc.full()[0]
      array([[0.        , 0.        , 0.33333333, 0.33333333, 0.        ,
              0.        ],
             [0.        , 0.        , 0.        , 0.        , 0.        ,
              0.        ],
             [0.2       , 0.        , 0.        , 0.2       , 0.2       ,
              0.        ],
             [0.2       , 0.        , 0.2       , 0.        , 0.2       ,
              0.        ],
             [0.        , 0.        , 0.33333333, 0.33333333, 0.        ,
              0.        ],
             [0.        , 0.        , 0.        , 0.        , 0.        ,
              0.        ]])

  You can check they are actually the same:

      >>> wcs.sparse.toarray() == wc.full()[0]
      array([[ True,  True,  True,  True,  True,  True],
             [ True,  True,  True,  True,  True,  True],
             [ True,  True,  True,  True,  True,  True],
             [ True,  True,  True,  True,  True,  True],
             [ True,  True,  True,  True,  True,  True],
             [ True,  True,  True,  True,  True,  True]])