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 inexcluded
and optionally write to filepathfp
.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 filepathfp
. Optionally usenames
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. Inconstructive_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 isecoinvent
, which loads the world and ecoinvent definitions fromconstructive_geometries
.default_namespace
: String defining the default search namespace. Default is'ecoinvent'
.use_coco
: Boolean, defaultTrue
. 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, thendata
is defined relative to the existing locations already inself.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 eitherRoW
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 withRoW
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 fromids
. 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. Ifids
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 byGLO
andRoW
.
- Retrieving face ids for a given location, acting as a dictionary (