onstove.RasterLayer

class onstove.RasterLayer(category: str | None = None, name: str | None = '', path: str | None = None, conn: sqlalchemy.engine.Connection | None = None, normalization: str | None = 'MinMax', inverse: bool = False, distance_method: str | None = None, distance_limit: Callable[[ndarray], ndarray] | None = None, resample: str = 'nearest', window: Window | None = None, rescale: bool = False)

A RasterLayer is an object used to read, manipulate and visualize GIS raster data.

It uses rasterio to read GIS raster data, and stores the output in a numpy.ndarray under the layer attribute, and the metadata of the layer in the meta attribute. It also stores additional metadata as category and name of the layer, normalization and distance algorithms to use among others. This data structure is used in both the MCA and the OnStove models and the onstove.DataProcessor object.

Parameters:

category: str, optional

Category of the layer. This parameter is useful to group the data into logical categories such as “Demographics”, “Resources” and “Infrastructure” or “Demand”, “Supply” and “Others”. This categories are particularly relevant for the MCA analysis.

name: str, optional

Name of the dataset. This name will be used as default in the save() method as the name of the file.

path: str, optional

The relative path to the datafile. This file can be of any type that is accepted by rasterio.open().

conn: sqlalchemy.engine.Connection or sqlalchemy.engine.Engine, optional

PostgreSQL connection if the layer needs to be read from a database.

See also

read_layer() and onstove.DataProcessor.set_postgres()

Warning

The PostgreSQL database connection is under development for the RasterLayer class and it will be available in future releases.

normalization: str, default ‘MinMax’

Sets the default normalization method to use when calling the RasterLayer.normalize(). This is relevant to calculate the demand_index, supply_index, clean_cooking_index and assistance_need_index of the MCA model.

inverse: bool, default False

Sets the default mode for the normalization algorithm (see RasterLayer.normalize()).

distance_method: str, default ‘proximity’

Sets the default distance algorithm to use when calling the get_distance_raster() method.

distance_limit: Callable object (function or lambda function) with a numpy array as input, optional

Defines a distance limit or range to consider when calculating the distance raster.

Example: lambda function for distance range between 1,000 and 10,000 meters

>>> distance_limit = lambda  x: (x >= 1000) & (x <= 10000)

resample: str, default ‘nearest’

Sets the default method to use when resampling the dataset. Resampling occurs when changing the grid cell size of the raster, thus the values of the cells need to be readjusted to reflect the new cell size. Several sampling methods can be used, and which one to use is dependent on the nature of the data. For a list of the accepted methods refer to rasterio.enums.Resampling.

See also

reproject()

window: instance of rasterio.windows.Window

A Window is a view from a rectangular subset of a raster. It is used to perform windowed reading of raster layers. This is useful when working with large raster files in order to reduce memory RAM needs or to read only an area of interest from a broader raster layer.

See also

read_layer()

rescale: bool, default False

Sets the default value for the rescale attribute. This attribute is used in the align() method to rescale the values of a cell proportionally to the change in size of the cell. This is useful when aligning rasters that have different cell sizes and their values can be scaled proportionally.

Attributes:

friction

RasterLayer object containing a friction raster dataset used to compute a travel time map.

distance_raster

RasterLayer object containing a distance raster dataset calculated by the get_distance_raster() method using one of the distance methods.

normalized

RasterLayer object containing a normalized raster dataset calculated by the normalize() method using one of the normalization methods.

restrictions

List of RasterLayer or VectorLayer used to restrict areas from the distance calculations.

Warning

The use of restrictions is under development and it will be available in future releases.

weight

Value to weigh the layer’s “importance” on the MCA model. It is initialized with a default value of 1.

bounds

Wrapper property to get the west, south, east, north bounds of the dataset using the rasterio.transform.array_bounds function of rasterio.

data

:class:`numpy.ndarray<numpy:reference/arrays.ndarray> containing the data of the raster layer.

Methods

align(base_layer[, rescale, output_path, ...])	Aligns the raster's gridded data with the grid of an input raster.
calculate_default_transform(dst_crs)	Wrapper function to calculate the default transform using the rasterio.warp.calculate_default_transform function.
category_legend(im, ax, categories[, ...])	Creates a category legend for the current plot.
copy()	Wrapper class to the deepcopy function of the copy module.
cumulative_count([min_max])	Calculates a new data array flattening the raster's data values that fall in either of the specified lower or upper percentile.
get_distance_raster([method, output_path, ...])	This method calls the specified distance calculation method.
get_quantiles(quantiles)	Gets the values of th specified quantiles.
log(mask_layer[, output_path, create_raster])	Calculates a logarithmic representation of the raster dataset.
mask(mask_layer[, output_path, crop, ...])	Creates a masked version of the layer, based on an input shape given by a VectorLayer.
normalize([output_path, buffer, inverse, ...])	Normalizes the raster data by a given normalization method.
plot([cmap, ticks, tick_labels, ...])	Plots a map of the raster data.
polygonize()	Polygonizes the raster layer based on the gridded data values.
proximity([value])	Calculates an euclidean distance raster taking as starting points cells of the value indicated by the value parameter.
quantiles(quantiles)	Computes an array based on the desired quantiles of the raster array.
read_layer(path[, conn, window])	Reads a dataset from a GIS raster data file.
reproject(crs[, output_path, cell_width, ...])	Reprojects the raster data into a specified coordinate system.
save(output_path)	Saves the raster layer as a tif file.
save_image(name[, cmap, ticks, tick_labels, ...])	Saves the raster as an image map in the specified format.
save_style(name[, cmap, quantiles, ...])	Saves the colormap used for the raster as a sld style.
shape_from_cell(bounds, cell_height, cell_width)	Gets the shape (width and height) of the raster layer based on the bounds and a cell size.
start_points(condition)	Gets the rows and columns of the cells tha fulfil a condition.
travel_time(rows, cols[, ...])	Calculates a travel time map using the raster data as cost surface and specific cells as starting points.