region.p_regions.exact module

class region.p_regions.exact.PRegionsExact

Bases: object

A class for solving the p-regions problem by transforming it into a mixed-integer-programming problem (MIP) as described in [DCM2011].

labels_

numpy.ndarray – Each element is a region label specifying to which region the corresponding area was assigned to by the last run of a fit-method.

method

str – The method used in the last call of a fit-method for translating the p-regions problem into an MIP.

metric

function – The distance metric specified in the last call of a fit-method.

n_regions

int – The number of regions the areas were clustered into by the last run of a fit-method.

solver

str – The solver used in the last call of a fit-method.

fit(adj, attr, n_regions, method='flow', solver='cbc', metric='euclidean')

Alias for fit_from_scipy_sparse_matrix().

Solve the p-regions problem as MIP as described in [DCM2011].

The resulting region labels are assigned to the instance’s labels_ attribute.

Parameters:
  • adj (class:scipy.sparse.csr_matrix) – Adjacency matrix representing the areas’ contiguity relation.
  • attr (numpy.ndarray) – Array (number of areas x number of attributes) of areas’ attributes relevant to clustering.
  • n_regions (int) – Number of desired regions.
  • method ({"flow", "order", "tree"}, default: "flow") –

    The method to translate the clustering problem into an exact optimization model.

    • ”flow” - Flow model on p. 112-113 in [DCM2011]
    • ”order” - Order model on p. 110-112 in [DCM2011]
    • ”tree” - Tree model on p. 108-110 in [DCM2011]
  • solver ({"cbc", "cplex", "glpk", "gurobi"}, default: "cbc") –

    The solver to use. Unless the default solver is used, the user has to make sure that the specified solver is installed.

    • ”cbc” - the Cbc (Coin-or branch and cut) solver
    • ”cplex” - the CPLEX solver
    • ”glpk” - the GLPK (GNU Linear Programming Kit) solver
    • ”gurobi” - the Gurobi Optimizer
  • metric (str or function, default: "euclidean") – See the metric argument in region.util.get_metric_function().
fit_from_dict(neighbors_dict, attr, n_regions, method='flow', solver='cbc', metric='euclidean')

Alternative API for fit_from_scipy_sparse_matrix().

Parameters:
fit_from_geodataframe(gdf, attr, n_regions, method='flow', solver='cbc', metric='euclidean', contiguity='rook')

Alternative API for fit_from_scipy_sparse_matrix().

Parameters:
  • gdf (GeoDataFrame) –
  • attr (str or list) – The clustering criteria (columns of the GeoDataFrame gdf) are specified as string (for one column) or list of strings (for multiple columns).
  • n_regions (int) – See the corresponding argument in fit_from_scipy_sparse_matrix().
  • method (str) – See the corresponding argument in fit_from_scipy_sparse_matrix().
  • solver (str) – See the corresponding argument in fit_from_scipy_sparse_matrix().
  • contiguity ({"rook", "queen"}, default: "rook") –

    Defines the contiguity relationship between areas. Possible contiguity definitions are:

    • ”rook” - Rook contiguity.
    • ”queen” - Queen contiguity.
  • metric (str or function, default: "euclidean") – See the corresponding argument in fit_from_scipy_sparse_matrix().
fit_from_networkx(graph, attr, n_regions, method='flow', solver='cbc', metric='euclidean')

Alternative API for fit_from_scipy_sparse_matrix().

Parameters:
  • graph (networkx.Graph) – Graph representing the areas’ contiguity relation.
  • attr (str, list or dict) – If the clustering criteria are present in the networkx.Graph graph as node attributes, then they can be specified as a string (for one criterion) or as a list of strings (for multiple criteria). Alternatively, a dict can be used with each key being a node of the networkx.Graph graph and each value being the corresponding clustering criterion (a scalar (e.g. float or int) or a numpy.ndarray). If there are no clustering criteria present in the networkx.Graph graph as node attributes, then a dictionary must be used for this argument. Refer to the corresponding argument in fit_from_dict() for more details about the expected dict.
  • n_regions (int) – See the corresponding argument in fit_from_scipy_sparse_matrix().
  • method (str) – See the corresponding argument in fit_from_scipy_sparse_matrix().
  • solver (str) – See the corresponding argument in fit_from_scipy_sparse_matrix().
  • metric (str or function, default: "euclidean") – See the corresponding argument in fit_from_scipy_sparse_matrix().
fit_from_scipy_sparse_matrix(adj, attr, n_regions, method='flow', solver='cbc', metric='euclidean')

Solve the p-regions problem as MIP as described in [DCM2011].

The resulting region labels are assigned to the instance’s labels_ attribute.

Parameters:
  • adj (class:scipy.sparse.csr_matrix) – Adjacency matrix representing the areas’ contiguity relation.
  • attr (numpy.ndarray) – Array (number of areas x number of attributes) of areas’ attributes relevant to clustering.
  • n_regions (int) – Number of desired regions.
  • method ({"flow", "order", "tree"}, default: "flow") –

    The method to translate the clustering problem into an exact optimization model.

    • ”flow” - Flow model on p. 112-113 in [DCM2011]
    • ”order” - Order model on p. 110-112 in [DCM2011]
    • ”tree” - Tree model on p. 108-110 in [DCM2011]
  • solver ({"cbc", "cplex", "glpk", "gurobi"}, default: "cbc") –

    The solver to use. Unless the default solver is used, the user has to make sure that the specified solver is installed.

    • ”cbc” - the Cbc (Coin-or branch and cut) solver
    • ”cplex” - the CPLEX solver
    • ”glpk” - the GLPK (GNU Linear Programming Kit) solver
    • ”gurobi” - the Gurobi Optimizer
  • metric (str or function, default: "euclidean") – See the metric argument in region.util.get_metric_function().
fit_from_w(w, attr, n_regions, method='flow', solver='cbc', metric='euclidean')

Alternative API for fit_from_scipy_sparse_matrix().

Parameters: