Skip to content

flowmachine.core.spatial_unit

Source: flowmachine/core/spatial_unit.py

Classes that map cell (or tower or site) IDs to a spatial unit. The helper function 'make_spatial_unit' can be used to create spatial unit objects.

Class AdminSpatialUnit

AdminSpatialUnit(*, level: int, region_id_column_name: Union[str, NoneType] = None, mapping_table: Union[str, flowmachine.core.query.Query] = None) -> None
Source: flowmachine/core/spatial_unit.py

Subclass of PolygonSpatialUnit object that maps all cells (aka sites) to an admin region. This assumes that you have geography data in the standard location in FlowDB.

Attributes

Parameters

  • level: int

    Admin level (e.g. 1 for admin1, 2 for admin2, etc.)

  • region_id_column_name: typing.Union[str, NoneType], default None

    Pass a string of the column to use as the identifier of the admin region. By default this will be admin*pcod. But you may wish to use something else, such as admin3name.

  • mapping_table: typing.Union[str, flowmachine.core.query.Query], default None

    Name of a bridge table to geography information. Can be either the name of a table, with the schema, or a flowmachine.Query object.

Methods

get_geom_query

get_geom_query(self) -> str
Source: flowmachine/core/spatial_unit.py

Returns a SQL query which can be used to map locations (identified by the values in self.location_id_columns) to their geometries (in a column named "geom").

Returns
  • str

location_subset_clause

location_subset_clause(self, locations, check_column_names: bool = True) -> str
Source: flowmachine/core/spatial_unit.py

Return a SQL "WHERE" clause to subset a query (joined to this spatial unit) to a location or set of locations.

Parameters

  • locations: or list/tuple thereof, dict, str

    Location or list of locations to subset to. This should have one of the following formats: str, or list/tuple of str Values correspond to the first column in self.location_id_columns. dict, or list/tuple of dict Dict keys correspond to the column names in self.location_id_columns, and values correspond to the values in those columns.

  • check_column_names: bool, default True

    If True, check that all dict keys can be found in self.location_id_columns.

Returns

  • str

    SQL where clause.

verify_criterion

verify_criterion(self, criterion, negate=False) -> None
Source: flowmachine/core/spatial_unit.py

Check whether this spatial unit meets a criterion, and raise an InvalidSpatialUnitError if not.

Parameters

  • criterion: str

    One of: 'has_geography' 'has_lon_lat_columns' 'is_network_object' 'is_polygon'

  • negate: bool, default False

    If True, negate the criterion check (i.e. raise an error if criterion is met).

cache

cache
Source: flowmachine/core/query.py

Returns

  • bool

    True is caching is switched on.

canonical_name

canonical_name
Source: flowmachine/core/spatial_unit.py

Get the canonical name for this type of spatial unit, to allow checking access rights in FlowAPI.

Returns

  • str

    The name of this type of spatial unit, suitable for comparison with flowapi's geography permissions.

column_names

column_names
Source: flowmachine/core/spatial_unit.py

Returns the column names.

Returns

  • typing.List[str]

    List of the column names of this query.

column_names_as_string_list

column_names_as_string_list
Source: flowmachine/core/query.py

Get the column names as a comma separated list

Returns

  • str

    Comma separated list of column names

dependencies

dependencies
Source: flowmachine/core/query.py

Returns

  • set

    The set of queries which this one is directly dependent on.

fully_qualified_table_name

fully_qualified_table_name
Source: flowmachine/core/query.py

Returns a unique fully qualified name for the query to be stored as under the cache schema, based on a hash of the parameters, class, and subqueries.

Returns

  • str

    String form of the table's fqn

has_geography

has_geography
Source: flowmachine/core/spatial_unit.py

True if spatial unit has geography information.

Returns
  • bool

has_lon_lat_columns

has_lon_lat_columns
Source: flowmachine/core/spatial_unit.py

True if spatial unit has lon/lat columns.

Returns
  • bool

index_cols

index_cols
Source: flowmachine/core/query.py

A list of columns to use as indexes when storing this query.

Returns

  • ixen: list

    By default, returns the location columns if they are present and self.spatial_unit is defined, and the subscriber column.

Examples
daily_location("2016-01-01").index_cols
[['name'], '"subscriber"']

is_network_object

is_network_object
Source: flowmachine/core/spatial_unit.py

True if spatial unit is a network object (cell or site).

Returns
  • bool

is_polygon

is_polygon
Source: flowmachine/core/spatial_unit.py

True if spatial unit's geographies are polygons.

Returns
  • bool

is_stored

is_stored
Source: flowmachine/core/query.py

Returns

  • bool

    True if the table is stored, and False otherwise.

location_id_columns

location_id_columns
Source: flowmachine/core/spatial_unit.py

Names of the columns that identify a location.

Returns
  • typing.List[str]

query_id

query_id
Source: flowmachine/core/query.py

Generate a uniquely identifying hash of this query, based on the parameters of it and the subqueries it is composed of.

Returns

  • str

    query_id hash string

query_state

query_state
Source: flowmachine/core/query.py

Return the current query state.

Returns

  • QueryState

    The current query state

query_state_str

query_state_str
Source: flowmachine/core/query.py

Return the current query state as a string

Returns

  • str

    The current query state. The possible values are the ones defined in flowmachine.core.query_state.QueryState.

table_name

table_name
Source: flowmachine/core/query.py

Returns a uniquename for the query to be stored as, based on a hash of the parameters, class, and subqueries.

Returns

  • str

    String form of the table's fqn

Class CellSpatialUnit

CellSpatialUnit()
Source: flowmachine/core/spatial_unit.py

This class represents the case where no join of cell ID to other data is required. As such, this class does not inherit from Query, is not a valid parameter to JoinToLocation, and only exists to provide the location_id_columns property and for consistency with the other spatial units.

Attributes

Methods

location_subset_clause

