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: Optional[str] = None, mapping_table: Union[str, flowmachine.core.query.Query] = None) -> None
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.Optional
, defaultNone
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
, defaultNone
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
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
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
, defaultTrue
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
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
, defaultFalse
If True, negate the criterion check (i.e. raise an error if criterion is met).
cache¶
cache
Returns¶
-
bool
True is caching is switched on.
canonical_name¶
canonical_name
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
Returns the column names.
Returns¶
-
typing.List
List of the column names of this query.
column_names_as_string_list¶
column_names_as_string_list
Get the column names as a comma separated list
Returns¶
-
str
Comma separated list of column names
dependencies¶
dependencies
Returns¶
-
set
The set of queries which this one is directly dependent on.
fully_qualified_table_name¶
fully_qualified_table_name
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
True if spatial unit has geography information.
Returns¶
bool
has_lon_lat_columns¶
has_lon_lat_columns
True if spatial unit has lon/lat columns.
Returns¶
bool
index_cols¶
index_cols
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
True if spatial unit is a network object (cell or site).
Returns¶
bool
is_polygon¶
is_polygon
True if spatial unit's geographies are polygons.
Returns¶
bool
is_stored¶
is_stored
Returns¶
-
bool
True if the table is stored, and False otherwise.
location_id_columns¶
location_id_columns
Names of the columns that identify a location.
Returns¶
typing.List
query_id¶
query_id
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
Return the current query state.
Returns¶
-
QueryState
The current query state
query_state_str¶
query_state_str
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
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()
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
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
, defaultTrue
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
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
, defaultFalse
If True, negate the criterion check (i.e. raise an error if criterion is met).
canonical_name¶
canonical_name
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
True if spatial unit has geography information.
Returns¶
bool
has_lon_lat_columns¶
has_lon_lat_columns
True if spatial unit has lon/lat columns.
Returns¶
bool
is_network_object¶
is_network_object
True if spatial unit is a network object (cell or site).
Returns¶
bool
is_polygon¶
is_polygon
True if spatial unit's geographies are polygons.
Returns¶
bool
location_id_columns¶
location_id_columns
Names of the columns that identify a location.
Returns¶
typing.List
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: Optional[str] = None, location_table_join_on: Optional[str] = None)
Base class for spatial units that map location IDs in connection.location_table to geographic locations.
Attributes¶
Parameters¶
-
geom_table_column_names
:typing.Union
Name(s) of the column(s) to fetch from geom_table.
-
location_id_column_names
:typing.Union
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
, defaultNone
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
, defaultNone
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
, defaultgeom
Name of the column in geom_table that defines the geometry.
-
geom_table_join_on
:typing.Optional
, defaultNone
Name of the column from geom_table to join on. Required if geom_table != connection.location_table.
-
location_table_join_on
:typing.Optional
, defaultNone
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
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
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
, defaultTrue
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
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
, defaultFalse
If True, negate the criterion check (i.e. raise an error if criterion is met).
cache¶
cache
Returns¶
-
bool
True is caching is switched on.
canonical_name¶
canonical_name
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
Returns the column names.
Returns¶
-
typing.List
List of the column names of this query.
column_names_as_string_list¶
column_names_as_string_list
Get the column names as a comma separated list
Returns¶
-
str
Comma separated list of column names
dependencies¶
dependencies
Returns¶
-
set
The set of queries which this one is directly dependent on.
fully_qualified_table_name¶
fully_qualified_table_name
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
True if spatial unit has geography information.
Returns¶
bool
has_lon_lat_columns¶
has_lon_lat_columns
True if spatial unit has lon/lat columns.
Returns¶
bool
index_cols¶
index_cols
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
True if spatial unit is a network object (cell or site).
Returns¶
bool
is_polygon¶
is_polygon
True if spatial unit's geographies are polygons.
Returns¶
bool
is_stored¶
is_stored
Returns¶
-
bool
True if the table is stored, and False otherwise.
location_id_columns¶
location_id_columns
Names of the columns that identify a location.
Returns¶
typing.List
query_id¶
query_id
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
Return the current query state.
Returns¶
-
QueryState
The current query state
query_state_str¶
query_state_str
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
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: Optional[str] = None) -> None
Subclass of PolygonSpatialUnit that maps all the sites in the database to a grid of arbitrary size.
Attributes¶
Parameters¶
-
size
:typing.Union
Size of the grid in kilometres
Methods¶
get_geom_query¶
get_geom_query(self) -> str
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
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
, defaultTrue
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
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
, defaultFalse
If True, negate the criterion check (i.e. raise an error if criterion is met).
cache¶
cache
Returns¶
-
bool
True is caching is switched on.
canonical_name¶
canonical_name
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
Returns the column names.
Returns¶
-
typing.List
List of the column names of this query.
column_names_as_string_list¶
column_names_as_string_list
Get the column names as a comma separated list
Returns¶
-
str
Comma separated list of column names
dependencies¶
dependencies
Returns¶
-
set
The set of queries which this one is directly dependent on.
fully_qualified_table_name¶
fully_qualified_table_name
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
True if spatial unit has geography information.
Returns¶
bool
has_lon_lat_columns¶
has_lon_lat_columns
True if spatial unit has lon/lat columns.
Returns¶
bool
index_cols¶
index_cols
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
True if spatial unit is a network object (cell or site).
Returns¶
bool
is_polygon¶
is_polygon
True if spatial unit's geographies are polygons.
Returns¶
bool
is_stored¶
is_stored
Returns¶
-
bool
True if the table is stored, and False otherwise.
location_id_columns¶
location_id_columns
Names of the columns that identify a location.
Returns¶
typing.List
query_id¶
query_id
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
Return the current query state.
Returns¶
-
QueryState
The current query state
query_state_str¶
query_state_str
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
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: Optional[str] = None, location_table_join_on: Optional[str] = None)
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
, default()
Name(s) of the column(s) to fetch from geom_table.
-
location_id_column_names
:typing.Union
, 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
, defaultNone
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
, defaultNone
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
, defaultgeom_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
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
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(
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
, defaultTrue
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
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
, defaultFalse
If True, negate the criterion check (i.e. raise an error if criterion is met).
cache¶
cache
Returns¶
-
bool
True is caching is switched on.
canonical_name¶
canonical_name
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
Returns the column names.
Returns¶
-
typing.List
List of the column names of this query.
column_names_as_string_list¶
column_names_as_string_list
Get the column names as a comma separated list
Returns¶
-
str
Comma separated list of column names
dependencies¶
dependencies
Returns¶
-
set
The set of queries which this one is directly dependent on.
fully_qualified_table_name¶
fully_qualified_table_name
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
True if spatial unit has geography information.
Returns¶
bool
has_lon_lat_columns¶
has_lon_lat_columns
True if spatial unit has lon/lat columns.
Returns¶
bool
index_cols¶
index_cols
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
True if spatial unit is a network object (cell or site).
Returns¶
bool
is_polygon¶
is_polygon
True if spatial unit's geographies are polygons.
Returns¶
bool
is_stored¶
is_stored
Returns¶
-
bool
True if the table is stored, and False otherwise.
location_id_columns¶
location_id_columns
Names of the columns that identify a location.
Returns¶
typing.List
query_id¶
query_id
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
Return the current query state.
Returns¶
-
QueryState
The current query state
query_state_str¶
query_state_str
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
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: Optional[str] = None)
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
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
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
, defaultNone
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
, defaultgeom
Name of the column in geom_table that defines the geography.
Methods¶
get_geom_query¶
get_geom_query(self) -> str
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
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
, defaultTrue
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
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
, defaultFalse
If True, negate the criterion check (i.e. raise an error if criterion is met).
cache¶
cache
Returns¶
-
bool
True is caching is switched on.
canonical_name¶
canonical_name
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
Returns the column names.
Returns¶
-
typing.List
List of the column names of this query.
column_names_as_string_list¶
column_names_as_string_list
Get the column names as a comma separated list
Returns¶
-
str
Comma separated list of column names
dependencies¶
dependencies
Returns¶
-
set
The set of queries which this one is directly dependent on.
fully_qualified_table_name¶
fully_qualified_table_name
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
True if spatial unit has geography information.
Returns¶
bool
has_lon_lat_columns¶
has_lon_lat_columns
True if spatial unit has lon/lat columns.
Returns¶
bool
index_cols¶
index_cols
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
True if spatial unit is a network object (cell or site).
Returns¶
bool
is_polygon¶
is_polygon
True if spatial unit's geographies are polygons.
Returns¶
bool
is_stored¶
is_stored
Returns¶
-
bool
True if the table is stored, and False otherwise.
location_id_columns¶
location_id_columns
Names of the columns that identify a location.
Returns¶
typing.List
query_id¶
query_id
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
Return the current query state.
Returns¶
-
QueryState
The current query state
query_state_str¶
query_state_str
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
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()
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
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
, defaultTrue
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
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
, defaultFalse
If True, negate the criterion check (i.e. raise an error if criterion is met).
canonical_name¶
canonical_name
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
True if spatial unit has geography information.
Returns¶
bool
has_lon_lat_columns¶
has_lon_lat_columns
True if spatial unit has lon/lat columns.
Returns¶
bool
is_network_object¶
is_network_object
True if spatial unit is a network object (cell or site).
Returns¶
bool
is_polygon¶
is_polygon
True if spatial unit's geographies are polygons.
Returns¶
bool
location_id_columns¶
location_id_columns
Names of the columns that identify a location.
Returns¶
typing.List
Class VersionedCellSpatialUnit¶
VersionedCellSpatialUnit() -> None
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
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
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(
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
, defaultTrue
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
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
, defaultFalse
If True, negate the criterion check (i.e. raise an error if criterion is met).
cache¶
cache
Returns¶
-
bool
True is caching is switched on.
canonical_name¶
canonical_name
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
Returns the column names.
Returns¶
-
typing.List
List of the column names of this query.
column_names_as_string_list¶
column_names_as_string_list
Get the column names as a comma separated list
Returns¶
-
str
Comma separated list of column names
dependencies¶
dependencies
Returns¶
-
set
The set of queries which this one is directly dependent on.
fully_qualified_table_name¶
fully_qualified_table_name
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
True if spatial unit has geography information.
Returns¶
bool
has_lon_lat_columns¶
has_lon_lat_columns
True if spatial unit has lon/lat columns.
Returns¶
bool
index_cols¶
index_cols
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
True if spatial unit is a network object (cell or site).
Returns¶
bool
is_polygon¶
is_polygon
True if spatial unit's geographies are polygons.
Returns¶
bool
is_stored¶
is_stored
Returns¶
-
bool
True if the table is stored, and False otherwise.
location_id_columns¶
location_id_columns
Names of the columns that identify a location.
Returns¶
typing.List
query_id¶
query_id
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
Return the current query state.
Returns¶
-
QueryState
The current query state
query_state_str¶
query_state_str
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
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
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
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
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(
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
, defaultTrue
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
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
, defaultFalse
If True, negate the criterion check (i.e. raise an error if criterion is met).
cache¶
cache
Returns¶
-
bool
True is caching is switched on.
canonical_name¶
canonical_name
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
Returns the column names.
Returns¶
-
typing.List
List of the column names of this query.
column_names_as_string_list¶
column_names_as_string_list
Get the column names as a comma separated list
Returns¶
-
str
Comma separated list of column names
dependencies¶
dependencies
Returns¶
-
set
The set of queries which this one is directly dependent on.
fully_qualified_table_name¶
fully_qualified_table_name
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
True if spatial unit has geography information.
Returns¶
bool
has_lon_lat_columns¶
has_lon_lat_columns
True if spatial unit has lon/lat columns.
Returns¶
bool
index_cols¶
index_cols
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
True if spatial unit is a network object (cell or site).
Returns¶
bool
is_polygon¶
is_polygon
True if spatial unit's geographies are polygons.
Returns¶
bool
is_stored¶
is_stored
Returns¶
-
bool
True if the table is stored, and False otherwise.
location_id_columns¶
location_id_columns
Names of the columns that identify a location.
Returns¶
typing.List
query_id¶
query_id
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
Return the current query state.
Returns¶
-
QueryState
The current query state
query_state_str¶
query_state_str
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
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: Optional[int] = 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: Optional[str] = None) -> Union[flowmachine.core.spatial_unit.CellSpatialUnit, flowmachine.core.spatial_unit.GeomSpatialUnit]
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.Optional
, defaultNone
Admin level (e.g. 1 for admin1, 2 for admin2, etc.). Required when spatial_unit_type='admin'.
-
region_id_column_name
:typing.Union
, defaultNone
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
, defaultNone
Size of the grid in kilometres. Required when spatial_unit_type='grid'.
-
geom_table
:typing.Union
, defaultNone
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
, defaultNone
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
, defaultgeom
Name of the column in geom_table that defines the geography. Required when spatial_unit_type='polygon'.
Returns¶
-
typing.Union
An object representing a mapping from location identifiers to a spatial unit.