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) → DataFrame[source]

Optimized calculation of building plan area using row-wise intersection and groupby sum.

Calculates the total area of intersection between each target’s buffered geometry and all its associated neighbors’ original geometries.

Parameters:: buildings_intersecting_plan_area (gpd.GeoDataFrame) – GeoDataFrame resulting from sjoin, containing target IDs (‘building_id_target’), target buffered geometry (‘building_buffered_target’), and neighbor geometry (‘building_geometry_neighbor’) per intersection pair.
Returns:: Series indexed by ‘building_id_target’, containing the total summed intersection area.
Return type:: pd.DataFrame

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: DataFrame) → 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.DataFrame) – 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 total frontal length for each cardinal direction per target building using optimized pandas groupby aggregation.

Requires input GeoDataFrame to have columns like ‘wall_length_north_neighbor’, etc., and a column specified by Settings.TARGET_ID_FIELD.

Parameters:: buildings_intersecting_plan_area (gpd.GeoDataFrame) – GeoDataFrame with target building IDs and neighbor wall lengths per direction.
Returns:: DataFrame indexed by target_building_id with total frontal lengths per direction.
Return type:: pd.DataFrame

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: DataFrame, 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.DataFrame) – 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: DataFrame, 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.DataFrame) – 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, n_jobs: int = -1) → DataFrame[source]

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

This function processes each building’s geometry to determine the angles, cardinal directions, and lengths of its walls. It utilizes parallel processing to enhance performance, especially with large datasets.

Parameters:

building_geometry (pd.Series) – A series containing the geometries of buildings.
n_jobs (int) – The number of CPU cores to use for parallel processing. Defaults to -1, which uses all available cores. If set to a value less than 1, it defaults to 1 core.

Returns:

A DataFrame where each row corresponds to a building and contains lists of wall angles, directions, and lengths.

Return type:

pd.DataFrame

Raises:

TypeError – If the input is not a GeoPandas GeoSeries or cannot be converted to one.

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]

Optimized conversion of a NumPy array to a binary string of packed big-endian integers.

This version uses NumPy’s vectorized astype and tobytes methods for efficiency.

Parameters:

raster_to_numpy (np.ndarray) – Input NumPy array (presumably 3D). Assumes numeric values that can be represented as int32. Floats will be truncated towards zero. NaNs will cause an error.

Returns:

Binary string containing packed data in C-contiguous order.

Return type:

bytes

Raises:

TypeError – If input is not a NumPy array.
ValueError – If input contains NaN or values incompatible with int32 conversion.

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, binary_output_directory: str = '') → Series[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.
binary_output_directory (str) – Full path to the directory to write the binary file to.

naturf.output.write_index(raster_to_numpy: ndarray, building_geometry: Series, target_crs: CRS, index_filename: str = 'index') → Series[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.