location_subset_clause(self, locations, check_column_names: bool = True) -> str
Source: flowmachine/core/spatial_unit.py

Return a SQL "WHERE" clause to subset a query (joined to this spatial unit) to a location or set of locations.

Parameters

  • locations: or list/tuple thereof, dict, str

    Location or list of locations to subset to. This should have one of the following formats: str, or list/tuple of str Values correspond to the first column in self.location_id_columns. dict, or list/tuple of dict Dict keys correspond to the column names in self.location_id_columns, and values correspond to the values in those columns.

  • check_column_names: bool, default True

    If True, check that all dict keys can be found in self.location_id_columns.

Returns

  • str

    SQL where clause.

verify_criterion

verify_criterion(self, criterion, negate=False) -> None
Source: flowmachine/core/spatial_unit.py

Check whether this spatial unit meets a criterion, and raise an InvalidSpatialUnitError if not.

Parameters

  • criterion: str

    One of: 'has_geography' 'has_lon_lat_columns' 'is_network_object' 'is_polygon'

  • negate: bool, default False

    If True, negate the criterion check (i.e. raise an error if criterion is met).

canonical_name

canonical_name
Source: flowmachine/core/spatial_unit.py

Get the canonical name for this type of spatial unit, to allow checking access rights in FlowAPI.

Returns

  • str

    The name of this type of spatial unit, suitable for comparison with flowapi's geography permissions.

has_geography

has_geography
Source: flowmachine/core/spatial_unit.py

True if spatial unit has geography information.

Returns
  • bool

has_lon_lat_columns

has_lon_lat_columns
Source: flowmachine/core/spatial_unit.py

True if spatial unit has lon/lat columns.

Returns
  • bool

is_network_object

is_network_object
Source: flowmachine/core/spatial_unit.py

True if spatial unit is a network object (cell or site).

Returns
  • bool

is_polygon

is_polygon
Source: flowmachine/core/spatial_unit.py

True if spatial unit's geographies are polygons.

Returns
  • bool

location_id_columns

location_id_columns
Source: flowmachine/core/spatial_unit.py

Names of the columns that identify a location.

Returns
  • typing.List[str]

Class GeomSpatialUnit

GeomSpatialUnit(*, geom_table_column_names: Union[str, Iterable[str]], location_id_column_names: Union[str, Iterable[str]], geom_table: Union[flowmachine.core.query.Query, str, NoneType] = None, mapping_table: Union[flowmachine.core.query.Query, str, NoneType] = None, geom_column: str = 'geom', geom_table_join_on: Union[str, NoneType] = None, location_table_join_on: Union[str, NoneType] = None)
Source: flowmachine/core/spatial_unit.py

Base class for spatial units that map location IDs in connection.location_table to geographic locations.

Attributes

Parameters

  • geom_table_column_names: typing.Union[str, typing.Iterable[str]]

    Name(s) of the column(s) to fetch from geom_table.

  • location_id_column_names: typing.Union[str, typing.Iterable[str]]

    Name(s) of the column(s) which identify the locations. Must be a subset of the column_names for this query.

  • geom_table: typing.Union[flowmachine.core.query.Query, str, NoneType], default None

    Name of the table containing the geography information. Can be either the name of a table, with the schema, or a flowmachine.Query object. Defaults to connection.location_table

  • mapping_table: typing.Union[flowmachine.core.query.Query, str, NoneType], default None

    Name of a bridge table to geography information. Can be either the name of a table, with the schema, or a flowmachine.Query object.

  • geom_column: str, default geom

    Name of the column in geom_table that defines the geometry.

  • geom_table_join_on: typing.Union[str, NoneType], default None

    Name of the column from geom_table to join on. Required if geom_table != connection.location_table.

  • location_table_join_on: typing.Union[str, NoneType], default None

    Name of the column from connection.location_table to join on. Required if geom_table != connection.location_table.

Methods

get_geom_query

get_geom_query(self) -> str
Source: flowmachine/core/spatial_unit.py

Returns a SQL query which can be used to map locations (identified by the values in self.location_id_columns) to their geometries (in a column named "geom").

Returns
  • str

location_subset_clause

location_subset_clause(self, locations, check_column_names: bool = True) -> str
Source: flowmachine/core/spatial_unit.py

Return a SQL "WHERE" clause to subset a query (joined to this spatial unit) to a location or set of locations.

Parameters

  • locations: or list/tuple thereof, dict, str

    Location or list of locations to subset to. This should have one of the following formats: str, or list/tuple of str Values correspond to the first column in self.location_id_columns. dict, or list/tuple of dict Dict keys correspond to the column names in self.location_id_columns, and values correspond to the values in those columns.

  • check_column_names: bool, default True

    If True, check that all dict keys can be found in self.location_id_columns.

Returns

  • str

    SQL where clause.

verify_criterion

verify_criterion(self, criterion, negate=False) -> None
Source: flowmachine/core/spatial_unit.py

Check whether this spatial unit meets a criterion, and raise an InvalidSpatialUnitError if not.

Parameters

  • criterion: str

    One of: 'has_geography' 'has_lon_lat_columns' 'is_network_object' 'is_polygon'

  • negate: bool, default False

    If True, negate the criterion check (i.e. raise an error if criterion is met).

cache

cache
Source: flowmachine/core/query.py

Returns

  • bool

    True is caching is switched on.

canonical_name

canonical_name
Source: flowmachine/core/spatial_unit.py

Get the canonical name for this type of spatial unit, to allow checking access rights in FlowAPI.

Returns

  • str

    The name of this type of spatial unit, suitable for comparison with flowapi's geography permissions.

column_names

column_names
Source: flowmachine/core/spatial_unit.py

Returns the column names.

Returns

  • typing.List[str]

    List of the column names of this query.

column_names_as_string_list

column_names_as_string_list
Source: flowmachine/core/query.py

