naturf package

Submodules

naturf.config module

class naturf.config.Settings[source]

Bases: object

This class is used to define variables for the naturf application.

ALPHACOEFFICIENT = 3.59
AREA_FIELD = 'building_area'
AREA_WEIGHTED_MEAN_OF_BUILDING_HEIGHTS = 'area_weighted_mean_of_building_heights'
AVERAGE_DISTANCE_BETWEEN_BUILDINGS = 'average_distance_between_buildings'
BETACOEFFICIENT = 1.0
BUFFERED_FIELD = 'building_buffered'
BUILDING_HEIGHT_INTERVAL = 5
BUILDING_PLAN_AREA_FIELD = 'building_plan_area'
BUILDING_SURFACE_AREA = 'building_surface_area'
BUILDING_SURFACE_AREA_TO_PLAN_AREA_RATIO = 'building_surface_area_to_plan_area_ratio'
CAP_STYLE = 3
CENTROID_FIELD = 'building_centroid'
COMPLETE_ASPECT_RATIO = 'complete_aspect_ratio'
CONSTANT_15 = 15
CONSTANT_75 = 7.5
DATA_GEOMETRY_FIELD_NAME = 'geometry'
DATA_HEIGHT_FIELD_NAME = 'Max_HOUSE_'
DATA_ID_FIELD_NAME = 'OBJECTID'
DEFAULT_FILL_VALUE = 0
DEFAULT_OUTPUT_RESOLUTION = [0.00083333333, 0.00083333333]
DEFAULT_STREET_WIDTH = 15
DEGREES_IN_CIRCLE = 360
DILAREA_DEFAULT = 10000
DISPLACEMENT_HEIGHT_FACTOR = 0.67
DISTANCE_BETWEEN_BUILDINGS = 'distance_between_buildings'
DISTANCE_TO_NEIGHBOR_BY_CENTROID = 'distance_to_neighbor_by_centroid'
DRAGCOEFFICIENT_0003 = 0.003
DRAGCOEFFICIENT_03 = 0.3
EAST = 'east'
EAST_WEST = 'east_west'
FRONTAL_AREA_EAST = 'frontal_area_east'
FRONTAL_AREA_INDEX_EAST = 'frontal_area_index_east'
FRONTAL_AREA_INDEX_NORTH = 'frontal_area_index_north'
FRONTAL_AREA_INDEX_SOUTH = 'frontal_area_index_south'
FRONTAL_AREA_INDEX_WEST = 'frontal_area_index_west'
FRONTAL_AREA_NORTH = 'frontal_area_north'
FRONTAL_AREA_SOUTH = 'frontal_area_south'
FRONTAL_AREA_WEST = 'frontal_area_west'
FRONTAL_LENGTH_EAST = 'frontal_length_east'
FRONTAL_LENGTH_NORTH = 'frontal_length_north'
FRONTAL_LENGTH_SOUTH = 'frontal_length_south'
FRONTAL_LENGTH_WEST = 'frontal_length_west'
GEOMETRY_FIELD = 'building_geometry'
GRIMMOND_OKE_DISPLACEMENT_HEIGHT = 'grimmond_oke_displacement_height'
GRIMMOND_OKE_ROUGHNESS_LENGTH = 'grimmond_oke_roughness_length'
HEIGHT_FIELD = 'building_height'
HEIGHT_TO_WIDTH_RATIO = 'height_to_width_ratio'
ID_FIELD = 'building_id'
MACDONALD_DISPLACEMENT_HEIGHT = 'macdonald_displacement_height'
MACDONALD_ROUGHNESS_LENGTH_EAST = 'macdonald_roughness_length_east'
MACDONALD_ROUGHNESS_LENGTH_NORTH = 'macdonald_roughness_length_north'
MACDONALD_ROUGHNESS_LENGTH_SOUTH = 'macdonald_roughness_length_south'
MACDONALD_ROUGHNESS_LENGTH_WEST = 'macdonald_roughness_length_west'
MAX_BUILDING_HEIGHT = 75
MEAN_BUILDING_HEIGHT = 'mean_building_height'
NEIGHBOR = 'neighbor'
NEIGHBOR_AREA_FIELD = 'building_area_neighbor'
NEIGHBOR_CENTROID_FIELD = 'building_centroid_neighbor'
NEIGHBOR_GEOMETRY_FIELD = 'building_geometry_neighbor'
NEIGHBOR_HEIGHT_FIELD = 'building_height_neighbor'
NEIGHBOR_ID_FIELD = 'building_id_neighbor'
NEIGHBOR_VOLUME_FIELD = 'volume_field_neighbor'
NORTH = 'north'
NORTHEAST_DEGREES = 45
NORTHWEST_DEGREES = 135
NORTH_SOUTH = 'north_south'
OBSTACLEDRAGCOEFFICIENT = 1.12
OUTPUT_CRS = 'EPSG:4326'
PLAN_AREA_DENSITY = 'plan_area_density'
PLAN_AREA_FRACTION = 'plan_area_fraction'
PSI_H = 0.193
RADIUS = 100
RAUPACH_DISPLACEMENT_HEIGHT_EAST = 'raupach_displacement_height_east'
RAUPACH_DISPLACEMENT_HEIGHT_NORTH = 'raupach_displacement_height_north'
RAUPACH_DISPLACEMENT_HEIGHT_SOUTH = 'raupach_displacement_height_south'
RAUPACH_DISPLACEMENT_HEIGHT_WEST = 'raupach_displacement_height_west'
RAUPACH_ROUGHNESS_LENGTH_EAST = 'raupach_roughness_length_east'
RAUPACH_ROUGHNESS_LENGTH_NORTH = 'raupach_roughness_length_north'
RAUPACH_ROUGHNESS_LENGTH_SOUTH = 'raupach_roughness_length_south'
RAUPACH_ROUGHNESS_LENGTH_WEST = 'raupach_roughness_length_west'
RDH_THRESHOLD_MAX = 3
RDH_THRESHOLD_MIN = 0
ROOFTOP_AREA_DENSITY = 'rooftop_area_density'
ROUGHNESS_LENGTH_FACTOR = 0.1
RRL_THRESHOLD_MAX = 3
RRL_THRESHOLD_MIN = 0
SCALING_FACTOR = 4
SKY_VIEW_FACTOR = 'sky_view_factor'
SMALL_DECIMAL = 1e-31
SOUTH = 'south'
SOUTHEAST_DEGREES = 315
SOUTHEAST_DEGREES_ARCTAN = -45
SOUTHWEST_DEGREES = 225
SOUTHWEST_DEGREES_ARCTAN = -135
SPATIAL_JOIN_LIST = ['building_height_target', 'building_height_neighbor', 'building_id_target', 'building_id_neighbor', 'building_area_target', 'building_area_neighbor', 'building_geometry_target', 'building_geometry_neighbor']
STANDARD_DEVIATION_OF_BUILDING_HEIGHTS = 'standard_deviation_of_building_heights'
START_OF_CIRCLE_DEGREES = 0
TARGET = 'target'
TARGET_AREA_FIELD = 'building_area_target'
TARGET_BUFFERED_FIELD = 'building_buffered_target'
TARGET_CENTROID_FIELD = 'building_centroid_target'
TARGET_GEOMETRY_FIELD = 'building_geometry_target'
TARGET_HEIGHT_FIELD = 'building_height_target'
TARGET_ID_FIELD = 'building_id_target'
TOTAL_PLAN_AREA = 'total_plan_area'
TOTAL_PLAN_AREA_GEOMETRY = 'total_plan_area_geometry'
VERTICAL_DISTRIBUTION_OF_BUILDING_HEIGHTS = 'vertical_distribution_of_building_heights'
VOLUME_FIELD = 'volume_field'
VONKARMANCONSTANT = 0.4
WALL_ANGLE = 'wall_angle'
WALL_DIRECTION = 'wall_direction'
WALL_LENGTH = 'wall_length'
WALL_LENGTH_EAST = 'wall_length_east'
WALL_LENGTH_NORTH = 'wall_length_north'
WALL_LENGTH_SOUTH = 'wall_length_south'
WALL_LENGTH_WEST = 'wall_length_west'
WEST = 'west'

