region.p_regions.azp module

class region.p_regions.azp.AZP(allow_move_strategy=None, random_state=None)

Bases: object

Class offering the implementation of the AZP algorithm (see [OR1995]).

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.

fit(adj, attr, n_regions, initial_labels=None, objective_func=<region.objective_function.ObjectiveFunctionPairwise object>)

Alias for fit_from_scipy_sparse_matrix().

Perform the AZP algorithm as described in [OR1995].

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

Parameters:
  • adj (scipy.sparse.csr_matrix) – Adjacency matrix representing the 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.
  • initial_labels (numpy.ndarray or None, default: None) – One-dimensional array of labels at the beginning of the algorithm. If None, then a random initial clustering will be generated.
  • objective_func (region.objective_function.ObjectiveFunction, default: ObjectiveFunctionPairwise()) – The objective function to use.
fit_from_dict(neighbor_dict, attr, n_regions, initial_labels=None, objective_func=<region.objective_function.ObjectiveFunctionPairwise object>)

Alternative API for fit_from_scipy_sparse_matrix().

Parameters:
  • neighbor_dict (dict) – Each key is an area and each value is an iterable of the key area’s neighbors.
  • attr (dict) – Each key is an area and each value is the corresponding clustering-relevant attribute.
  • n_regions (int) – Refer to the corresponding argument in fit_from_scipy_sparse_matrix().
  • initial_labels (dict or None, default: None) – Each key represents an area. Each value represents the region, the corresponding area is assigned to at the beginning of the algorithm. If None, then a random initial clustering will be generated.
  • objective_func (region.ObjectiveFunction, default: ObjectiveFunctionPairwise()) – Refer to the corresponding argument in fit_from_scipy_sparse_matrix().
fit_from_geodataframe(gdf, attr, n_regions, contiguity='rook', initial_labels=None, objective_func=<region.objective_function.ObjectiveFunctionPairwise object>)

Alternative API for fit_from_scipy_sparse_matrix().

Parameters:
  • gdf (geopandas.GeoDataFrame) –
  • attr (str or list) – The clustering-relevant attributes (columns of the GeoDataFrame gdf) are specified as string (for one column) or list of strings (for multiple columns).
  • n_regions (int) – 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.
  • initial_labels (numpy.ndarray or None, default: None) – Refer to the corresponding argument in fit_from_scipy_sparse_matrix().
  • objective_func (region.ObjectiveFunction, default: ObjectiveFunctionPairwise()) – Refer to the corresponding argument in fit_from_scipy_sparse_matrix().
fit_from_networkx(graph, attr, n_regions, initial_labels=None, objective_func=<region.objective_function.ObjectiveFunctionPairwise object>)

Alternative API for fit_from_scipy_sparse_matrix().

Parameters:
  • graph (networkx.Graph) – Graph representing the 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) – Refer to the corresponding argument in fit_from_scipy_sparse_matrix().
  • initial_labels (str or dict or None, default: None) – If str, then the string names the graph’s attribute holding the information about the initial clustering. If dict, then each key is a node and each value is the region the key area is assigned to at the beginning of the algorithm. If None, then a random initial clustering will be generated.
  • objective_func (region.ObjectiveFunction, default: ObjectiveFunctionPairwise()) – Refer to the corresponding argument in fit_from_scipy_sparse_matrix().
fit_from_scipy_sparse_matrix(adj, attr, n_regions, initial_labels=None, objective_func=<region.objective_function.ObjectiveFunctionPairwise object>)

Perform the AZP algorithm as described in [OR1995].

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

Parameters:
  • adj (scipy.sparse.csr_matrix) – Adjacency matrix representing the 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.
  • initial_labels (numpy.ndarray or None, default: None) – One-dimensional array of labels at the beginning of the algorithm. If None, then a random initial clustering will be generated.
  • objective_func (region.objective_function.ObjectiveFunction, default: ObjectiveFunctionPairwise()) – The objective function to use.
fit_from_w(w, attr, n_regions, initial_labels=None, objective_func=<region.objective_function.ObjectiveFunctionPairwise object>)

Alternative API for fit_from_scipy_sparse_matrix().

Parameters:
class region.p_regions.azp.AZPBasicTabu(tabu_length=None, repetitions_before_termination=5, random_state=None)

Bases: region.p_regions.azp.AZPTabu

Implementation of the AZP with basic tabu (refer to [OR1995]).

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.

class region.p_regions.azp.AZPReactiveTabu(max_iterations, k1, k2, random_state=None)

Bases: region.p_regions.azp.AZPTabu

Implementation of the AZP with reactive tabu (refer to [OR1995]).

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.

class region.p_regions.azp.AZPSimulatedAnnealing(init_temperature=None, max_iterations=inf, sa_moves_term=10, nonmoving_steps_before_stop=3, repetitions_before_termination=5, random_state=None)

Bases: object

Class offering the implementation of the AZP-SA algorithm (see [OR1995]).

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.

fit_from_dict(neighbor_dict, attr, n_regions, initial_labels=None, cooling_factor=0.85, objective_func=<region.objective_function.ObjectiveFunctionPairwise object>)
Parameters:
fit_from_geodataframe(gdf, attr, n_regions, contiguity='rook', initial_labels=None, cooling_factor=0.85, objective_func=<region.objective_function.ObjectiveFunctionPairwise object>)
Parameters:
fit_from_networkx(graph, attr, n_regions, initial_labels=None, cooling_factor=0.85, objective_func=<region.objective_function.ObjectiveFunctionPairwise object>)
Parameters:
fit_from_scipy_sparse_matrix(adj, attr, n_regions, initial_labels=None, cooling_factor=0.85, objective_func=<region.objective_function.ObjectiveFunctionPairwise object>)
Parameters:
fit_from_w(w, attr, n_regions, initial_labels=None, cooling_factor=0.85, objective_func=<region.objective_function.ObjectiveFunctionPairwise object>)
Parameters:
move_made_alert()
sa_moves_alert()
class region.p_regions.azp.AZPTabu(allow_move_strategy=None, random_state=None)

Bases: region.p_regions.azp.AZP, abc.ABC

Superclass for tabu variants of the AZP.

reset_tabu(tabu_len=None)