Get the column names as a comma separated list

Returns

  • str

    Comma separated list of column names

dependencies

dependencies
Source: flowmachine/core/query.py

Returns

  • set

    The set of queries which this one is directly dependent on.

fully_qualified_table_name

fully_qualified_table_name
Source: flowmachine/core/query.py

Returns a unique fully qualified name for the query to be stored as under the cache schema, based on a hash of the parameters, class, and subqueries.

Returns

  • str

    String form of the table's fqn

has_geography

has_geography
Source: flowmachine/core/spatial_unit.py

True if spatial unit has geography information.

Returns
  • bool

has_lon_lat_columns

has_lon_lat_columns
Source: flowmachine/core/spatial_unit.py

True if spatial unit has lon/lat columns.

Returns
  • bool

index_cols

index_cols
Source: flowmachine/core/query.py

A list of columns to use as indexes when storing this query.

Returns

  • ixen: list

    By default, returns the location columns if they are present and self.spatial_unit is defined, and the subscriber column.

Examples
daily_location("2016-01-01").index_cols
[['name'], '"subscriber"']

is_network_object

is_network_object
Source: flowmachine/core/spatial_unit.py

True if spatial unit is a network object (cell or site).

Returns
  • bool

is_polygon

is_polygon
Source: flowmachine/core/spatial_unit.py

True if spatial unit's geographies are polygons.

Returns
  • bool

is_stored

is_stored
Source: flowmachine/core/query.py

Returns

  • bool

    True if the table is stored, and False otherwise.

location_id_columns

location_id_columns
Source: flowmachine/core/spatial_unit.py

Names of the columns that identify a location.

Returns
  • typing.List[str]

query_id

query_id
Source: flowmachine/core/query.py

Generate a uniquely identifying hash of this query, based on the parameters of it and the subqueries it is composed of.

Returns

  • str

    query_id hash string

query_state

query_state
Source: flowmachine/core/query.py

Return the current query state.

Returns

  • QueryState

    The current query state

query_state_str

query_state_str
Source: flowmachine/core/query.py

Return the current query state as a string

Returns

  • str

    The current query state. The possible values are the ones defined in flowmachine.core.query_state.QueryState.

table_name

table_name
Source: flowmachine/core/query.py

Returns a uniquename for the query to be stored as, based on a hash of the parameters, class, and subqueries.

Returns

  • str

    String form of the table's fqn

Class GridSpatialUnit

GridSpatialUnit(*, size: Union[float, int], mapping_table: Union[str, flowmachine.core.query.Query] = None, location_table_join_on: Union[str, NoneType] = None) -> None
Source: flowmachine/core/spatial_unit.py

Subclass of PolygonSpatialUnit that maps all the sites in the database to a grid of arbitrary size.

Attributes

Parameters

  • size: typing.Union[float, int]

    Size of the grid in kilometres

Methods

get_geom_query

get_geom_query(self) -> str
Source: flowmachine/core/spatial_unit.py

Returns a SQL query which can be used to map locations (identified by the values in self.location_id_columns) to their geometries (in a column named "geom").

Returns
  • str

location_subset_clause

location_subset_clause(self, locations, check_column_names: bool = True) -> str
Source: flowmachine/core/spatial_unit.py

Return a SQL "WHERE" clause to subset a query (joined to this spatial unit) to a location or set of locations.

Parameters

  • locations: or list/tuple thereof, dict, str

    Location or list of locations to subset to. This should have one of the following formats: str, or list/tuple of str Values correspond to the first column in self.location_id_columns. dict, or list/tuple of dict Dict keys correspond to the column names in self.location_id_columns, and values correspond to the values in those columns.

  • check_column_names: bool, default True

    If True, check that all dict keys can be found in self.location_id_columns.

Returns

  • str

    SQL where clause.

verify_criterion

verify_criterion(self, criterion, negate=False) -> None
Source: flowmachine/core/spatial_unit.py

Check whether this spatial unit meets a criterion, and raise an InvalidSpatialUnitError if not.

Parameters

  • criterion: str

    One of: 'has_geography' 'has_lon_lat_columns' 'is_network_object' 'is_polygon'

  • negate: bool, default False

    If True, negate the criterion check (i.e. raise an error if criterion is met).

cache

cache
Source: flowmachine/core/query.py

Returns

  • bool

    True is caching is switched on.

canonical_name

canonical_name
Source: flowmachine/core/spatial_unit.py

Get the canonical name for this type of spatial unit, to allow checking access rights in FlowAPI.

Returns

  • str

    The name of this type of spatial unit, suitable for comparison with flowapi's geography permissions.

column_names

column_names
Source: flowmachine/core/spatial_unit.py

Returns the column names.

Returns

  • typing.List[str]

    List of the column names of this query.

column_names_as_string_list

column_names_as_string_list
Source: flowmachine/core/query.py

Get the column names as a comma separated list

Returns

  • str

    Comma separated list of column names

dependencies

dependencies
Source: flowmachine/core/query.py

Returns

  • set

    The set of queries which this one is directly dependent on.

fully_qualified_table_name

fully_qualified_table_name
Source: flowmachine/core/query.py

Returns a unique fully qualified name for the query to be stored as under the cache schema, based on a hash of the parameters, class, and subqueries.

Returns

  • str

    String form of the table's fqn

has_geography

has_geography
Source: flowmachine/core/spatial_unit.py

True if spatial unit has geography information.

Returns
  • bool

has_lon_lat_columns

has_lon_lat_columns
Source: flowmachine/core/spatial_unit.py

True if spatial unit has lon/lat columns.

Returns
  • bool

index_cols

index_cols
Source: flowmachine/core/query.py

A list of columns to use as indexes when storing this query.

Returns

  • ixen: list

    By default, returns the location columns if they are present and self.spatial_unit is defined, and the subscriber column.

Examples
daily_location("2016-01-01").index_cols
[['name'], '"subscriber"']

is_network_object

is_network_object
Source: flowmachine/core/spatial_unit.py

True if spatial unit is a network object (cell or site).

Returns
  • bool

is_polygon

is_polygon
Source: flowmachine/core/spatial_unit.py

True if spatial unit's geographies are polygons.

Returns
  • bool

is_stored

is_stored
Source: flowmachine/core/query.py

Returns

  • bool

    True if the table is stored, and False otherwise.

location_id_columns

location_id_columns
Source: flowmachine/core/spatial_unit.py

Names of the columns that identify a location.

Returns
  • typing.List[str]

query_id

query_id
Source: flowmachine/core/query.py

Generate a uniquely identifying hash of this query, based on the parameters of it and the subqueries it is composed of.

Returns

  • str

    query_id hash string

query_state

query_state
Source: flowmachine/core/query.py

Return the current query state.

Returns

  • QueryState

    The current query state

query_state_str

query_state_str
Source: flowmachine/core/query.py

Return the current query state as a string

Returns

  • str

    The current query state. The possible values are the ones defined in flowmachine.core.query_state.QueryState.

table_name

table_name
Source: flowmachine/core/query.py

Returns a uniquename for the query to be stored as, based on a hash of the parameters, class, and subqueries.

Returns

  • str

    String form of the table's fqn

Class LonLatSpatialUnit

LonLatSpatialUnit(*, geom_table_column_names: Union[str, Iterable[str]] = (), location_id_column_names: Union[str, Iterable[str]] = (), geom_table: Union[flowmachine.core.query.Query, str, NoneType] = None, mapping_table: Union[flowmachine.core.query.Query, str, NoneType] = None, geom_column: str = 'geom_point', geom_table_join_on: Union[str, NoneType] = None, location_table_join_on: Union[str, NoneType] = None)
Source: flowmachine/core/spatial_unit.py

Class that provides a mapping from cell/site IDs in the location table to longitude and latitude. In addition to the requested geom_table_column_names, this query returns longitude and latitude values in columns "lon" and "lat".

Attributes

Parameters

  • geom_table_column_names: typing.Union[str, typing.Iterable[str]], default ()

    Name(s) of the column(s) to fetch from geom_table.

  • location_id_column_names: typing.Union[str, typing.Iterable[str]], default ()

    Name(s) of the column(s) which identify the locations. Must be a subset of the column_names for this query. "lon" and "lat" will be appended to this list of names.

  • geom_table: typing.Union[flowmachine.core.query.Query, str, NoneType], default None

    Name of the table containing the geography information. Can be either the name of a table, with the schema, or a flowmachine.Query object. Defaults to connection.location_table

  • mapping_table: typing.Union[flowmachine.core.query.Query, str, NoneType], default None

    Name of a bridge table to geography information. Can be either the name of a table, with the schema, or a flowmachine.Query object.

  • geom_column: str, default geom_point

    Name of the column in geom_table that defines the point geometry from which longitude and latitude will be extracted.

Methods

get_geom_query

get_geom_query(self) -> str
Source: flowmachine/core/spatial_unit.py

Returns a SQL query which can be used to map locations (identified by the values in self.location_id_columns) to their geometries (in a column named "geom").

Returns
  • str

location_subset_clause

location_subset_clause(self, locations, check_column_names: bool = True) -> str
Source: flowmachine/core/spatial_unit.py

Return a SQL "WHERE" clause to subset a query (joined to this spatial unit) to a location or set of locations. This method differs from the default implementation in its handling of lon-lat values, i.e. it returns WHERE ST_SetSRID(ST_Point(lon, lat), 4326) = 'ST_SetSRID(ST_Point(, ), 4326)' instead of WHERE lon = '' AND lat = ''

Parameters

  • locations: or list/tuple thereof, dict, str, tuple

    Location or list of locations to subset to. This should have one of the following formats: list/tuple of tuple Values are (longitude, latitude) pairs, corresponding to the 'lon' and 'lat' columns. Note: cannot pass a single (lon, lat) tuple, as this would be ambiguous (could be a tuple of str, see below). For a single location, either pass a length-1 list [(lon, lat)] or a dict {"lon": lon, "lat": lat}. str, or list/tuple of str Values correspond to the first column in self.location_id_columns. dict, or list/tuple of dict Dict keys correspond to the column names in self.location_id_columns, and values correspond to the values in those columns.

  • check_column_names: bool, default True

    If True, check that all dict keys can be found in self.location_id_columns.

Returns

  • str

    SQL where clause.

verify_criterion

verify_criterion(self, criterion, negate=False) -> None
Source: flowmachine/core/spatial_unit.py

Check whether this spatial unit meets a criterion, and raise an InvalidSpatialUnitError if not.

Parameters

  • criterion: str

    One of: 'has_geography' 'has_lon_lat_columns' 'is_network_object' 'is_polygon'

  • negate: bool, default False

    If True, negate the criterion check (i.e. raise an error if criterion is met).

cache

cache
Source: flowmachine/core/query.py

Returns

  • bool

    True is caching is switched on.

canonical_name

canonical_name
Source: flowmachine/core/spatial_unit.py

Get the canonical name for this type of spatial unit, to allow checking access rights in FlowAPI.

Returns

  • str

    The name of this type of spatial unit, suitable for comparison with flowapi's geography permissions.

column_names

column_names
Source: flowmachine/core/spatial_unit.py

Returns the column names.

Returns

  • typing.List[str]

    List of the column names of this query.

column_names_as_string_list

column_names_as_string_list
Source: flowmachine/core/query.py

Get the column names as a comma separated list

Returns

  • str

    Comma separated list of column names

dependencies

dependencies
Source: flowmachine/core/query.py

Returns

  • set

    The set of queries which this one is directly dependent on.

fully_qualified_table_name

fully_qualified_table_name
Source: flowmachine/core/query.py

