region.max_p_regions.exact module

class region.max_p_regions.exact.MaxPRegionsExact

Bases: object

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

labels_

dict – Each key is an area and each value the region it has been assigned to.

fit(adj, attr, spatially_extensive_attr, threshold, solver='cbc', metric='euclidean')

Alias for fit_from_scipy_sparse_matrix().

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

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.
  • spatially_extensive_attr (numpy.ndarray) – Array (number of areas x number of attributes) of areas’ attributes relevant to ensuring the threshold condition.
  • threshold (numbers.Real or numpy.ndarray) – The lower bound for a region’s sum of spatially extensive attributes. The argument’s type is numbers.Real if there is only one spatially extensive attribute per area, otherwise it is a one-dimensional array with as many entries as there are spatially extensive attributes per area.
  • 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, spatially_extensive_attr, threshold, solver='cbc', metric='euclidean')

Alternative API for fit_from_scipy_sparse_matrix().

Parameters:
  • neighbors_dict (dict) – Each key represents an area and each value is an iterable of neighbors of this area.
  • attr (dict) – A dict with the same keys as neighbors_dict and values representing the attributes for calculating homo-/heterogeneity. A value can be scalar (e.g. float or int) or a numpy.ndarray.
  • spatially_extensive_attr (dict) – A dict with the same keys as neighbors_dict and values representing the spatially extensive attribute (scalar or iterable of scalars). In the max-p-regions problem each region’s sum of spatially extensive attributes must be greater than a specified threshold. In case of iterables of scalars as dict-values all elements of the iterable have to fulfill the condition.
  • threshold (numbers.Real or numpy.ndarray) – Refer to the corresponding argument in fit_from_scipy_sparse_matrix().
  • solver ({"cbc", "cplex", "glpk", "gurobi"}, default: "cbc") – Refer to the corresponding argument in fit_from_scipy_sparse_matrix().
  • metric (str or function, default: "euclidean") – Refer to the corresponding argument in fit_from_scipy_sparse_matrix().
fit_from_geodataframe(gdf, attr, spatially_extensive_attr, threshold, 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).
  • spatially_extensive_attr (str or list) – The name (str) or names (list of strings) of column(s) in gdf containing the spatially extensive attributes.
  • threshold (numbers.Real or numpy.ndarray) – Refer to the corresponding argument in fit_from_scipy_sparse_matrix().
  • solver ({"cbc", "cplex", "glpk", "gurobi"}, default: "cbc") – Refer to the corresponding argument in fit_from_scipy_sparse_matrix().
  • metric (str or function, default: "euclidean") – Refer to 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.
fit_from_networkx(graph, attr, spatially_extensive_attr, threshold, solver='cbc', metric='euclidean')

Alternative API for fit_from_scipy_sparse_matrix().

Parameters:
  • graph (networkx.Graph) –
  • 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.
  • spatially_extensive_attr (str, list or dict) – If the spatially extensive attribute is present in the networkx.Graph graph as node attributes, then they can be specified as a string (for one attribute) or as a list of strings (for multiple attributes). Alternatively, a dict can be used with each key being a node of the networkx.Graph graph and each value being the corresponding spatially extensive attribute (a scalar (e.g. float or int) or a numpy.ndarray). If there are no spatially extensive attributes 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.
  • threshold (numbers.Real or numpy.ndarray) – Refer to the corresponding argument in fit_from_scipy_sparse_matrix().
  • solver ({"cbc", "cplex", "glpk", "gurobi"}, default: "cbc") – Refer to the corresponding argument in fit_from_scipy_sparse_matrix().
  • metric (str or function, default: "euclidean") – Refer to the corresponding argument in fit_from_scipy_sparse_matrix().
fit_from_scipy_sparse_matrix(adj, attr, spatially_extensive_attr, threshold, solver='cbc', metric='euclidean')

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

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.
  • spatially_extensive_attr (numpy.ndarray) – Array (number of areas x number of attributes) of areas’ attributes relevant to ensuring the threshold condition.
  • threshold (numbers.Real or numpy.ndarray) – The lower bound for a region’s sum of spatially extensive attributes. The argument’s type is numbers.Real if there is only one spatially extensive attribute per area, otherwise it is a one-dimensional array with as many entries as there are spatially extensive attributes per area.
  • 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, spatially_extensive_attr, threshold, solver='cbc', metric='euclidean')

Alternative API for fit_from_scipy_sparse_matrix().

Parameters: