Core API

These are the base classes underlying every layer and metric, defined in city_metrix.metrix_model. Most users will only call the public methods documented in Core Concepts — this page is the full signature reference.

GeoZone

city_metrix.metrix_model.GeoZone

GeoZone(geo_zone: Union[GeoDataFrame | str], crs=WGS_CRS)

geo_type instance-attribute

geo_type = GeoType.CITY_CENTROID

city_id instance-attribute

city_id = None

city_json instance-attribute

city_json = None

aoi_id instance-attribute

aoi_id = None

admin_level instance-attribute

admin_level = None

zones instance-attribute

zones = geo_zone

bbox instance-attribute

bbox = geo_zone.total_bounds

crs instance-attribute

crs = crs

latitude instance-attribute

latitude = city_data.get('latitude')

longitude instance-attribute

longitude = city_data.get('longitude')

bounds instance-attribute

bounds = self.bbox

epsg_code instance-attribute

epsg_code = int(self.crs.split(':')[1])

projection_type instance-attribute

projection_type = get_projection_type(self.crs)

units instance-attribute

units = 'degrees' if self.projection_type == ProjectionType.GEOGRAPHIC else 'meters'

coords instance-attribute

coords = (self.min_x, self.min_y, self.max_x, self.max_y)

polygon instance-attribute

polygon = shapely.box(self.min_x, self.min_y, self.max_x, self.max_y)

centroid instance-attribute

centroid = self.polygon.centroid

GeoExtent

city_metrix.metrix_model.GeoExtent

GeoExtent(bbox: Union[tuple[float, float, float, float] | GeoZone | str], crs=WGS_CRS)

geo_type instance-attribute

geo_type = bbox.geo_type

city_id instance-attribute

city_id = None

aoi_id instance-attribute

aoi_id = None

admin_level instance-attribute

admin_level = None

bbox instance-attribute

bbox = bbox.bbox

crs instance-attribute

crs = box_crs.srs

epsg_code instance-attribute

epsg_code = int(self.crs.split(':')[1])

projection_type instance-attribute

projection_type = get_projection_type(self.crs)

units instance-attribute

units = 'degrees' if self.projection_type == ProjectionType.GEOGRAPHIC else 'meters'

bounds instance-attribute

bounds = self.bbox

min_x instance-attribute

min_x = self.bbox[0]

min_y instance-attribute

min_y = self.bbox[1]

max_x instance-attribute

max_x = self.bbox[2]

max_y instance-attribute

max_y = self.bbox[3]

coords instance-attribute

coords = (self.min_x, self.min_y, self.max_x, self.max_y)

centroid instance-attribute

centroid = shapely.box(self.min_x, self.min_y, self.max_x, self.max_y).centroid

polygon instance-attribute

polygon = shapely.box(self.min_x, self.min_y, self.max_x, self.max_y)

to_ee_rectangle

to_ee_rectangle()

Converts bbox to an Earth Engine geometry rectangle

buffer_utm_bbox

buffer_utm_bbox(buffer_m)

as_utm_bbox

as_utm_bbox()

Converts bbox to UTM projection

Returns:

Type	Description

as_geographic_bbox

as_geographic_bbox()

Converts bbox to lat-lon bbox

Returns:

Type	Description

Layer

city_metrix.metrix_model.Layer

Layer(aggregate=None, masks=None, **kwargs)

aggregate instance-attribute

aggregate = aggregate

masks instance-attribute

masks = [] if masks is None else masks

resolution instance-attribute

resolution = kwargs.get('resolution')

get_data abstractmethod

get_data(bbox: GeoExtent, spatial_resolution: int = None, resampling_method: str = None) -> Union[xr.DataArray, gpd.GeoDataFrame]

Extract the data from the source and return it in a way we can compare to other layers. This is an abstract class to be implemented for each layer.

Parameters:

Name	Type	Description	Default
bbox	GeoExtent	a tuple of floats representing the bounding box, (min x, min y, max x, max y)	required
spatial_resolution	int	resolution of continuous raster data in meters	None
resampling_method	str	interpolation method for continuous raster layers (bilinear, bicubic, nearest)	None

Returns:

Type	Description
Union[DataArray, GeoDataFrame]	A rioxarray-format DataArray or a GeoPandas DataFrame

filename

filename(bbox: GeoExtent) -> tuple

write

write(bbox: GeoExtent, target_file_path: str, tile_side_length: int = None, buffer_size: int = None, length_units: str = None, spatial_resolution: int = None, resampling_method: str = None, **kwargs)

Write the layer to a path. Does not apply masks. Function is mostly intended for testing purposes.

Parameters:

Name	Type	Description	Default
bbox	GeoExtent	a GeoExtent object	required
target_file_path	str	local path to output to	required
tile_side_length	int	optional param to tile the results into multiple files specified as tile length on a side	None
buffer_size	int	tile buffer distance	None
length_units	str	units for tile_side_length and buffer_size (degrees, meters)	None
spatial_resolution	int	resolution of continuous raster data in meters	None
resampling_method	str	interpolation method for continuous raster layers (bilinear, bicubic, nearest)	None

Returns:

Type	Description

cache_city_data

cache_city_data(bbox: GeoExtent, s3_bucket: str, s3_env: str, aoi_buffer_m: int = None, spatial_resolution: int = None, force_data_refresh: bool = False)

Gets data values from source and writes to an S3 bucket if the target does not already exist.

Parameters:

Name	Type	Description	Default
bbox	GeoExtent	a GeoExtent object	required
s3_bucket	str	name of the S3 bucket	required
s3_env	str	name of the S3 environment folder within the bucket	required
aoi_buffer_m	int	AOI buffering size in meters used for writting to S3	None
spatial_resolution	int	resolution of continuous raster data in meters	None
force_data_refresh	bool	whether to force data refresh from source	False

retrieve_data

retrieve_data(bbox: GeoExtent, s3_bucket: str = CIF_CACHE_S3_BUCKET_URI, s3_env: str = DEFAULT_PRODUCTION_ENV, aoi_buffer_m: int = None, city_aoi_subarea: (float, float, float, float) = None, spatial_resolution: int = None) -> Union[xr.DataArray, gpd.GeoDataFrame]

Pulls data values from S3 cache or from the source, if not already in cache. If values are pulled from the source, then opportunistically writes the value to the S3 cache.

Parameters:

Name	Type	Description	Default
bbox	GeoExtent	a GeoExtent object	required
s3_bucket	str	name of the S3 bucket	CIF_CACHE_S3_BUCKET_URI
s3_env	str	name of the S3 environment folder within the bucket	DEFAULT_PRODUCTION_ENV
aoi_buffer_m	int	AOI buffering size in meters used for writting to S3	None
city_aoi_subarea	(float, float, float, float)	the bounds of a sub-area within a city extent	None
spatial_resolution	int	resolution of continuous raster data in meters	None

mask

mask(*layers)

Apply layers as masks

Parameters:

Name	Type	Description	Default
layers		lis	()

Returns:

Type	Description

groupby

groupby(geo_zone, spatial_resolution=None, layer=None, custom_tile_size_m=None)

Group layers by zones.

Parameters:

Name	Type	Description	Default
geo_zone		GeoZone containing geometries to group by.	required
spatial_resolution		resolution of continuous raster layers in meters	None
layer		Additional categorical layer to group by	None

Returns:

Type	Description
	LayerGroupBy object that can be aggregated.

LayerGroupBy

city_metrix.metrix_model.LayerGroupBy

LayerGroupBy(aggregate, geo_zone: GeoZone, spatial_resolution=None, layer=None, custom_tile_size_m=None, masks=None)

aggregate instance-attribute

aggregate = aggregate

masks instance-attribute

masks = [] if masks is None else masks

geo_zone instance-attribute

geo_zone = geo_zone

custom_tile_size_m instance-attribute

custom_tile_size_m = custom_tile_size_m

spatial_resolution instance-attribute

spatial_resolution = spatial_resolution

layer instance-attribute

layer = layer

mean

mean()

count

count()

sum

sum()

get_stats_funcs staticmethod

get_stats_funcs(stats_func)

Metric

city_metrix.metrix_model.Metric

Metric(metric=None)

metric instance-attribute

metric = metric

get_metric abstractmethod

get_metric(geo_zone: GeoZone, spatial_resolution: int) -> Union[pd.Series, pd.DataFrame]

Construct polygonal dataset using baser layers. This is an abstract class to be implemented for each metric.

Parameters:

Name	Type	Description	Default
geo_zone	GeoZone	a GeoZone object	required
spatial_resolution	int	resolution of continuous raster data in meters	required

Returns:

Type	Description
Union[Series, DataFrame]	A rioxarray-format GeoPandas DataFrame

write

write(geo_zone: GeoZone, target_file_path: str = None, spatial_resolution: int = None, **kwargs)

Write the metric to a path. Does not apply masks. Mostly intened for testing.

Parameters:

Name	Type	Description	Default
geo_zone	GeoZone	a GeoZone object	required
target_file_path	str	local or s3 path to output to	None
spatial_resolution	int	resolution of continuous raster data in meters	None

write_as_geojson

write_as_geojson(geo_zone: GeoZone, target_file_path: str = None, spatial_resolution: int = None, **kwargs)

Write the metric to a path. Does not apply masks. Intended for testing purposes.

Parameters:

Name	Type	Description	Default
geo_zone	GeoZone	a GeoZone object	required
target_file_path	str	local or s3 path to output to	None
spatial_resolution	int	resolution of continuous raster data in meters	None

cache_city_metric

cache_city_metric(geo_zone: GeoZone, s3_bucket: str, s3_env: str, spatial_resolution: int = None, force_data_refresh: bool = False) -> tuple[Union[pd.Series, pd.DataFrame], str]

Gets metric values from source(s) and writes to an S3 bucket if the target does not already exist.

Parameters:

Name	Type	Description	Default
geo_zone	GeoZone	a GeoZone object	required
s3_bucket	str	name of the S3 bucket	required
s3_env	str	name of the S3 environment folder within the bucket	required
spatial_resolution	int	resolution of continuous raster data in meters	None
force_data_refresh	bool	whether to force data refresh from source	False

retrieve_metric

retrieve_metric(geo_zone: GeoZone, s3_bucket: str = None, s3_env: str = None, spatial_resolution: int = None) -> tuple[Union[pd.Series, pd.DataFrame], str]

Pulls metric values from S3 cache or from the source, if not already in cache. If values are pulled from the source, then opportunistically writes the value to the S3 cache.

Parameters:

Name	Type	Description	Default
geo_zone	GeoZone	a GeoZone object	required
s3_bucket	str	name of the S3 bucket	None
s3_env	str	name of the S3 environment folder within the bucket	None
spatial_resolution	int	resolution of continuous raster data in meters	None