naturf.driver module

class naturf.driver.Model(inputs: dict, outputs: List[str], **kwargs)[source]

Bases: object

execute() → DataFrame[source]

Run the driver.

graph(view: bool = True, output_file_path: str | None = None) → object[source]

Show the DAG. Return the graph object for the given inputs to execute.

list_parameters()[source]

List all available parameters.

naturf.nodes module

naturf.nodes.area_weighted_mean_of_building_heights(buildings_intersecting_plan_area: GeoDataFrame) → Series[source]

Calculate the area weighted mean of building heights for each target building in a GeoPandas GeoDataFrame. The entire area of buildings considered to be neighbors are included in the calculation.

Parameters:

buildings_intersecting_plan_area (gpd.GeoDataFrame) – Geometry field for the neighboring buildings from the spatially joined data.

Returns:

The area weighted mean of building heights for all buildings within the target building’s plan area.

naturf.nodes.average_distance_between_buildings(distance_between_buildings: Series) → Series[source]

Calculate the average distance from the target building to all neighboring buildings.

Parameters:

distance_between_buildings (pd.Series) – distance from the target building to each neighbor building.

Returns:

float

naturf.nodes.building_area(building_geometry: Series) → Series[source]

Calculate the area of the building geometry.

Parameters:

building_geometry (pd.Series) – Building Geometry.