Returns a unique fully qualified name for the query to be stored as under the cache schema, based on a hash of the parameters, class, and subqueries.

Returns

  • str

    String form of the table's fqn

has_geography

has_geography
Source: flowmachine/core/spatial_unit.py

True if spatial unit has geography information.

Returns
  • bool

has_lon_lat_columns

has_lon_lat_columns
Source: flowmachine/core/spatial_unit.py

True if spatial unit has lon/lat columns.

Returns
  • bool

index_cols

index_cols
Source: flowmachine/core/query.py

A list of columns to use as indexes when storing this query.

Returns

  • ixen: list

    By default, returns the location columns if they are present and self.spatial_unit is defined, and the subscriber column.

Examples
daily_location("2016-01-01").index_cols
[['name'], '"subscriber"']

is_network_object

is_network_object
Source: flowmachine/core/spatial_unit.py

True if spatial unit is a network object (cell or site).

Returns
  • bool

is_polygon

is_polygon
Source: flowmachine/core/spatial_unit.py

True if spatial unit's geographies are polygons.

Returns
  • bool

is_stored

is_stored
Source: flowmachine/core/query.py

Returns

  • bool

    True if the table is stored, and False otherwise.

location_id_columns

location_id_columns
Source: flowmachine/core/spatial_unit.py

Names of the columns that identify a location.

Returns
  • typing.List[str]

query_id

query_id
Source: flowmachine/core/query.py

Generate a uniquely identifying hash of this query, based on the parameters of it and the subqueries it is composed of.

Returns

  • str

    query_id hash string

query_state

query_state
Source: flowmachine/core/query.py

Return the current query state.

Returns

  • QueryState

    The current query state

query_state_str

query_state_str
Source: flowmachine/core/query.py

Return the current query state as a string

Returns

  • str

    The current query state. The possible values are the ones defined in flowmachine.core.query_state.QueryState.

table_name

table_name
Source: flowmachine/core/query.py

Returns a uniquename for the query to be stored as, based on a hash of the parameters, class, and subqueries.

Returns

  • str

    String form of the table's fqn

Class PolygonSpatialUnit

PolygonSpatialUnit(*, geom_table_column_names: Union[str, Iterable[str]], geom_table: Union[flowmachine.core.query.Query, str], mapping_table: Union[flowmachine.core.query.Query, str, NoneType] = None, geom_column: str = 'geom', geom_table_join_on: Union[str, NoneType] = None)
Source: flowmachine/core/spatial_unit.py

Class that provides a mapping from cell/site data in the location table to spatial regions defined by geography information in a table.

Attributes

Parameters

  • geom_table_column_names: typing.Union[str, typing.Iterable[str]]

    Name(s) of the column(s) to fetch from geom_table. This column or columns will be used to identify the polygons.

  • geom_table: typing.Union[flowmachine.core.query.Query, str]

    Name of the table containing the geography information. Can be either the name of a table, with the schema, or a flowmachine.Query object.

  • mapping_table: typing.Union[flowmachine.core.query.Query, str, NoneType], default None

    Name of a bridge table to geography information. Can be either the name of a table, with the schema, or a flowmachine.Query object.

  • geom_column: str, default geom

    Name of the column in geom_table that defines the geography.

Methods

get_geom_query

get_geom_query(self) -> str
Source: flowmachine/core/spatial_unit.py

Returns a SQL query which can be used to map locations (identified by the values in self.location_id_columns) to their geometries (in a column named "geom").

Returns
  • str

location_subset_clause

location_subset_clause(self, locations, check_column_names: bool = True) -> str
Source: flowmachine/core/spatial_unit.py

Return a SQL "WHERE" clause to subset a query (joined to this spatial unit) to a location or set of locations.

Parameters

  • locations: or list/tuple thereof, dict, str

    Location or list of locations to subset to. This should have one of the following formats: str, or list/tuple of str Values correspond to the first column in self.location_id_columns. dict, or list/tuple of dict Dict keys correspond to the column names in self.location_id_columns, and values correspond to the values in those columns.

  • check_column_names: bool, default True

    If True, check that all dict keys can be found in self.location_id_columns.

Returns

  • str

    SQL where clause.

verify_criterion

verify_criterion(self, criterion, negate=False) -> None
Source: flowmachine/core/spatial_unit.py

Check whether this spatial unit meets a criterion, and raise an InvalidSpatialUnitError if not.

Parameters

  • criterion: str

    One of: 'has_geography' 'has_lon_lat_columns' 'is_network_object' 'is_polygon'

  • negate: bool, default False

    If True, negate the criterion check (i.e. raise an error if criterion is met).

cache

cache
Source: flowmachine/core/query.py

Returns

  • bool

    True is caching is switched on.

canonical_name

canonical_name
Source: flowmachine/core/spatial_unit.py

Get the canonical name for this type of spatial unit, to allow checking access rights in FlowAPI.

Returns

  • str

    The name of this type of spatial unit, suitable for comparison with flowapi's geography permissions.

column_names

column_names
Source: flowmachine/core/spatial_unit.py

Returns the column names.

Returns

  • typing.List[str]

    List of the column names of this query.

column_names_as_string_list

column_names_as_string_list
Source: flowmachine/core/query.py

Get the column names as a comma separated list

Returns

  • str

    Comma separated list of column names

dependencies

dependencies
Source: flowmachine/core/query.py

Returns

  • set

    The set of queries which this one is directly dependent on.

fully_qualified_table_name

fully_qualified_table_name
Source: flowmachine/core/query.py

Returns a unique fully qualified name for the query to be stored as under the cache schema, based on a hash of the parameters, class, and subqueries.

Returns

  • str

    String form of the table's fqn

has_geography

has_geography
Source: flowmachine/core/spatial_unit.py

True if spatial unit has geography information.

Returns
  • bool

has_lon_lat_columns

