constructive_geometries

Simple tools to define world locations from a set of topological faces and set algebra. For example, one could define a “rest of the world” which started from all countries, but excluded every country who name started with the letter “a”.

No requirements for basic use, but needs shapely, and fiona for any GIS functions.

Note

See the usage example

Installation

Because of the GIS library dependencies, it is easiest to install using `conda <>`__. Installation into a new environment is recommended (doesn’t need to be called cg):

conda create -n cg python=3.6
source activate cg
conda install -c conda-forge -c cmutel -c konstantinstadler country_converter constructive_geometries

ConstructiveGeometries class

class constructive_geometries.cg.ConstructiveGeometries

check_data()

Check that definitions file is present, and that faces file is readable.

construct_difference(parent, excluded, name=None, fp=None)

Construct geometry from parent without the regions in excluded and optionally write to filepath fp.

excluded must be an iterable of location strings (not face ids).

construct_rest_of_world(excluded, name=None, fp=None, geom=True)

Construct rest-of-world geometry and optionally write to filepath fp.

Excludes faces in location list excluded. excluded must be an iterable of location strings (not face ids).

construct_rest_of_worlds(excluded, fp=None, use_mp=True, simplify=True)

Construct many rest-of-world geometries and optionally write to filepath fp.

excluded must be a dictionary of {“rest-of-world label”: [“names”, “of”, “excluded”, “locations”]}``.

construct_rest_of_worlds_mapping(excluded, fp=None)

Construct topo mapping file for excluded.

excluded must be a dictionary of {“rest-of-world label”: [“names”, “of”, “excluded”, “locations”]}``.

Topo mapping has the data format:

{
    'data': [
        ['location label', ['topo face integer ids']],
    ],
    'metadata': {
        'filename': 'name of face definitions file',
        'field': 'field with uniquely identifies the fields in ``filename``',
        'sha256': 'SHA 256 hash of ``filename``'
    }
}

load_definitions()

Load mapping of country names to face ids

write_geoms_to_file(fp, geoms, names=None)

Write unioned geometries geoms to filepath fp. Optionally use names in name field.

Geomatcher class

class constructive_geometries.geomatcher.Geomatcher(topology='ecoinvent', default_namespace=None, use_coco=True)

Object managing spatial relationships using the a world topology.

Geomatcher takes as its base data a definition of the world split into topological faces. This definition is provided by the `constructive_geometries <>`__ library. A toplogical face is a polygon which does not overlap any other topological face. In constructive_geometries, these faces are defined by integer ids, so e.g. Ireland is:

>>> from constructive_geometries import ConstructiveGeometries
>>> cg = ConstructiveGeometries()
>>> cg.data['IE']
[325, 327, 328, 334, 336, 337, 338, 345, 346, 347, 348, 350, 374, 2045]

By default, Geomatcher is populated with all world countries, and all ecoinvent regions. The instance of Geomatcher created in this file also includes the IMAGE world regions.

Geospatial definitions are namespaced, except for countries. Countries are therefore defined by their ISO two-letter codes, but other data should be referenced by a tuple of its namespace and identifier, e.g. ('ecoinvent', 'NAFTA'). You can also set a default namespace, either in instantiation (Geomatcher(default_namespace="foo")) or afterwards (geomatcher_instance.default_namespace = 'foo'). The default namespace is 'ecoinvent'.

Geomatcher supports the following operations:

• Retrieving face ids for a given location, acting as a dictionary (geomatcher['foo'])
• Adding new geospatial definitions, either directly with face ids or relative to existing definitions
• Splitting faces to allow for finer-scale regionalization
• Intersection, contained, and within calculations with several configuration options.

Initialization arguments:

• topology: A dictionary of {str: set} labels to faces ids. Default is ecoinvent, which loads the world and ecoinvent definitions from constructive_geometries.
• default_namespace: String defining the default search namespace. Default is 'ecoinvent'.
• use_coco: Boolean, default True. Use the country_converter library to fuzzy match country identifiers, e.g. “Austria” instead of “AT”.

add_definitions(data, namespace, relative=True)

Add new topological definitions to self.topology.

If relative is true, then data is defined relative to the existing locations already in self.topology, e.g. IMAGE:

{"Russia Region": [
    "AM",
    "AZ",
    "GE",
    "RU"
]}

Otherwise, data is a dictionary with string keys and values of integer topology face id sets:

{
    'A': {1, 2, 3},
    'B': {2, 3, 4},
}

contained(key, include_self=True, exclusive=False, biggest_first=True, only=None)

Get all locations that are completely within this location.

If the resolved_row context manager is not used, RoW doesn’t have a spatial definition. Therefore, .contained("RoW") returns a list with either RoW or nothing.

intersects(key, include_self=False, exclusive=False, biggest_first=True, only=None)

Get all locations that intersect this location.

Note that sorting is done by first by number of faces intersecting key; the total number of faces in the intersected region is only used to break sorting ties.

If the resolved_row context manager is not used, RoW doesn’t have a spatial definition, and therefore nothing intersects it. .intersects("RoW") returns a list with with RoW or nothing.

split_face(face, number=None, ids=None)

Split a topological face into a number of small faces.

• face: The face to split. Must be in the topology.
• number: Number of new faces to create. Optional, can be inferred from ids. Default is 2 new faces.
• ids: Iterable of new face ids. Optional, default is the maximum integer in the existing topology plus one. ids don’t have to be integers. If ids is specified, number is ignored.

Returns the new face ids.

within(key, include_self=True, exclusive=False, biggest_first=True, only=None)

Get all locations that completely contain this location.

If the resolved_row context manager is not used, RoW doesn’t have a spatial definition. Therefore, RoW can only be contained by GLO and RoW.