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 infit_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 infit_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 infit_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 infit_from_dict()
for more details about the expected dict. - threshold (numbers.Real or
numpy.ndarray
) – Refer to the corresponding argument infit_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: - w (libpysal.weights.W) – W object representing the areas’ contiguity relation.
- attr (
numpy.ndarray
) – See the corresponding argument infit_from_scipy_sparse_matrix()
. - spatially_extensive_attr (
numpy.ndarray
) – See the corresponding argument infit_from_scipy_sparse_matrix()
. - threshold (numbers.Real or
numpy.ndarray
) – Refer to the corresponding argument infit_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()
.
-