geographer.graph package¶

Submodules¶

geographer.graph.bipartite_graph module¶

Simple class for bipartite graphs.

Implements graphs adjacency list-style as (dict-of)-dict-of-dicts.

Example: A graph with

vertex colors ‘red’ and ‘black’
red vertices ‘r1’, ‘r2’ and black vertices ‘b1’, ‘b2’, ‘b3’
an edge with edge data ‘foo’ between ‘r1’ and ‘b1’ and an edge with edge data ‘bar’ between ‘r1’ and ‘b3’

is encoded as the dict of dicts of dicts:

{
    'red':
        {
            'r1': {'b1': 'foo', 'b3': 'bar'},
            'r2': {},
            'r3': {}
        }

    'black':
        {
            'b1': {'r1': 'foo'},
            'b2': {},
            'b3': {'r1': 'bar'}
        }
}

Only tested for the undirected case.

class geographer.graph.bipartite_graph.BipartiteGraph(graph_dict=None, file_path=None, red=None, black=None, directed=False)[source]¶

Bases: BipartiteGraphClass

Class implementing bipartite graphs.

Simple adjacency list-style dict-of-dicts (sort of) implementation of a bipartite graph (a vertex is thought of as being either red or black) which can be serialized in/read in from a json file. The graph can be directed or not and the edges can have extra data. e.g. a name, a color, a weight, possibly even composite data in the form of tuples, though I haven’t checked if that plays well with json. The vertices have to be hashable, e.g. strings.

Parameters:

graph_dict (dict | None)
file_path (Path | None)
red (VertexColor)
black (VertexColor)
directed (bool)

__eq__(other)[source]¶

Check equality of graphs.

Two graphs are equal if the vertex sets and colors and the edge sets and edge data agree, which is tested by asking whether the underlying dicts are equal.

Return type:: bool
Parameters:: other (BipartiteGraph)
Returns:: True if the graphs are equal, False otherwise.

__init__(graph_dict=None, file_path=None, red=None, black=None, directed=False)[source]¶

Construct graph from graph dict or json file.

Construct from either a dict (of dicts of dicts) or from a json file serializing such a dict. The encoding is such that graph_dict[vertex1_color][vertex1][vertex2] is the edge data between vertex1 (of a certain color vertex1_color) and vertex2 (of the opposite color). A vertex v of color c without an edge is encoded by having graph_dict[c][v] be the empty dict. A directed graph is encoded as an undirected graph with edges in both directions.

Parameters:

graph_dict (dict | None) – dict (of dicts of dicts) defining a bipartite graph. See example in module header.
file_path (Path | None) – path to .json containing such a dict.
red (Hashable | None) – vertex color, defaults to ‘red’.
black (Hashable | None) – vertex color, defaults to ‘black.
directed (bool) – If True the graph is directed, defaults to False.

__opposite_color__(color)¶

Return opposite color.

Return type:: Hashable
Parameters:: color (Hashable)

__str__()[source]¶

Return string representation of the graph.

Args: :returns: string representation of the graph. :rtype: (str)

add_edge(from_vertex, from_vertex_color, to_vertex, edge_data, force=False)[source]¶

Add an edge to the graph.

If the vertices do not yet exist will create them. Throws an error if an edge between the vertices already exists unless force is True, in which case it overwrites the existing edge_data.

Parameters:

from_vertex (Hashable)
from_color
to_vertex (Hashable)
edge_data (Any)
force (bool)
from_vertex_color (Hashable)

add_vertex(vertex_name, vertex_color)[source]¶

Add a vertex to the graph.

Parameters:

vertex_name (Hashable)
vertex_color (Hashable)

colors()[source]¶

Return vertex colors.

Return type:: list[Hashable]

delete_edge(from_vertex, from_vertex_color, to_vertex)[source]¶

Delete an edge from the graph.

Delete the edge between vertices from_vertex of color from_vertex_color and to_vertex.

Parameters:

from_vertex (Hashable)
from_vertex_color (Hashable)
to_vertex (Hashable)

delete_vertex(vertex_name, vertex_color, force_delete_with_edges=True)[source]¶

Delete a vertex from the graph.

If force==False, will delete only if the vertex has no edges. If force==True, will also delete edges starting or ending at the vertex. Note that in that case we don’t delete dangling opposite vertices (i.e. opposite vertices that don’t have any edges left after this). Only implemented for directed graphs.

Parameters:

vertex_name (Hashable)
vertex_color (Hashable)
force_delete_with_edges