Returns:

pd.Series

naturf.nodes.building_plan_area(buildings_intersecting_plan_area: GeoDataFrame, join_predicate: str = 'intersection', join_rsuffix: str = 'neighbor') → Series[source]

Calculate the building plan area from the GeoDataFrame of buildings intersecting the plan area.

Parameters:

  • buildings_intersecting_plan_area (gpd.GeoDataFrame) – Geometry field for the neighboring buildings from the spatially joined data.

  • join_predicate (str) – Selected topology of join. DEFAULT: intersection

  • join_rsuffix (str) – Suffix of the right object in the join. DEFAULT: neighbor

Returns:

The building plan area for each unique building in the buildings_intersecting_plan_area GeoDataFrame.

naturf.nodes.building_surface_area(wall_length: DataFrame, building_height: Series, building_area: Series) → Series[source]

Calculate the building surface area for each building in a Panda Series. In naturf, the building footprint area is the same as the roof area.

Parameters:

  • wall_length (pd.DataFrame) – Wall length in each cardinal direction for each building.

  • building_height (pd.Series) – Building height for each building.

  • building_area (pd.Series) – Building area field.

Returns:

Panda Series with building surface area.

naturf.nodes.building_surface_area_to_plan_area_ratio(building_surface_area: Series, total_plan_area: Series) → Series[source]

Calculate the building surface area to plan area ratio for each building in a Pandas Series. In naturf, the building footprint area is the same as the roof area.

Parameters:

  • building_surface_area (pd.Series) – Building surface area for each building.

  • total_plan_area (pd.Series) – Total plan area for each building.

Returns:

Panda Series with building surface area to plan area ratio.

naturf.nodes.buildings_intersecting_plan_area(building_id: Series, building_height: Series, building_geometry: Series, building_area: Series, total_plan_area_geometry: Series, wall_length: DataFrame, target_crs: CRS, join_type: str = 'left', join_predicate: str = 'intersects', join_lsuffix: str = 'target', join_rsuffix: str = 'neighbor') → GeoDataFrame[source]

Conduct a spatial join to get the building areas that intersect the buffered target buildings.

Parameters:

  • building_id (pd.Series) – Building ID field.

  • building_height (pd.Series) – Building height field.

  • building_geometry (pd.Series) – Geometry field for the buildings.

  • building_area (pd.Series) – Building area field.

  • total_plan_area_geometry (pd.Series) – Geometry of the buffered building.

  • target_crs (pd.Series) – Coordinate reference system field of the parent geometry.

  • join_type (str) – Type of join desired. DEFAULT: left

  • join_predicate (str) – Selected topology of join. DEFAULT: intersects

  • join_lsuffix (str) – Suffix of the left object in the join. DEFAULT: target

  • join_rsuffix (str) – Suffix of the right object in the join. DEFAULT: neighbor

Returns:

GeoDataFrame of building areas that intersect the buffered target buildings and their attributes.

naturf.nodes.complete_aspect_ratio(building_surface_area: Series, total_plan_area: Series, building_plan_area: Series) → Series[source]

Calculate the complete aspect ratio for each building in a Pandas Series. In naturf, the building footprint area is the same as the roof area, and the exposed ground is the difference between total plan area and building plan area.

Parameters:

  • building_surface_area (pd.Series) – Building surface area for each building.

  • total_plan_area (pd.Series) – Total plan area for each building.

  • building_plan_area (pd.Series) – Building plan area for each building.

Returns:

Panda Series with complete aspect ratio.

naturf.nodes.distance_between_buildings(buildings_intersecting_plan_area: GeoDataFrame) → Series[source]

