# spopt.region.RandomRegions

class spopt.region.RandomRegions(area_ids, num_regions=None, cardinality=None, contiguity=None, maxiter=100, compact=False, max_swaps=1000000, permutations=99)

  Generate a list of RandomRegion instances.

  Parameters:
    area_ids `python:list`

      The IDs indexing the areas to be grouped into regions (must be in the same order as spatial weights matrix if this is provided).

    num_regions `python:int` (default `python:None`)

      The number of regions to generate (if `None` then this is chosen randomly from 2 to \(n\) where \(n\) is the number of areas).

    cardinality `python:list` (default `python:None`)

      A list containing the number of areas to assign to regions (if `num_regions` is also provided then `len(cardinality)` must equal `num_regions`; if `None` then a list of length `num_regions` will be generated randomly).

    contiguity `libpysal.weights.W` (default `python:None`)

      A spatial weights object (if `None` then contiguity will be ignored).

    maxiter `python:int` (default 100)

      The maximum number attempts (for each permutation) at finding a feasible solution (only affects contiguity constrained regions).

    compact bool (default `python:False`)

      Attempt to build compact regions (only affects contiguity constrained regions).

    max_swaps `python:int` (default 1000000)

      The maximum number of swaps to find a feasible solution (only affects contiguity constrained regions).

    permutations `python:int` (default 99)

      The number of `RandomRegion` instances to generate.

  Attributes:
    solutions `python:list`

      A list of length `permutations` containing all `RandomRegion` instances generated.

    solutions_feas `python:list`

      A list of the `RandomRegion` instances that resulted in feasible solutions.

  Examples

  Setup the data.

      >>> import libpysal
      >>> import numpy
      >>> from spopt.region import RandomRegions, RandomRegion
      >>> nregs = 13
      >>> cards = list(range(2,14)) + [10]
      >>> w = libpysal.weights.lat2W(10,10,rook=True)
      >>> ids = w.id_order

  Unconstrained:

      >>> numpy.random.seed(10)
      >>> t0 = RandomRegions(ids, permutations=2)
      >>> t0.solutions[0].regions[0]
      [19, 14, 43, 37, 66, 3, 79, 41, 38, 68, 2, 1, 60]

  Cardinality and contiguity constrained (`num_regions` implied):

      >>> numpy.random.seed(60)
      >>> t1 = RandomRegions(
      ...     ids, num_regions=nregs, cardinality=cards, contiguity=w, permutations=2
      ... )
      >>> t1.solutions[0].regions[0]
      [62, 61, 81, 71, 64, 90, 72, 51, 80, 63, 50, 73, 52]

  Cardinality constrained (`num_regions` implied):

      >>> numpy.random.seed(100)
      >>> t2 = RandomRegions(
      ...     ids, num_regions=nregs, cardinality=cards, permutations=2
      ... )
      >>> t2.solutions[0].regions[0]
      [37, 62]

  Number of regions and contiguity constrained:

      >>> numpy.random.seed(100)
      >>> t3 = RandomRegions(ids, num_regions=nregs, contiguity=w, permutations=2)
      >>> t3.solutions[0].regions[1]
      [62, 52, 51, 63, 61, 73, 41, 53, 60, 83, 42, 31, 32]

  Cardinality and contiguity constrained:

      >>> numpy.random.seed(60)
      >>> t4 = RandomRegions(ids, cardinality=cards, contiguity=w, permutations=2)
      >>> t4.solutions[0].regions[0]
      [62, 61, 81, 71, 64, 90, 72, 51, 80, 63, 50, 73, 52]

  Number of regions constrained:

      >>> numpy.random.seed(100)
      >>> t5 = RandomRegions(ids, num_regions=nregs, permutations=2)
      >>> t5.solutions[0].regions[0]
      [37, 62, 26, 41, 35, 25, 36]

  Cardinality constrained:

      >>> numpy.random.seed(100)
      >>> t6 = RandomRegions(ids, cardinality=cards, permutations=2)
      >>> t6.solutions[0].regions[0]
      [37, 62]

  Contiguity constrained:

      >>> numpy.random.seed(100)
      >>> t7 = RandomRegions(ids, contiguity=w, permutations=2)
      >>> t7.solutions[0].regions[1]
      [62, 61, 71, 63]

  __init__(area_ids, num_regions=None, cardinality=None, contiguity=None, maxiter=100, compact=False, max_swaps=1000000, permutations=99)

  Methods

  `__init__`(area_ids[, num_regions, ...]) |