has_lon_lat_columns
Source: flowmachine/core/spatial_unit.py

True if spatial unit has lon/lat columns.

Returns
  • bool

index_cols

index_cols
Source: flowmachine/core/query.py

A list of columns to use as indexes when storing this query.

Returns

  • ixen: list

    By default, returns the location columns if they are present and self.spatial_unit is defined, and the subscriber column.

Examples
daily_location("2016-01-01").index_cols
[['name'], '"subscriber"']

is_network_object

is_network_object
Source: flowmachine/core/spatial_unit.py

True if spatial unit is a network object (cell or site).

Returns
  • bool

is_polygon

is_polygon
Source: flowmachine/core/spatial_unit.py

True if spatial unit's geographies are polygons.

Returns
  • bool

is_stored

is_stored
Source: flowmachine/core/query.py

Returns

  • bool

    True if the table is stored, and False otherwise.

location_id_columns

location_id_columns
Source: flowmachine/core/spatial_unit.py

Names of the columns that identify a location.

Returns
  • typing.List[str]

query_id

query_id
Source: flowmachine/core/query.py

Generate a uniquely identifying hash of this query, based on the parameters of it and the subqueries it is composed of.

Returns

  • str

    query_id hash string

query_state

query_state
Source: flowmachine/core/query.py

Return the current query state.

Returns

  • QueryState

    The current query state

query_state_str

query_state_str
Source: flowmachine/core/query.py

Return the current query state as a string

Returns

  • str

    The current query state. The possible values are the ones defined in flowmachine.core.query_state.QueryState.

table_name

table_name
Source: flowmachine/core/query.py

Returns a uniquename for the query to be stored as, based on a hash of the parameters, class, and subqueries.

Returns

  • str

    String form of the table's fqn

Class SpatialUnitMixin

SpatialUnitMixin()
Source: flowmachine/core/spatial_unit.py

Mixin for spatial unit classes, which provides a 'location_id_columns' property and methods for verifying whether a spatial unit meets different criteria (useful for checking whether a spatial unit is valid in a given query).

Attributes

Methods

location_subset_clause

location_subset_clause(self, locations, check_column_names: bool = True) -> str
Source: flowmachine/core/spatial_unit.py

Return a SQL "WHERE" clause to subset a query (joined to this spatial unit) to a location or set of locations.

Parameters

  • locations: or list/tuple thereof, dict, str

    Location or list of locations to subset to. This should have one of the following formats: str, or list/tuple of str Values correspond to the first column in self.location_id_columns. dict, or list/tuple of dict Dict keys correspond to the column names in self.location_id_columns, and values correspond to the values in those columns.

  • check_column_names: bool, default True

    If True, check that all dict keys can be found in self.location_id_columns.

Returns

  • str

    SQL where clause.

verify_criterion

verify_criterion(self, criterion, negate=False) -> None
Source: flowmachine/core/spatial_unit.py

Check whether this spatial unit meets a criterion, and raise an InvalidSpatialUnitError if not.

Parameters

  • criterion: str

    One of: 'has_geography' 'has_lon_lat_columns' 'is_network_object' 'is_polygon'

  • negate: bool, default False

    If True, negate the criterion check (i.e. raise an error if criterion is met).

canonical_name

canonical_name
Source: flowmachine/core/spatial_unit.py

Get the canonical name for this type of spatial unit, to allow checking access rights in FlowAPI.

Returns

  • str

    The name of this type of spatial unit, suitable for comparison with flowapi's geography permissions.

has_geography

has_geography
Source: flowmachine/core/spatial_unit.py

True if spatial unit has geography information.

Returns
  • bool

has_lon_lat_columns

has_lon_lat_columns
Source: flowmachine/core/spatial_unit.py

True if spatial unit has lon/lat columns.

Returns
  • bool

is_network_object

is_network_object
Source: flowmachine/core/spatial_unit.py

True if spatial unit is a network object (cell or site).

Returns
  • bool

is_polygon

is_polygon
Source: flowmachine/core/spatial_unit.py

True if spatial unit's geographies are polygons.

Returns
  • bool

location_id_columns

location_id_columns
Source: flowmachine/core/spatial_unit.py

Names of the columns that identify a location.

Returns
  • typing.List[str]

Class VersionedCellSpatialUnit

VersionedCellSpatialUnit() -> None
Source: flowmachine/core/spatial_unit.py

Subclass of LonLatSpatialUnit that maps cell location_id to a cell version and lon-lat coordinates.

Attributes

Methods

get_geom_query

get_geom_query(self) -> str
Source: flowmachine/core/spatial_unit.py

Returns a SQL query which can be used to map locations (identified by the values in self.location_id_columns) to their geometries (in a column named "geom").

Returns
  • str

location_subset_clause

location_subset_clause(self, locations, check_column_names: bool = True) -> str
Source: flowmachine/core/spatial_unit.py

Return a SQL "WHERE" clause to subset a query (joined to this spatial unit) to a location or set of locations. This method differs from the default implementation in its handling of lon-lat values, i.e. it returns WHERE ST_SetSRID(ST_Point(lon, lat), 4326) = 'ST_SetSRID(ST_Point(, ), 4326)' instead of WHERE lon = '' AND lat = ''

Parameters

  • locations: or list/tuple thereof, dict, str, tuple

    Location or list of locations to subset to. This should have one of the following formats: list/tuple of tuple Values are (longitude, latitude) pairs, corresponding to the 'lon' and 'lat' columns. Note: cannot pass a single (lon, lat) tuple, as this would be ambiguous (could be a tuple of str, see below). For a single location, either pass a length-1 list [(lon, lat)] or a dict {"lon": lon, "lat": lat}. str, or list/tuple of str Values correspond to the first column in self.location_id_columns. dict, or list/tuple of dict Dict keys correspond to the column names in self.location_id_columns, and values correspond to the values in those columns.

  • check_column_names: bool, default True

    If True, check that all dict keys can be found in self.location_id_columns.