Calculate the distance between each building and its neighbor as defined in buildings_intersecting_plan_area.

Parameters:

buildings_intersecting_plan_area (gpd.GeoDataFrame) – Geometry field for the neighboring buildings from the spatially joined data.

Returns:

The distance between each building and its neighbors in a Pandas Series.

naturf.nodes.filter_height_range(standardize_column_names_df: GeoDataFrame) → GeoDataFrame[source]

Filter out any zero height buildings and reindex the data frame. Extract the building_id, building_height, and geometry fields to nodes.

Parameters:

standardize_column_names_df (gpd.GeoDataFrame) – GeoDataFrame of the input shapefile with renamed columns.

Returns:

GeoDataFrame

naturf.nodes.frontal_area(frontal_length: DataFrame, building_height: Series) → DataFrame[source]

Calculate the frontal area for each building in a Pandas DataFrame in each cardinal direction.

Parameters:

  • frontal_length (pd.DataFrame) – Frontal length in each cardinal direction for each building.

  • building_height (pd.Series) – Building height for each building.

Returns:

Pandas DataFrame with frontal area in each cardinal direction.

naturf.nodes.frontal_area_density(frontal_length: DataFrame, building_height: Series, total_plan_area: Series) → DataFrame[source]

Calculate the frontal area density for each building in a GeoPandas GeoSeries. Frontal area density is the frontal area of a building at a specific height increment divided by the total plan area. naturf calculates frontal area density from the four cardinal directions (east, north, west, south) and at 5 meter increments from ground level to 75 meters unless otherwise specified.

Parameters:

  • frontal_length (pd.DataFrame) – Frontal length in each cardinal direction for each building.

  • building_height (pd.Series) – Building height for each building.

  • total_plan_area (pd.Series) – Total plan area for each building.

Returns:

Pandas DataFrame with frontal area density for each cardinal direction and each BUILDING_HEIGHT_INTERVAL for each building.

naturf.nodes.frontal_area_index(frontal_area: DataFrame, total_plan_area: Series) → DataFrame[source]

Calculate the frontal area index for each building in a Pandas DataFrame in each cardinal direction.

Parameters:

  • frontal_area (pd.DataFrame) – Frontal area in each cardinal direction for each building.

  • total_plan_area (pd.Series) – Total plan area for each building.

Returns:

Pandas DataFrame with frontal area index in each cardinal direction.

naturf.nodes.frontal_length(buildings_intersecting_plan_area: GeoDataFrame) → DataFrame[source]

Calculate the frontal length for each cardinal direction from the GeoDataFrame of buildings intersecting the plan area. buildings_intersecting_plan_area() needs to include wall_length.

Parameters:

buildings_intersecting_plan_area (gpd.GeoDataFrame) – Geometry field for the neighboring buildings from the spatially joined data.

Returns:

The frontal area for each cardinal direction for each unique building in the buildings_intersecting_plan_area GeoDataFrame.

naturf.nodes.grimmond_oke_displacement_height(building_height: Series) → Series[source]

Calculate the Grimmond & Oke displacement height for each building

Parameters:

building_height (pd.Series) – Building height field.

Returns:

pd.Series

naturf.nodes.grimmond_oke_roughness_length(building_height: Series) → Series[source]

Calculate the Grimmond & Oke roughness length for each building

Parameters:

building_height (pd.Series) – Building height field.

Returns:

pd.Series

naturf.nodes.height_to_width_ratio(mean_building_height: Series, average_distance_between_buildings: Series) → Series[source]

Calculate the height to width ratio for each building.

Parameters:

  • mean_building_height (pd.Series) – Series of mean building height for all buildings within the target building’s plan area

  • average_distance_between_buildings (pd.Series) – Series of average distance from each building to all neighboring buildings

Returns:

pd.Series

naturf.nodes.input_shapefile_df(input_shapefile: str) → GeoDataFrame[source]

Import shapefile to GeoDataFrame using only desired columns.

Params input_shapefile:

Full path with file name and extension to the input shapefile.

Returns:

GeoDataFrame

naturf.nodes.lot_area(buildings_intersecting_plan_area: GeoDataFrame, building_surface_area: Series) → Series[source]

Calculate the lot area for each building in a Panda Series. Lot area is the total surface area of all buildings within a given building’s plan area divided by the number of buildings in the plan area.”