edge_data(from_vertex, from_color, to_vertex)[source]¶

Return edge data.

Return type:

Any

Parameters:

from_vertex (Hashable)
from_color (Hashable)
to_vertex (Hashable)

exists_edge(from_vertex, from_vertex_color, to_vertex, edge_data=None)[source]¶

Return True if the edge is in the graph, False otherwise.

Return type:

bool

Parameters:

from_vertex (Hashable)
from_vertex_color (Hashable)
to_vertex (Hashable)
edge_data (Any | None)

exists_vertex(vertex_name, vertex_color)[source]¶

Return True if the vertex is in the graph, False otherwise.

Return type:

bool

Parameters:

vertex_name (Hashable)
vertex_color (Hashable)

really_undirected()[source]¶

Check if graph is really undirected.

Check if graph is really undirected, i.e. if for each edge the opposite edge exists as well. Useful for testing.

Return type:: bool
Returns:: True if graph is undirected, False if it’s not.

save_to_file(file_path=None)[source]¶

Save graph (i.e. graph_dict) to disk as json file.

Parameters:: file_path (Path | None) – path of json file to save graph to.

vertices(color)[source]¶

Return vertices of a given color.

Return type:: list[Hashable]
Parameters:: color (Hashable)

vertices_opposite(vertex_name, vertex_color, edge_data=None)[source]¶

Return list of adjacent vertices.

Since our graph is bipartite, these are always of the opposite color, hence ‘opposite’.

Return type:

list[Hashable]

Parameters:

vertex_name (Hashable)
vertex_color (Hashable)
edge_data (Any | None)

geographer.graph.bipartite_graph.empty_bipartite_graph(red='red', black='black')[source]¶

Return empty bipartite graph.

Parameters:

red – vertex color. Defaults to “red”.
black – vertex color. Defaults to “black”.

Returns:

empty graph

geographer.graph.bipartite_graph.empty_graph_dict(red='red', black='black')[source]¶

Return graph dict of empty bipartite graph.

Parameters:

red – vertex color. Defaults to “red”.
black – vertex color. Defaults to “black”.

Returns:

graph dict of empty graph

geographer.graph.bipartite_graph_class module¶

ABC for bipartite graphs.

class geographer.graph.bipartite_graph_class.BipartiteGraphClass[source]¶

Bases: ABC

ABC for bipartite graphs.

The decomposition of a vertex set into two sets are thought of as vertex colors, e.g. red or black.

The graph can be directed or not and the edges can have extra data. e.g. a name, a color, a weight, possibly even composite data in the form of tuples.

__opposite_color__(color)[source]¶

Return opposite color.

Return type:: Hashable
Parameters:: color (Hashable)

__str__()[source]¶

Return str repr.

Return type:: str

add_edge(from_vertex, from_vertex_color, to_vertex, edge_data, force=False)[source]¶

Add edge to graph.

Parameters:

from_vertex (Hashable)
from_vertex_color (Hashable)
to_vertex (Hashable)
edge_data (Any)
force (bool)

add_vertex(vertex_name, vertex_color)[source]¶

Add a vertex to the graph.

Parameters:

vertex_name (Hashable)
vertex_color (Hashable)

colors()[source]¶

Return vertex colors.

Return type:: list[Hashable]

delete_edge(from_vertex, from_vertex_color, to_vertex)[source]¶

Delete edge from graph.

Parameters:

from_vertex (Hashable)
from_vertex_color (Hashable)
to_vertex (Hashable)

delete_vertex(vertex_name, vertex_color, force_delete_with_edges=True)[source]¶

Delete vertex from graph.

Parameters:

vertex_name (Hashable)
vertex_color (Hashable)

edge_data(from_vertex, from_color, to_vertex)[source]¶

Return edge data.

Return type:

Any

Parameters:

from_vertex (Hashable)
from_color (Hashable)
to_vertex (Hashable)

exists_edge(from_vertex, from_vertex_color, to_vertex, edge_data)[source]¶

Return True if the edge is in the graph, False otherwise.

Return type:

bool

Parameters:

from_vertex (Hashable)
from_vertex_color (Hashable)
to_vertex (Hashable)
edge_data (Any | None)

exists_vertex(vertex_name, vertex_color)[source]¶

Return True if the vertex is in the graph, False otherwise.

Return type:

bool

Parameters:

vertex_name (Hashable)
vertex_color (Hashable)

really_undirected()[source]¶

Return True if graph is really undirected.