Returns

  • str

    SQL where clause.

verify_criterion

verify_criterion(self, criterion, negate=False) -> None
Source: flowmachine/core/spatial_unit.py

Check whether this spatial unit meets a criterion, and raise an InvalidSpatialUnitError if not.

Parameters

  • criterion: str

    One of: 'has_geography' 'has_lon_lat_columns' 'is_network_object' 'is_polygon'

  • negate: bool, default False

    If True, negate the criterion check (i.e. raise an error if criterion is met).

cache

cache
Source: flowmachine/core/query.py

Returns

  • bool

    True is caching is switched on.

canonical_name

canonical_name
Source: flowmachine/core/spatial_unit.py

Get the canonical name for this type of spatial unit, to allow checking access rights in FlowAPI.

Returns

  • str

    The name of this type of spatial unit, suitable for comparison with flowapi's geography permissions.

column_names

column_names
Source: flowmachine/core/spatial_unit.py

Returns the column names.

Returns

  • typing.List[str]

    List of the column names of this query.

column_names_as_string_list

column_names_as_string_list
Source: flowmachine/core/query.py

Get the column names as a comma separated list

Returns

  • str

    Comma separated list of column names

dependencies

dependencies
Source: flowmachine/core/query.py

Returns

  • set

    The set of queries which this one is directly dependent on.

fully_qualified_table_name

fully_qualified_table_name
Source: flowmachine/core/query.py

Returns a unique fully qualified name for the query to be stored as under the cache schema, based on a hash of the parameters, class, and subqueries.

Returns

  • str

    String form of the table's fqn

has_geography

has_geography
Source: flowmachine/core/spatial_unit.py

True if spatial unit has geography information.

Returns
  • bool

has_lon_lat_columns

has_lon_lat_columns
Source: flowmachine/core/spatial_unit.py

True if spatial unit has lon/lat columns.

Returns
  • bool

index_cols

index_cols
Source: flowmachine/core/query.py

A list of columns to use as indexes when storing this query.

Returns

  • ixen: list

    By default, returns the location columns if they are present and self.spatial_unit is defined, and the subscriber column.

Examples
daily_location("2016-01-01").index_cols
[['name'], '"subscriber"']

is_network_object

is_network_object
Source: flowmachine/core/spatial_unit.py

True if spatial unit is a network object (cell or site).

Returns
  • bool

is_polygon

is_polygon
Source: flowmachine/core/spatial_unit.py

True if spatial unit's geographies are polygons.

Returns
  • bool

is_stored

is_stored
Source: flowmachine/core/query.py

Returns

  • bool

    True if the table is stored, and False otherwise.

location_id_columns

location_id_columns
Source: flowmachine/core/spatial_unit.py

Names of the columns that identify a location.

Returns
  • typing.List[str]

query_id

query_id
Source: flowmachine/core/query.py

Generate a uniquely identifying hash of this query, based on the parameters of it and the subqueries it is composed of.

Returns

  • str

    query_id hash string

query_state

query_state
Source: flowmachine/core/query.py

Return the current query state.

Returns

  • QueryState

    The current query state

query_state_str

query_state_str
Source: flowmachine/core/query.py

Return the current query state as a string

Returns

  • str

    The current query state. The possible values are the ones defined in flowmachine.core.query_state.QueryState.

table_name

table_name
Source: flowmachine/core/query.py

Returns a uniquename for the query to be stored as, based on a hash of the parameters, class, and subqueries.

Returns

  • str

    String form of the table's fqn

Class VersionedSiteSpatialUnit

VersionedSiteSpatialUnit() -> None
Source: flowmachine/core/spatial_unit.py

Subclass of LonLatSpatialUnit that maps cell location_id to a site version and lon-lat coordinates.

Attributes

Methods

get_geom_query

get_geom_query(self) -> str
Source: flowmachine/core/spatial_unit.py

Returns a SQL query which can be used to map locations (identified by the values in self.location_id_columns) to their geometries (in a column named "geom").

Returns
  • str

location_subset_clause

location_subset_clause(self, locations, check_column_names: bool = True) -> str
Source: flowmachine/core/spatial_unit.py

Return a SQL "WHERE" clause to subset a query (joined to this spatial unit) to a location or set of locations. This method differs from the default implementation in its handling of lon-lat values, i.e. it returns WHERE ST_SetSRID(ST_Point(lon, lat), 4326) = 'ST_SetSRID(ST_Point(, ), 4326)' instead of WHERE lon = '' AND lat = ''

Parameters

  • locations: or list/tuple thereof, dict, str, tuple

    Location or list of locations to subset to. This should have one of the following formats: list/tuple of tuple Values are (longitude, latitude) pairs, corresponding to the 'lon' and 'lat' columns. Note: cannot pass a single (lon, lat) tuple, as this would be ambiguous (could be a tuple of str, see below). For a single location, either pass a length-1 list [(lon, lat)] or a dict {"lon": lon, "lat": lat}. str, or list/tuple of str Values correspond to the first column in self.location_id_columns. dict, or list/tuple of dict Dict keys correspond to the column names in self.location_id_columns, and values correspond to the values in those columns.

  • check_column_names: bool, default True

    If True, check that all dict keys can be found in self.location_id_columns.

Returns

  • str

    SQL where clause.

verify_criterion

verify_criterion(self, criterion, negate=False) -> None
Source: flowmachine/core/spatial_unit.py

Check whether this spatial unit meets a criterion, and raise an InvalidSpatialUnitError if not.

Parameters

  • criterion: str

    One of: 'has_geography' 'has_lon_lat_columns' 'is_network_object' 'is_polygon'

  • negate: bool, default False

    If True, negate the criterion check (i.e. raise an error if criterion is met).

cache

cache
Source: flowmachine/core/query.py