Parameters:

  • buildings_intersecting_plan_area (gpd.GeoDataFrame) – Geometry field for the neighboring buildings from the spatially joined data.

  • building_surface_area (pd.Series) – Building surface area for each building.

Returns:

Panda Series of lot area for each building.

naturf.nodes.macdonald_displacement_height(building_height: Series, plan_area_fraction: Series) → Series[source]

Calculate the Macdonald et al. displacement height for each building in a Pandas Series.

Parameters:

  • building_height (pd.Series) – Building height for each building.

  • plan_area_fraction (pd.Series) – Plan area fraction for each building.

naturf.nodes.macdonald_roughness_length(building_height: Series, macdonald_displacement_height: Series, frontal_area: DataFrame, lot_area: Series) → DataFrame[source]

Calculate the Macdonald et al. roughness length for each building in a Pandas Series.

Parameters:

  • building_height (pd.Series) – Building height for each building.

  • macdonald_displacement_height (pd.Series) – Macdonald displacement height for each building.

  • frontal_area (pd.DataFrame) – Frontal area for each building in each cardinal direction.

  • lot_area (pd.Series) – Lot area for each building.

Returns:

Panda Series with Macdonald roughness length for each building in each cardinal direction.

naturf.nodes.mean_building_height(buildings_intersecting_plan_area: GeoDataFrame) → Series[source]

Calculate the mean building height for all buildings within the target building’s total plan area.

Parameters:

buildings_intersecting_plan_area (gpd.GeoDataFrame) – Geometry field for the neighboring buildings from the spatially joined data.

Returns:

The mean building height for all buildings within the target building’s plan area.

naturf.nodes.plan_area_density(building_plan_area: Series, building_height: Series, total_plan_area: Series) → DataFrame[source]

Calculate the plan area density for each building in a GeoPandas GeoSeries. Plan area density is the building plan area at a specific height increment divided by the total plan area. naturf calculates plan area density from the four cardinal directions (north, east, south, west) and at 5-meter increments from ground level to 75 meters unless otherwise specified.

Parameters:

  • building_plan_area (pd.Series) – Building plan area for each building.

  • building_height (pd.Series) – Building height for each building.

  • total_plan_area (pd.Series) – Total plan area for each building.

Returns:

Pandas DataFrame with plan area density for each BUILDING_HEIGHT_INTERVAL for each building.

naturf.nodes.plan_area_fraction(building_plan_area: Series, total_plan_area: Series) → Series[source]

Calculate the plan area fraction for each building in a Pandas Series. Plan area fraction is the building plan area at ground level for each building divided by the total plan area.

Parameters:

  • building_plan_area (pd.Series) – Building plan area for each building.

  • total_plan_area (pd.Series) – Total plan area for each building.

Returns:

Pandas Series with plan area fraction for each building.

naturf.nodes.raupach_displacement_height(building_height: Series, frontal_area_index: DataFrame) → DataFrame[source]

Calculate the Raupach displacement height for each building in each cardinal direction in a Panda Series. Default values for constants are set in the config file.

Parameters:

  • building_height (pd.Series) – Building height for each building.

  • frontal_area_index (pd.DataFrame) – Frontal area index for each building in each cardinal direction.

Returns:

Pandas DataFrame with Raupach displacement height in each cardinal direction.

naturf.nodes.raupach_roughness_length(building_height: Series, frontal_area_index: DataFrame, raupach_displacement_height: DataFrame) → DataFrame[source]

Calculate the Raupach roughness length for each building in each cardinal direction in a Panda Series. Default values for constants are set in the config file.

Parameters:

  • building_height (pd.Series) – Building height for each building.

  • frontal_area_index (pd.DataFrame) – Frontal area index for each building in each cardinal direction.

  • raupach_displacment_height (pd.DataFrame) – Raupach displacment height for each building in each cardinal direction.

Returns:

Pandas DataFrame with Raupach roughness length in each cardinal direction.

naturf.nodes.rooftop_area_density(plan_area_density: DataFrame) → DataFrame[source]

Calculate the rooftop area density for each building in a Pandas DataFrame. Rooftop area density is the roof area of all buildings within the total plan area at a specified height increment divided by the total plan area. naturf projects building footprints vertically to the building height, meaning that rooftop area density is equal to the plan area density.

Parameters:

plan_area_density (pd.DataFrame) – Plan area density at each specified height increment.

Returns:

Pandas DataFrame with rooftop area density for each BUILDING_HEIGHT_INTERVAL for each building.