Return type:: bool

save_to_file(file_path=None)[source]¶

Save graph to file.

Parameters:: file_path (Path | None)

vertices(color)[source]¶

Return vertices of a given color.

Return type:: list[Hashable]
Parameters:: color (Hashable)

vertices_opposite(vertex_name, vertex_color, edge_data=None)[source]¶

Return list of adjacent vertices.

Return type:

list[Hashable]

Parameters:

vertex_name (Hashable)
vertex_color (Hashable)
edge_data (Any | None)

geographer.graph.bipartite_graph_mixin module¶

Mix-in for manipulating a connector’s internal graph.

class geographer.graph.bipartite_graph_mixin.BipartiteGraphMixIn[source]¶

Bases: object

Mix-in that interfaces with a connector’s internal graph.

does_raster_contain_vector(raster_name, vector_name)[source]¶

Return whether a raster fully contains a vector feature.

Return type:

bool

Parameters:

raster_name (str) – Name of raster
vector_name (str) – name of vector feature

Returns:

True or False depending on whether the raster contains the vector feature or not

does_raster_intersect_vector(raster_name, vector_name)[source]¶

Return whether a vector feature intersects a raster.

Return type:

bool

Parameters:

raster_name (str) – Name of raster
vector_name (str) – name of vector feature

Returns:

True or False depending on whether the raster intersects the vector feature or not

does_vector_intersect_raster(vector_name, raster_name)[source]¶

Return whether a vector feature intersects a raster.

Return type:

bool

Parameters:

raster_name (str) – Name of raster
vector_name (str) – name of vector feature

Returns:

True or False depending on whether the vector feature intersects the raster or not

have_raster_for_vector(vector_name)[source]¶

Check if there is a raster fully containing the vector feature.

Return type:: bool
Parameters:: vector_name (str) – Name of vector feature
Returns:: True if there is a raster in the dataset fully containing the vector feature, False otherwise.

is_vector_contained_in_raster(vector_name, raster_name)[source]¶

Return True if a vector feature is fully contained in a raster.

Return type:

bool

Parameters:

raster_name (str) – Name of raster
vector_name (str) – name of vector feature

Returns:

True or False depending on whether the vector feature contains the raster or not

rasters_containing_vector(vector_name, mode='names')[source]¶

Return rasters in which a given vector feature is fully contained.

If multiple vector features are given, return raster which contain at least one of the vector features.

Return type:

list[str]

Parameters:

vector_name (str | list[str]) – name/id (or list of names) of vector feature(s)
mode (Literal['names', 'paths']) – One of ‘names’ or ‘paths’. In the former case the raster names are
'names'. (returned in the latter case paths to the rasters. Defaults to)

Returns:

raster_names/identifiers of all rasters in connector containing the vector feature(s)

rasters_intersecting_vector(vector_name, mode='names')[source]¶

Return rasters intersecting several vector feature(s).

If more than one vector feature is given, return rasters intersecting at least one of the vector features.

Return type:

list[str]

Parameters:

vector_name (str | list[str]) – name/id (or list) of vector feature(s)
mode (Literal['names', 'paths']) – One of ‘names’ or ‘paths’. In the former case the raster names are
'names'. (returned in the latter case paths to the rasters. Defaults to)

Returns:

vector_names/identifiers of all vector features in connector with non-empty intersection with the raster.

rectangle_bounding_raster(raster_name)[source]¶

Return shapely geometry bounding a raster.

The geometry is with respect to the connector’s (standard) crs.

Return type:: BaseGeometry
Parameters:: raster_name (str) – the raster_name/identifier of the raster
Returns:: shapely geometry giving the bounds of the raster in the standard crs of the connector

vectors_contained_in_raster(raster_name)[source]¶

Return vector features fully containing a given raster.

If several rasters are given return vector features fully containing any of the rasters.

Return type:: list[str]
Parameters:: raster_name (str | list[str]) – name/id of raster or list of names/ids of rasters
Returns:: vector_names/identifiers of all vector features in connector contained in the raster(s).

vectors_intersecting_raster(raster_name)[source]¶

Return vector features intersecting one or (any of) several rasters.

Return type:: list[str]
Parameters:: raster_name (str | list[str]) – name/id of raster or list names/ids
Returns:: list of vector_names/ids of all vector features in connector which have non-empty intersection with the raster(s)

geographer.graph.type_aliases module¶

Type aliases for the graph code.

Module contents¶

Code for bipartite graphs used by the associator.