Returns

  • bool

    True is caching is switched on.

canonical_name

canonical_name
Source: flowmachine/core/spatial_unit.py

Get the canonical name for this type of spatial unit, to allow checking access rights in FlowAPI.

Returns

  • str

    The name of this type of spatial unit, suitable for comparison with flowapi's geography permissions.

column_names

column_names
Source: flowmachine/core/spatial_unit.py

Returns the column names.

Returns

  • typing.List[str]

    List of the column names of this query.

column_names_as_string_list

column_names_as_string_list
Source: flowmachine/core/query.py

Get the column names as a comma separated list

Returns

  • str

    Comma separated list of column names

dependencies

dependencies
Source: flowmachine/core/query.py

Returns

  • set

    The set of queries which this one is directly dependent on.

fully_qualified_table_name

fully_qualified_table_name
Source: flowmachine/core/query.py

Returns a unique fully qualified name for the query to be stored as under the cache schema, based on a hash of the parameters, class, and subqueries.

Returns

  • str

    String form of the table's fqn

has_geography

has_geography
Source: flowmachine/core/spatial_unit.py

True if spatial unit has geography information.

Returns
  • bool

has_lon_lat_columns

has_lon_lat_columns
Source: flowmachine/core/spatial_unit.py

True if spatial unit has lon/lat columns.

Returns
  • bool

index_cols

index_cols
Source: flowmachine/core/query.py

A list of columns to use as indexes when storing this query.

Returns

  • ixen: list

    By default, returns the location columns if they are present and self.spatial_unit is defined, and the subscriber column.

Examples
daily_location("2016-01-01").index_cols
[['name'], '"subscriber"']

is_network_object

is_network_object
Source: flowmachine/core/spatial_unit.py

True if spatial unit is a network object (cell or site).

Returns
  • bool

is_polygon

is_polygon
Source: flowmachine/core/spatial_unit.py

True if spatial unit's geographies are polygons.

Returns
  • bool

is_stored

is_stored
Source: flowmachine/core/query.py

Returns

  • bool

    True if the table is stored, and False otherwise.

location_id_columns

location_id_columns
Source: flowmachine/core/spatial_unit.py

Names of the columns that identify a location.

Returns
  • typing.List[str]

query_id

query_id
Source: flowmachine/core/query.py

Generate a uniquely identifying hash of this query, based on the parameters of it and the subqueries it is composed of.

Returns

  • str

    query_id hash string

query_state

query_state
Source: flowmachine/core/query.py

Return the current query state.

Returns

  • QueryState

    The current query state

query_state_str

query_state_str
Source: flowmachine/core/query.py

Return the current query state as a string

Returns

  • str

    The current query state. The possible values are the ones defined in flowmachine.core.query_state.QueryState.

table_name

table_name
Source: flowmachine/core/query.py

Returns a uniquename for the query to be stored as, based on a hash of the parameters, class, and subqueries.

Returns

  • str

    String form of the table's fqn

make_spatial_unit

make_spatial_unit(spatial_unit_type: str, *, level: Union[int, NoneType] = None, region_id_column_name: Union[str, Iterable[str], NoneType] = None, size: Union[float, int] = None, geom_table: Union[flowmachine.core.query.Query, str, NoneType] = None, geom_column: str = 'geom', mapping_table: Union[flowmachine.core.query.Query, str, NoneType] = None, geom_table_join_on: Union[str, NoneType] = None) -> Union[flowmachine.core.spatial_unit.CellSpatialUnit, flowmachine.core.spatial_unit.GeomSpatialUnit]
Source: flowmachine/core/spatial_unit.py

Helper function to create an object representing a spatial unit.

Parameters

  • spatial_unit_type: str

    Can be one of: 'cell' The identifier as found in the CDR. 'lon-lat' Longitude and latitude of cell/site locations. 'versioned-cell' The identifier as found in the CDR combined with the version from the cells table. 'versioned-site' The ID found in the sites table, coupled with the version number. 'polygon' A custom set of polygons that live in the database. In which case you can pass the parameters 'region_id_column_name', which is the column or columns you want to return after the join, and 'geom_table', the table where the polygons reside (with the schema), and additionally geom_column which is the column with the geometry information (will default to 'geom'). 'admin' An admin region of interest, such as admin3. Must live in the database in the standard location. In addition pass the 'level' parameter, e.g. level=3 for admin3. Optionally also pass the parameter 'column_name' to choose the column to use as the identifier of the admin region (default is 'admin*pcod') 'grid' A square in a regular grid, in addition pass the 'size' parameter to determine the size of the polygon.

  • level: typing.Union[int, NoneType], default None

    Admin level (e.g. 1 for admin1, 2 for admin2, etc.). Required when spatial_unit_type='admin'.

  • region_id_column_name: typing.Union[str, typing.Iterable[str], NoneType], default None

    Name(s) of column(s) which identifies the polygon regions. Required when spatial_unit_type='polygon', optional when spatial_unit_type='admin'.

  • size: typing.Union[float, int], default None

    Size of the grid in kilometres. Required when spatial_unit_type='grid'.

  • geom_table: typing.Union[flowmachine.core.query.Query, str, NoneType], default None

    Name of the table containing the geography information. Can be either the name of a table, with the schema, or a flowmachine.Query object. Required when spatial_unit_type='polygon'.

  • mapping_table: typing.Union[flowmachine.core.query.Query, str, NoneType], default None

    Name of a bridge table to geography information. Can be either the name of a table, with the schema, or a flowmachine.Query object.

  • geom_column: str, default geom

    Name of the column in geom_table that defines the geography. Required when spatial_unit_type='polygon'.

Returns

  • typing.Union[flowmachine.core.spatial_unit.CellSpatialUnit, flowmachine.core.spatial_unit.GeomSpatialUnit]

    An object representing a mapping from location identifiers to a spatial unit.