naturf.nodes.sky_view_factor(building_height: Series, average_distance_between_buildings: Series) → Series[source]

Calculate the 2D sky view factor for each building.

Parameters:

  • building_height (pd.Series) – Building height field.

  • average_distance_between_buildings (float) – Average distance between the target building and all neighboring buildings.

Returns:

pd.Series

naturf.nodes.standard_deviation_of_building_heights(buildings_intersecting_plan_area: GeoDataFrame) → Series[source]

Calculate the standard deviation of building heights for all buildings within the target building’s total plan area.

Parameters:

buildings_intersecting_plan_area (gpd.GeoDataFrame) – Geometry field for the neighboring buildings from the spatially joined data.

Returns:

The standard deviation of building heights for all buildings within the target building’s plan area.

naturf.nodes.standardize_column_names_df(input_shapefile_df: GeoDataFrame) → GeoDataFrame[source]

Standardize field names so use throughout code will be consistent throughout.

Params input_shapefile_df:

GeoDataFrame of from the input shapefile.

Returns:

GeoDataFrame

naturf.nodes.target_crs(input_shapefile_df: GeoDataFrame) → CRS[source]

Extract coordinate reference system from geometry.

Params input_shapefile_df:

GeoDataFrame of from the input shapefile.

Returns:

pyproj Coordinate Reference System (CRS) object

naturf.nodes.total_plan_area(total_plan_area_geometry: GeoSeries) → Series[source]

Calculate the total plan area for each building in a GeoPandas GeoSeries.

Parameters:

geometry (gpd.GeoSeries) – Geometry for a series of buildings.

Returns:

Pandas Series with total plan area for each building.

naturf.nodes.total_plan_area_geometry(building_geometry: Series, radius: int = 100, cap_style: int = 3) → GeoSeries[source]

Calculate the geometry of the total plan area which is the buffer of the building for the desired radius and cap style.

Parameters:

  • building_geometry (pd.Series) – Geometry of the building.

  • radius (int) – The radius of the buffer. 100 (default, set in config.py)

  • cap_style – The shape of the buffer. 1 == Round 2 == Flat 3 == Square (default)

Returns:

pd.Series

naturf.nodes.vertical_distribution_of_building_heights(building_height: Series) → DataFrame[source]

Represent the location of buildings at 5m increments from ground level to 75m unless otherwise specified. If is within a given height bin, it will be given a 1 and it will be given a 0 otherwise.”

Parameters:

building_height (pd.Series) – Building height for each building.

Returns:

Pandas DataFrame with the distribution of building heights at each BUILDING_HEIGHT_INTERVAL for each building.

naturf.nodes.wall_angle_direction_length(building_geometry: Series) → DataFrame[source]

Calculate the wall angle, direction, and length for each building in a GeoPandas GeoSeries.

Parameters:

geometry (pd.Series) – Geometry for a series of buildings.

Returns:

Pandas DataFrame with wall angle, direction, and length for each building.

naturf.nodes.wall_length(wall_angle_direction_length: DataFrame) → DataFrame[source]

Calculate the wall length for each building in a GeoPandas GeoSeries.

Parameters:

wall_angle_direction_length (pd.DataFrame) – Wall angle, direction, and length for a series of buildings.

Returns:

Pandas DataFrame with wall area for each cardinal direction for each building.

naturf.output module

naturf.output.aggregate_rasters(rasterize_parameters: Dataset) → Dataset[source]

Divide each raster by the number of buildings in the cell to get the average parameter value for each cell.

Parameters:

rasterize_parameters (Xr.Dataset) – Xr.Dataset with rasterized parameters summed at the defined resolution.

Returns:

Xr.Dataset containing rasterized parameter values averaged at the defined resolution.

naturf.output.merge_parameters(frontal_area_density: DataFrame, plan_area_density: DataFrame, rooftop_area_density: DataFrame, plan_area_fraction: Series, mean_building_height: Series, standard_deviation_of_building_heights: Series, area_weighted_mean_of_building_heights: Series, building_surface_area_to_plan_area_ratio: Series, frontal_area_index: DataFrame, complete_aspect_ratio: Series, height_to_width_ratio: Series, sky_view_factor: Series, grimmond_oke_roughness_length: Series, grimmond_oke_displacement_height: Series, raupach_roughness_length: DataFrame, raupach_displacement_height: DataFrame, macdonald_roughness_length: DataFrame, macdonald_displacement_height: Series, vertical_distribution_of_building_heights: DataFrame, building_geometry: Series, target_crs: CRS) → GeoDataFrame[source]

Merge all parameters into one Pandas DataFrame.

Parameters:

  • frontal_area_density (pd.DataFrame) – Frontal area density at each specified height increment and each cardinal direction.

  • plan_area_density (pd.DataFrame) – Plan area density at each specified height increment.

  • rooftop_area_density (pd.DataFrame) – Rooftop area density at each specified height increment.

  • plan_area_fraction (pd.Series) – Plan area fraction for each building.

  • mean_building_height (pd.Series) – Series of mean building height for all buildings within the target building’s total plan area.

  • standard_deviation_of_building_heights (pd.Series) – Series of standard deviation of building height for all buildings within the target building’s total plan area.

  • area_weighted_mean_of_building_heights (pd.Series) – Series of area weighted mean building heights for each building.

  • building_surface_area_to_plan_area_ratio (pd.Series) – Series of building surface area to plan area ratio for each building.

  • frontal_area_index (pd.DataFrame) – Frontal area index for each building in each cardinal direction.

  • complete_aspect_ratio (pd.Series) – Complete aspect ratio for each building.

  • height_to_width_ratio (pd.Series) – Height-to-width ratio for each building.

  • sky_view_factor (pd.Series) – Sky view factor for each building.

  • grimmond_oke_roughness_length (pd.Series) – Grimmond & Oke roughness length for each building.

  • grimmond_oke_displacement_height (pd.Series) – Grimmond & Oke displacement height for each building.

  • raupach_roughness_length (pd.DataFrame) – Raupach roughness length for each building in each cardinal direction.

  • raupach_displacment_height (pd.DataFrame) – Raupach displacment height for each building in each cardinal direction.

  • macdonald_roughness_length (pd.DataFrame) – Macdonald roughness_length for each building in each cardinal direction.

  • macdonald_displacement_height (pd.Series) – Macdonald displacement height for each building.

  • vertical_distribution_of_building_heights (pd.DataFrame) – Distribution of building heights for each building ata each height increment.

  • building_geometry (pd.Series) – Geometry field for the buildings.

  • target_crs (CRS) – Coordinate reference system field of the parent geometry.

Returns:

Pandas DataFrame with all parameters merged together.

naturf.output.numpy_to_binary(raster_to_numpy: ndarray) → bytes[source]

Turn the master numpy array containing all 132 aggregated parameters into a binary stream.

Parameters:

raster_to_numpy (np.ndarray) – 132 level numpy array with each level being an aggregated parameter.

Returns:

Binary object containing the parameter data.

naturf.output.raster_to_numpy(aggregate_rasters: Dataset) → ndarray[source]

Stack all 132 rasterized parameters into one numpy array for conversion to a binary file.

Parameters:

aggregate_rasters (xr.Dataset) – Dataset with rasterized parameter values averaged at the defined resolution.

Returns:

132 level numpy array with each level being an aggregated parameter.

naturf.output.rasterize_parameters(merge_parameters: GeoDataFrame) → Dataset[source]

Rasterize parameters in preparation for conversion to numpy arrays. Raster will be of resolution Settings.DEFAULT_OUTPUT_RESOLUTION and each cell will be the sum of each parameter value within. By default all_touched is True so that every building that is within a cell is included in the sum.

Parameters:

merge_parameters (Pandas.GeoDataFrame) – Pandas.GeoDataFrame with all selected urban parameters for each building.

Returns:

Xr.Dataset containing rasterization of selected urban parameters.

naturf.output.write_binary(numpy_to_binary: bytes, raster_to_numpy: ndarray) → None[source]

Write the binary file that will be input to WRF.

Parameters:

  • numpy_to_binary (bytes) – Binary object containing the parameter data.

  • raster_to_numpy (np.ndarray) – 132 level numpy array with each level being an aggregated parameter.

naturf.output.write_index(raster_to_numpy: ndarray, building_geometry: Series, target_crs: CRS, index_filename: str = 'index') → str[source]

Write the index file that will accompany the output binary file.

Parameters:

  • raster_to_numpy (np.ndarray) – 132 level numpy array with each level being an aggregated parameter.

  • building_geometry (pd.Series) – Geometry field for the buildings.

  • target_crs (crs) – Coordinate reference system field of the parent geometry.