Library

add_building_stock_year!(mod::Module)

Add the building_stock_year parameter for the building_stock objects in mod.

Currently, the building_stock_year is parsed from the name of the building_stock objects, assuming the names are formatted like <NAME>_<YEAR>.

calculate_structure_properties(
    source::Object,
    structure::Object;
    thermal_conductivity_weight::Float64,
    interior_node_depth::Float64,
    variation_period::Float64,
    mod::Module = @__MODULE__,
)

Calculate the properties of (source, structure) from mod based on the raw structural data.

This function calculates the following properties for each (source, structure):

1. U-value [W/m2K] from the interior into the structure itself.
2. U-value [W/m2K] from the structure into exterior air.
3. U-value [W/m2K] from the structure into ground.
4. Total U-value [W/m2K] through the structure from interior to exterior (mainly for cross-referencing purposes).
5. Effective thermal mass [J/m2K] of the structure (calculated from layers inside the primary insulation).

Note that for internal structure types, all structural layers are included in the effective thermal mass!

The U-values are calculated as the inverse of the total thermal resistance of the structural layers:

\[U = R_{\text{total}}^{-1} = \left( \sum_{l \in \text{layers}} R_{l} \right)^{-1}\]

The zeroth layer is considered as the boundary between internal layers and external layers, and contains the primary thermal insulation layer for envelope structures. As such, half of the zeroth layer is considered as an internal layer, and the other half as an external layer.

If a structure contains an exterior finish or crawl space layer, the U-value to the exterior air will be calculated until that layer. If a structure contains the ground layer, the U-value to the ground will be calculated until that layer. If a structure contains both (e.g. base floors with crawl spaces), both U-values will be calculated separately, and the total U-value will be calculated based on them, as if they were parallel thermal resistances.

All the above parameters are calculated separately for the non-load-bearing and load-bearing variants of the structure.

The keywords can be used to tweak material properties between their min and max values, the assumed "depth" of the temperature node, and the "period of variations" as explained in EN ISO 13786:2017.

Essentially, this function performs the following steps:

1. Linearly interpolate the thermal resistance of ventilation spaces based on the raw input data.
2. Calculate the properties of the structural layers using layers_with_properties.
3. Check if the structure can be load-bearing using isloadbearing.
4. Calculate the total effective thermal mass of the structure by summing the effective thermal mass of the interior layers.
5. Call account_for_surface_resistance_in_effective_thermal_mass! with the assumed variation_period.
6. Call calculate_ground_resistance_m2K_W using the method by Kissock et al. 2013.
7. Calculate the thermal resistances for the different parts of the structure, accounting for surface resistances and the assumed interior_node_depth.
8. Calculate the final U-values for the different parts of the structure based on the above thermal resistances.

create_building_stock_statistics!(
    mod::Module;
    building_stock=anything,
    building_type=anything,
    building_period=anything,
    location_id=anything,
    heat_source=anything,
)

Create the building_stock_statistics RelationshipClass in mod to house the building stock forecasts.

Based on the building_stock__building_type__building_period__location_id__heat_source relationship, but with some renaming to make the data more flexible. Furthermore, includes the average_floor_area_m2 data as well. Optional keyword arguments can be used to limit the scope of the calculations, and the mod keyword is used to tweak the Module scope of the calculations.

Essentially, performs the following steps:

1. Include the filtered building_stock__building_type__building_period__location_id__heat_source raw input data relationships.
2. Merge the filtered_parameter_values with the _average_gross_floor_area_m2_per_building_values for the relationships.
3. Set an empty default value for average_gross_floor_area_m2_per_building.
4. Create the SpineInterface Parameters for number_of_buildings and average_gross_floor_area_m2_per_building.
5. Evaluate building_stock_statistics and the associated parameters into the desired mod.

NOTE! Due to lacking input data, the average gross floor area per building is assumed independent of building_stock and heat_source.

create_processed_statistics!(
    mod::Module,
    num_lids::Float64,
    thermal_conductivity_weight::Float64,
    interior_node_depth::Float64,
    variation_period::Float64,
)

Create processed statistics in mod based on the contents of the input datastore.

The arguments are used to tweak details regarding the processing:

• num_lids: Number of location_id objects included in the resulting datastore (e.g. for testing).
• thermal_conductivity_weight: How thermal conductivity of the materials is sampled.
• interior_node_depth: How deep the interior thermal node is positioned within the structure.
• variation_period: "Period of variations" as defined in EN ISO 13786:2017 Annex C.

Essentially performs the following steps:

1. Limit location_ids based on the given num_lids.
2. Call add_building_stock_year! to parse years from building_stock names.
3. Call create_building_stock_statistics! to create processed building stock statistics.
4. Call create_structure_statistics! to create processed structural statistics.
5. Call create_ventilation_and_fenestration_statistics! to create processed ventilation and fenestration statistics.

create_structure_statistics!(
    mod::Module;
    building_type=anything,
    building_period=anything,
    location_id=anything,
    thermal_conductivity_weight::Float64,
    interior_node_depth::Float64,
    variation_period::Float64,
)

Create the structure_statistics RelationshipClass to house the structural data from mod.

The keywords can be used to filter produced data, as well as tweak how the different material properties are weighted: 0 uses the minimum values, and 1 uses the maximum values. interior_node_depth is used to calculate the thermal resistance into the structure node, and variation_period affects the effective thermal mass accounting for surface resistance.

Essentially, this function performs the following steps:

1. Creates the is_load_bearing parameter via _add_light_wall_types_and_is_load_bearing!
2. Forms all BuildingStructures using _form_building_structures
3. Creates and returns the structure_statistics RelationshipClass, with its parameters calculated using _structure_type_parameter_values

The RelationshipClass stores the following structural parameters:

• effective_thermal_mass_J_m2K: Effective thermal mass of the structure.
• linear_thermal_bridges_W_mK: Linear thermal bridges of the structure.
• design_U_value_W_m2K: Design U-value of the structure, based on U-values in the input data, and used mainly as a reference for total_U_value_W_m2K.
• total_U_value_W_m2K: Estimated total U-value through the structure, accounting for both ambient air and ground interaction. Used mainly as a comparison against design_U_value_W_m2K.
• external_U_value_to_ambient_air_W_m2K: U-value portion from inside the structure into ambient air.
• external_U_value_to_ground_W_m2K: U-value portion from inside the structure into the ground.
• internal_U_value_to_structure_W_m2K: U-value portion from the interior air into the structure.

create_ventilation_and_fenestration_statistics!(
    mod::Module;
    building_type=anything,
    location_id=anything,
    building_period=anything,
    ventilation_rate_weight::Float64=0.5,
    n50_infiltration_rate_weight::Float64=0.5,
    infiltration_factor_weight::Float64=0.5,
    HRU_efficiency_weight::Float64=0.5,
    lookback_if_empty::Int64=10,
    max_lookbacks::Int64=20,
)

Create the ventilation_and_fenestration_statistics RelationshipClass to house ventilation and fenestration data from mod.

The ObjectClass keywords can be used to filter the processed data, while the weight keywords can be used to tweak how the properties are sampled: 0 uses the minimum value, and 1 uses the maximum value. The lookback keywords control how historical data is backtracked if no data is found for a building_period.

The RelationshipClass stores the following ventilation and fenestration parameters:

• ventilation_rate_1_h: Calculated using mean_ventilation_rate
• infiltration_rate_1_h: Calculated using mean_infiltration_rate
• HRU_efficiency: Calculated using mean_hru_efficiency
• window_U_value_W_m2K: Calculated using mean_window_U_value
• total_normal_solar_energy_transmittance: Calculated using mean_total_normal_solar_energy_transmittance

data_from_package(filepaths::String...)

Read and form FinnishBuildingStockData.RawSpineData from Data Packages at filepaths.

data_from_url(urls::String...; upgrade=false, filters=Dict())

Read and form FinnishBuildingStockData.RawSpineData from Spine Datastores at urls.

filter_entity_class!(oc::ObjectClass; kwargs...)

Filters and ObjectClass or a RelationshipClass to only contain the desired objects or relationships. Separate methods for ObjectClass and RelationshipClass.

import_processed_data(
    url_out::String;
    scramble_data = false,
    mod::Module = @__MODULE__,
    fields::Vector{Symbol}=[
        :building_period,
        :building_stock,
        :building_type,
        :heat_source,
        :location_id,
        :structure_type,
        :building_stock_statistics,
        :structure_statistics,
        :ventilation_and_fenestration_statistics
    ]
)

Imports the processed data from module mod into the datastore at url_out.

The mod keyword can be used to tweak which Module the data is accessed from. The scramble_data keyword can be used to scramble the database if needed. The fields keyword can be used to control which object and relationship classes are imported into the desired url.

layers_with_properties(
    source::Object,
    structure::Object,
    R_itp::Interpolations.Extrapolation;
    thermal_conductivity_weight::Float64
    mod::Module = @__MODULE__,
)

Calculate the properties of the structural layers while combining overlapping layers.

Returns an array of unique structure_materials for the load-bearing layers, as well as an array of the processed PropertyLayers. The keywords can be used to tweak material properties between their min and max values, while the mod keyword defines the Module from which the data is accessed.

Essentially, this function performs the following steps:

1. Order and create the Layers in the structure using order_layers.
2. Identify the load bearing materials.
3. Identify whether the structure is ground-coupled or not.
4. Calculate the layer properties using layer_thermal_resistance and layer_heat_capacity.
5. Create the final array of PropertyLayers using the calculated layer properties.

run_structural_tests(; limit::Number = Inf, mod::Module = @__MODULE__)

Run all structural data tests for Module mod.

Note that you must first open a database via using_spinedb(db_url, mod)!

Essentially, this function scans through the structural input data and ensures that there are no missing values or values of the incorrect type. For some parameters, the tests also check whether the given values are reasonable, in an attempt to avoid blatant input data mistakes.

run_statistical_tests(;limit::Number=Inf, mod::Module = @__MODULE__)

Run all statistical data tests for Module mod.

Note that you must first open a database via using_spinedb(db_url, mod).

Essentially, this function scans through the statistical input data and ensures that there are no missing values or values of the incorrect type. For some parameters, the tests also check whether the given values are reasonable, in an attempt to avoid blatant input data mistakes.

scramble_parameter_data!(oc::ObjectClass)

Scrambles all parameter data in an object or relationship class. Methods are provided for object and relationship classes separately.

BuildingStructure

A struct representing a structure with all its important properties.

Contains the following fields:

1. name::Symbol: Name of the structure, combined from the source and structure identifiers.
2. type::Object: The type of the structure, e.g. exterior_wall, roof, or light_partition_wall.
3. year::Float64: Year of the source including this structure, after which the structure is assumed to be in use.
4. internal::Bool: A flag indicating whether the structure is an internal structure, as opposed to envelope structures.
5. loadbearing::Bool A flag indicating whether the structure can be load-bearing.
6. load_bearing_materials::Array{Object,1}: An array of the load-bearing materials used in this structure.
7. design_U_value::Property: The original design U-value [W/m2K] of the structure in the raw input data.
8. U_value_dict::Dict{Symbol,Property}: Holds all the different U-values [W/m2K] between the ambient, structural, and interior air nodes.
9. effective_thermal_mass::Property: Effective thermal mass of the structure [J/m2K].
10. linear_thermal_bridges::Property: Linear thermal bridges [W/mK] of the structure based on raw input data.
11. building_types::Array{Object,1}: List of building_types employing this structure.

The constructor essentially performs the following steps:

1. Define the name, type, year, internal, design_U_value, linear_thermal_bridges, and building_types based on raw input data.
2. Determine the loadbearing, load_bearing_materials, effective_thermal_mass, and U_value_dict via the calculate_structure_properties function.
3. Create the final BuildingStructure.

Layer

A struct representing a structural layer.

Contains the following fields:

• number::Int: Indicates the depth of the layer within the structure. Negative values indicate layers inside the primary thermal insulation layer, 0 indicates the primary thermal insulation layer, and positive values indicate layers outside the primary insulation layer.
• tag::Symbol: A tag explaining the purpose of each layer.
• id::Object: Unique identifier for each structural layer.
• material::Object: The material of the structural layer.

Property

A convenience struct handling minimum and load-bearing properties of structural layers.

Contains the following fields:

• min::Real: The minimum property of the structural layer when it is non-load-bearing.
• loadbering::Real: The minimum load-bearing when it is load-bearing.

PropertyLayer

A struct storing the Propertys of structural layers, used for calculations.

Contains the following fields:

• number::Int: Indicates the depth of the layer within the structure. Negative values indicate layers inside the primary thermal insulation layer, 0 indicates the primary thermal insulation layer, and positive values indicate layers outside the primary insulation layer.
• R::Property: The thermal resistance of the structural layer in [m2K/W], both for load-bearing and non-load-bearing variants of the layer.
• C::Property: The heat capacity of the structural layer in [J/m2K], both for load-bearing and non-load-bearing variants of the layer.
• interior::Bool: A flag whether this layer lies between the interior surface and the primary thermal insulation layer of the structure.
• exterior::Bool: A flag whether this layer lies between the exterior surface and the primary thermal insulation layer of the structure.
• ground::Bool: A flag whether this layer lies between the ground and the primary thermal insulation layer of the structure.

RawSpineData

A struct for holding the raw Spine Datastore contents.

Follows the raw JSON formatting of Spine Datastores, with the following fields:

• object_classes::Vector
• object_classes::Vector
• objects::Vector
• object_parameters::Vector
• object_parameter_values::Vector
• relationship_classes::Vector
• relationships::Vector
• relationship_parameters::Vector
• relationship_parameter_values::Vector
• alternatives::Vector
• parameter_value_lists::Vector

_add_light_wall_types_and_is_load_bearing!(mod::Module)

Add new structure_types for non-load-bearing exterior and partition walls, as well as a new parameter is_load_bearing for whether the structure type is load-bearing.

Note that this function operates in Module mod!

Essentially, all the structure types in the raw data are assumed to be load-bearing. This function creates the light_exterior_wall and light_partition_wall structure_types assuming identical properties to their load-bearing counterparts, except that the :is_load_bearing flag is set to false.

_average_gross_floor_area_m2_per_building_values(;
    building_stock=anything,
    building_type=anything,
    building_period=anything,
    location_id=anything,
    heat_source=anything,
    mod::Module = @__MODULE__
)

Create the average_gross_floor_area_m2_per_building parameter values for the building_stock_statistics RelationshipClass.

Essentially, this function loops over all (building_stock, building_type, building_period, location_id, heat_source) in the data, and fetches the corresponding average_floor_area_m2(building_type, location_id, building_period) data. The calculations can be limited to only the desired object classes by using the optional keyword arguments, and the mod keyword is used to tweak the Module scope of the calculations.

_check(cond::Bool, msg::String)

Check the condition cond, and print msg if false.

_filter_relevant_building_structures(
    building_structures::Array{BuildingStructure,1},
    building_type::Object,
    building_period::Object,
    structure_type::Object,
    st_map::Dict;
    lookback_if_empty::Int64 = 10,
    max_lookbacks::Int64 = 20,
    mod::Module = @__MODULE__,
)

Find the BuildingStructures matching the provided criteria from data in mod.

Essentially, this function returns a filtered Array of BuildingStructures, that match the desired structure_type, building_type, and building_period. If nothing is found, relaxes the building_period period_start by lookback_if_empty = 10 and tries again. If nothing is found after max_lookbacks = 20, throws an error.

_filter_relevant_sources(
    building_period::Object,
    relationship_class::SpineInterface.RelationshipClass;
    lookback_if_empty::Int64 = 10,
    max_lookbacks::Int64 = 20;
    mod::Module = @__MODULE__
)

Finds the sources matching the provided building_period for the desired relationship_class.

If nothing is found, relaxes the building_period start by lookback_if_empty, and tries again until max_lookbacks is reached. The mod keyword defines the Module from which the data is accessed.

_form_building_structures(;
    thermal_conductivity_weight::Float64,
    interior_node_depth::Float64,
    variation_period::Float64,
    mod::Module = @__MODULE__,
)

Forms the BuildingStructure for each structure in Module mod.

Essentially, loops over each (source, structure) in the raw input data, and creates a corresponding BuildingStructure using the desired properties. The keywords can be used to tweak material properties between their min and max values. Note that only structures with total_building_type_weight greater than zero are handled to avoid unnecessary calculations.

_get(oc::ObjectClass, name::Symbol)

Helper function to fetch existing object of class oc and create it if missing.

_import_oc!(
    rsd::RawSpineData,
    df::DataFrame,
    oc::Symbol,
    stackrange::UnitRange{Int64},
    params::Vector{Symbol}
)

Helper function for generic ObjectClass imports.

The stackrange can be used to manipulate the DataFrame shape prior to extracting the object class, while params is used to read parameter values if any. Both can be omitted if not needed.

_import_rc!(
    rsd::RawSpineData,
    df::DataFrame,
    rc::Symbol,
    stackname::Symbol,
    stackrange::UnitRange{Int64},
    rename_value::Symbol,
    params::Vector{Symbol};
    object_classes::Vector{Symbol}=Symbol.(split(String(rc), "__"))
)

Helper function for generic RelationshipClass imports.

stackname, stackrange, and rename_value can be used to manipulate the DataFrame shape prior to extracting the relationship class, while params is used to read parameter values if any. object_classes can be used to set RelationshipClass dimensions manually. These can be omitted if not needed.

_map_structure_types(
    is_load_bearing::SpineInterface.Parameter;
    mod::Module = @__MODULE__,
)

Maps structure_type to its load-bearing variant. Only light structures are affected.

Note that this function operates in Module mod, set to @__MODULE__ by default!

Essentially, returns a Dict mapping each structure_type to itself, with the exception of the light_exterior_wall and light_partition_wall being mapped to exterior_wall and partition_wall repsectively.

_merge_data!(rsd1::RawSpineData, rsds::RawSpineData ...)

Helper function for merging FinnishBuildingStockData.RawSpineData.

_relationship_and_unique_entries(relationship::SpineInterface.RelationshipClass, fields::Symbol)

Gets the unique entries in the relationship with the desired fields.

Returns a Pair with the name of the relationship as a String, and the entries in an Array.

_relationship_and_unique_entries(relationship::SpineInterface.RelationshipClass, fields::NTuple{N Symbol})

Gets the unique entries in the relationship with the desired fields.

Returns a Pair with the name of the relationship as a String, and the entries in an Array.

_scramble_parameter_value(val::SpineInterface.ParameterValue)

Scramble the values of a ParameterValue.

_scramble_value(val)

Scramble a value. Different methods are employed for different types encountered. If a method isn't specified, the value is simply omitted entirely.

_structure_type_parameter_values(
    building_structures::Array{BuildingStructure,1},
    inds::NamedTuple,
    is_load_bearing::SpineInterface.Parameter;
    mod::Module = @__MODULE__,
)

Aggregate the building_structures parameters from mod into a parameter value Dict.

NOTE! The share parameter is never allowed to be zero, with a 1e-6 always added to the share. Adding 1e-6 to the share means that an even mix of materials is assumed if no meaningful data is found.

Essentially, this function performs the following steps:

1. Maps structure_type into its load-bearing variant via _map_structure_types.
2. Filters out irrelevant structures based in inds using _filter_relevant_building_structures.
3. Calculates the normalized weights of the relevant structures based on the (building_type, location_id, frame_material) frame material share data.
4. Calculates the aggregated average properties of the relevant structures, weighted using the normalized frame material weights.

Yielding the following weighted average structural parameters:

• effective_thermal_mass_J_m2K: Effective thermal mass of the structure.
• linear_thermal_bridges_W_mK: Linear thermal bridges of the structure.
• design_U_value_W_m2K: Design U-value of the structure, based on U-values in the input data, and used mainly as a reference for total_U_value_W_m2K.
• total_U_value_W_m2K: Estimated total U-value through the structure, accounting for both ambient air and ground interaction. Used mainly as a comparison against design_U_value_W_m2K.
• external_U_value_to_ambient_air_W_m2K: U-value portion from inside the structure into ambient air.
• external_U_value_to_ground_W_m2K: U-value portion from inside the structure into the ground.
• internal_U_value_to_structure_W_m2K: U-value portion from the interior air into the structure.

_thermal_resistance(
    source::Object,
    structure::Object,
    layer::Layer,
    thickness::SpineInterface.Parameter,
    R_itp::Interpolations.Extrapolation;
    weight::Float64 = 0.5,
    mod::Module = @__MODULE__,
)

Calculate the thermal resistance [W/m2K] of a single homogeneous structural layer.

For regular material layers, the thermal resistance is calculated as:

\[R = \frac{\textit{thickness}}{\textit{thermal conductivity}}\]

but for layers with ventilation space as the material, linearly interpolated tabulated values from the raw input data are used instead. The weight keyword can be used to tweak the thermal conductivity of the materials between their min and max values.

account_for_surface_resistance_in_effective_thermal_mass!(
    C::Property,
    surface_resistance::Float64,
    variation_period::Float64
)

Account for the surface_resistance and the assumed variation_period ("period of the variations").

The effective thermal mass is calculated according to EN ISO 13786:2017 Annex C.2.4 Effective thickness method. When used for a Property, calculates the effective thermal mass separately for both min and loadbearing values.

calculate_ground_resistance_m2K_W(Rf::Float64, Rp::Float64)

Calculate the effective ground thermal resistance [m2K/W].

\[R_g = \left( \frac{0.114}{0.7044 + R_f + R_p} + \frac{0.8768}{2.818 + R_f} \right)^{-1}\]

The calculation is based on the simple method proposed by K.Kissock in: Simplified Model for Ground Heat Transfer from Slab-on-Grade Buildings, (c) 2013 ASHRAE, where:

• Rf stands for the total thermal resistance of the floor structures.
• Rp stands for the additional ground perimeter insulation thermal resistance (assumed 0 since no data).

Note that the correction factor C can only be taken into account later on, when the dimensions of the building are known!

density(material::Object; mod::Module = @__MODULE__)

Return the average density of the material in [kg/m3].

Calculated as a simple average based on the minimum_density_kg_m3 and maximum_density_kg_m3 parameters in the input data as

\[\rho_{\text{mean}} = \frac{\rho_{\text{min}} + \rho_{\text{max}}}{2}\]

The mod keyword is used to tweak the Module from which the parameters are read.

filtered_parameter_values(oc::ObjectClass; kwargs...)

Filters the parameter_values field of an ObjectClass or a RelationshipClass. Methods for the entitity classes are provided separately.

import_building_period!(
    rsd::RawSpineData,
    dp::Dict{String,DataFrame}
)

Import the building_period object class from dp.

import_building_stock!(
    rsd::RawSpineData,
    dp::Dict{String,DataFrame}
)

Import building_stock ObjectClass from dp.

import_building_stock__building_type__building_period__location_id__heat_source!(
    rsd::RawSpineData,
    dp::Dict{String,DataFrame}
)

Import the desired relationship class.

import_building_type!(
    rsd::RawSpineData,
    dp::Dict{String,DataFrame}
)

Import building_type ObjectClass from dp.

import_building_type__location_id__building_period!(
    rsd::RawSpineData,
    dp::Dict{String,DataFrame}
)

Import the desired relationship class.

import_building_type__location_id__frame_material!(
    rsd::RawSpineData,
    dp::Dict{String,DataFrame}
)

Import the desired relationship class.

import_datapackage!(
    rsd::RawSpineData,
    dp::Dict{String,DataFrame}
)

import_fenestration_source__building_type!(
    rsd::RawSpineData,
    dp::Dict{String,DataFrame}
)

Import the desired relationship class.

import_frame_material!(
    rsd::RawSpineData,
    dp::Dict{String,DataFrame}
)

Import frame_material ObjectClass from dp.

import_heat_source!(
    rsd::RawSpineData,
    dp::Dict{String,DataFrame}
)

Import heat_source ObjectClass from dp.

import_layer_id!(
    rsd::RawSpineData,
    dp::Dict{String,DataFrame}
)

Import layer_id ObjectClass from dp.

import_location_id!(
    rsd::RawSpineData,
    dp::Dict{String,DataFrame}
)

Import location_id ObjectClass from dp.

import_source!(
    rsd::RawSpineData,
    dp::Dict{String,DataFrame}
)

Import source ObjectClass from dp.

import_source__structure!(
    rsd::RawSpineData,
    dp::Dict{String,DataFrame}
)

Import the desired relationship class.

import_source__structure__building_type!(
    rsd::RawSpineData,
    dp::Dict{String,DataFrame}
)

Import the desired relationship class.

import_source__structure__layer_id__structure_material!(
    rsd::RawSpineData,
    dp::Dict{String,DataFrame}
)

Import the desired relationship class.

import_statistical_datapackage!(
    rsd::RawSpineData,
    dp::Dict{String,DataFrame}
)

Imports a statistical datapackage into a FinnishBuildingStockData.RawSpineData.

import_structural_datapackage!(
    rsd::RawSpineData,
    dp::Dict{String,DataFrame}
)

Imports a structural datapackage into a FinnishBuildingStockData.RawSpineData struct.

import_structure!(
    rsd::RawSpineData,
    dp::Dict{String,DataFrame}
)

Import structure ObjectClass from dp.

import_structure_material!(
    rsd::RawSpineData,
    dp::Dict{String,DataFrame}
)

Import structure_material ObjectClass from dp.

import_structure_material__frame_material!(
    rsd::RawSpineData,
    dp::Dict{String,DataFrame}
)

Import the desired relationship class.

import_structure__structure_type!(
    rsd::RawSpineData,
    dp::Dict{String,DataFrame}
)

Import the desired relationship class.

import_structure_type!(
    rsd::RawSpineData,
    dp::Dict{String,DataFrame}
)

Import structure_type ObjectClass from dp.

import_structure_type__ventilation_space_heat_flow_direction!(
    rsd::RawSpineData,
    dp::Dict{String,DataFrame}
)

Import the desired relationship class.

import_ventilation_source__building_type!(
    rsd::RawSpineData,
    dp::Dict{String,DataFrame}
)

Import the desired relationship class.

import_ventilation_space_heat_flow_direction!(
    rsd::RawSpineData,
    dp::Dict{String,DataFrame}
)

Import ventilation_space_heat_flow_direction ObjectClass from dp.

isloadbearing(source::Object, structure::Object; mod::Module = @__MODULE__)

Check if structure from mod can be load-bearing and return a Bool.

A structure is interpreted as potentially load-bearing if any of its layers has a layer_load_bearing_thickness_mm value in the raw input data.

layer_heat_capacity(
    source::Object,
    structure::Object,
    layers::Array{Layer,1};
    mod::Module = @__MODULE__
)

Calculate the effective heat capacity [J/m2K] of a potentially heterogeneous structural layer as:

\[C = \sum_{i \in \text{overlapping}} \textit{layer weight}(i) * \textit{specific heat capacity}(i) * \textit{density}(i) * \textit{thickness}(i)\]

Returns a Property with the effective heat capacity for the minimum thickness min, and the effective heat capacity for the load-bearing thickness loadbearing. The thermal capacity is assumed to be zero if it cannot be calculated using the parameters (e.g. when thickness is zero). The mod keyword defines the Module from which the data is accessed.

layer_number_weight(layer::Union{Layer,PropertyLayer})

Returns 0.5 if layer.num == 0, otherwise returns 1.

layer_thermal_resistance(
    source::Object,
    structure::Object,
    layers::Array{Layer,1},
    R_itp::Interpolations.Extrapolation;
    weight::Float64 = 0.5
    mod::Module = @__MODULE__
)

Calculate the thermal resistance [m2K/W] of a potentially heterogeneous structural layer as:

\[R = \left(\sum_{i \in \text{overlapping}} \frac{\textit{layer weight}(i)*\textit{thermal conductivity}(i)}{\textit{thickness}(i)} \right)^{-1}\]

Returns a Property with the thermal resistance for the minimum thickness min, and the thermal resistance for the load-bearing thickness loadbearing. The thermal resistance is assumed to be zero if it cannot be calculated using the parameters (e.g. when thickess is zero). The weight keyword can be used to tweak the thermal conductivity of the materials between their min and max values. The mod keyword defines the Module from which the data is accessed.

mean_hru_efficiency(
    building_period::Object,
    building_type::Object;
    weight::Float64=0.5,
    lookback_if_empty::Int64 = 10,
    max_lookbacks::Int64 = 20,
    mod::Module = @__MODULE__,
)

Calculate the mean Heat Recovery Unit (HRU) efficiency for a (building_period, building_type) based on relevant raw data.

The weight keyword can be used to tweak how the HRU efficiency is sampled: 0 uses the min_HRU_efficiency, and 1 uses the max_HRU_efficiency. The lookback keywords control how historical data is backtracked if no data is found for a building_period. The mod keyword defines the Module from which the data is accessed.

Essentially, this function performs the following steps:

1. Filter out irrelevant sources using _filter_relevant_sources.
2. Calculate the mean HRU efficiency across the relevant sources as:

\[\eta_{\text{mean}} = \frac{\sum_{s \in \text{relevant sources}} w \eta_{\text{max,s}} + (1-w) \eta_{\text{min,s}}}{\sum_{s \in \text{relevant sources}} 1} \]

mean_infiltration_rate(
    building_period::Object,
    building_type::Object;
    n50_weight::Float64=0.5,
    factor_weight::Float64=0.5,
    lookback_if_empty::Int64 = 10,
    max_lookbacks::Int64 = 20,
    mod::Module = @__MODULE__,
)

Calculate the mean infiltration rate [1/h] for a (building_period, building_type) based on relevant raw data.

The weight keywords can be used to tweak how the infiltration rate and infiltration factor are sampled: 0 uses the minimum, and 1 uses the maximum parameter values. The lookback keywords control how historical data is backtracked if no data is found for a building_period. The mod keyword defines the Module from which the data is accessed.

NOTE! The calculation of the infiltration factor is based on the convention in the Finnish building code. The convention uses a n50 infiltration rate corrected using an infiltration factor accounting for the typical number of storeys in the building type in question.

Essentially, this function performs the following steps:

1. Filter out irrelevant sources using _filter_relevant_sources.
2. Calculate the mean infiltration rate [1/h] across the relevant sources as:

\[r_{\text{inf,mean}} = \frac{\sum_{s \in \text{relevant sources}} w_{\text{n50}} r_{\text{inf,max,s}} + (1-w_{\text{n50}}) r_{\text{inf,min,s}}}{\sum_{s \in \text{relevant sources}} \left[ w_{\text{factor}} F_{\text{max}} + (1-w_{\text{factor}}) F_{\text{min}} \right] \sum_{s \in \text{relevant sources}} 1} \]

mean_total_normal_solar_energy_transmittance(
    building_period::Object,
    building_type::Object;
    lookback_if_empty::Int64 = 10,
    max_lookbacks::Int64 = 20,
    mod::Module = @__MODULE__,
)

Calculate the mean total normal solar energy transmittance for a (building_period, building_type) based on raw data. In this case, "total" means that both the properties of glazing and window frames are accounted for, while "normal" means that this value is strictly applicable only to solar radiation directly perpendicular to the window.

The lookback keywords control how historical data is backtracked if no data is found for a building_period. The mod keyword defines the Module from which the data is accessed.

Essentially, this function performs the following steps:

1. Filter out irrelevant sources using _filter_relevant_sources.
2. Calculate the mean total normal solar energy transmittance of the windows across the relevant sources accounting for the frame area fraction as:

\[g_{\text{mean}} = \frac{\sum_{s \in \text{relevant sources}} (1-f) g}{\sum_{s \in \text{relevant sources}} 1} \]

mean_ventilation_rate(
    building_period::Object,
    building_type::Object;
    weight::Float64=0.5,
    lookback_if_empty::Int64 = 10,
    max_lookbacks::Int64 = 20,
    mod::Module = @__MODULE__
)

Calculate the mean ventilation rate [1/h] for a (building_period, building_type) based on relevant raw data.

The weight keyword can be used to tweak how the ventilation rate is sampled: 0 uses the min_ventilation_rate_1_h, and 1 uses the max_ventilation_rate_1_h. The lookback keywords control how historical data is backtracked if no data is found for a building_period. The mod keyword defines the Module from which the data is accessed.

Essentially, this function performs the following steps:

1. Filter out irrelevant sources using _filter_relevant_sources.
2. Calculate the mean ventilation rate [1/h] across the relevant sources as:

\[r_{\text{ven,mean}} = \frac{\sum_{s \in \text{relevant sources}} w r_{\text{ven,max,s}} + (1-w) r_{\text{ven,min,s}}}{\sum_{s \in \text{relevant sources}} 1} \]

mean_window_U_value(
    building_period::Object,
    building_type::Object;
    lookback_if_empty::Int64 = 10,
    max_lookbacks::Int64 = 20,
    mod::Module = @__MODULE__,
)

Calculate the mean window U-value [W/m2K] for a (building_period, building_type) based on relevant raw data.

The lookback keywords control how historical data is backtracked if no data is found for a building_period. The mod keyword defines the Module from which the data is accessed.

Essentially, this function performs the following steps:

1. Filter out irrelevant sources using _filter_relevant_sources.
2. Calculate the mean window U-value [W/m2K] across the relevant sources as:

\[U_{\text{mean}} = \frac{\sum_{s \in \text{relevant sources}} U_{\text{max,s}} + U_{\text{min,s}}}{2 \sum_{s \in \text{relevant sources}} 1} \]

order_layers(source::Object, structure::Object; mod::Module = @__MODULE__)

Order the structural layers of (source, structure) from mod according to the layer_numbers.

Returns an array of Layers, sorted according to the layer_number parameter, as well as the unique array of layer_numbers.

read_datapackage(datpack_path::String)

Read the resources of a Data Package into a dictionary of DataFrames.

specific_heat_capacity(material::Object; mod::Module = @__MODULE__)

Return the average specific heat capacity of the material in [J/kgK].

Calculated as a simple average based on the minimum_specific_heat_capacity_J_kgK and maximum_specific_heat_capacity_J_kgK parameters in the input data as

\[c_{\text{mean}} = \frac{c_{\text{min}} + c_{\text{max}}}{2}\]

The mod keyword is used to tweak the Module from which the parameters are read.

test_building_period(;limit::Number=Inf, mod::Module = @__MODULE__)

Run tests for the building_period objects in Module mod.

test_building_stock(;limit::Number=Inf, mod::Module = @__MODULE__)

Run tests for the building_stock objects in Module mod.

test_building_stock__building_type__building_period__location_id__heat_source(;
    limit::Number=Inf,
    mod::Module = @__MODULE__
)

Run tests for the building_stock__building_type__building_period__location_id__heat_source relationhip.

test_building_type__location_id__building_period(;
    limit::Number=Inf,
    mod::Module = @__MODULE__
)

Run tests for the building_type__location_id__building_period relationship.

test_building_type__location_id__frame_material(;
    limit::Number=Inf,
    mod::Module = @__MODULE__
)

Run tests for the building_type__location_id__frame_material relationship.

test_fenestration_source__building_type(; limit::Number = Inf, mod::Module = @__MODULE__)

Run tests for the fenestration_source__building_type relationships in Module mod.

test_frame_material(;limit::Number=Inf, mod::Module = @__MODULE__)

Runs tests for the frame_material objects in Module mod.

test_heat_source(;limit::Number=Inf, mod::Module = @__MODULE__)

Runs tests for the heat_source objects in Module mod.

test_layer_id(;limit::Number=Inf, mod::Module = @__MODULE__)

Run tests for the layer_id objects in Module mod.

test_location_id(;limit::Number=Inf, mod::Module = @__MODULE__)

Runs tests for the location_id objects in Module mod.

test_source(; limit::Number=Inf, mod::Module = @__MODULE__)

Run tests for the source objects in Module mod.

test_source__structure(; limit::Number = Inf, mod::Module = @__MODULE__)

Run tests for the source__structure relationships in Module mod.

test_source__structure__building_type(; limit::Number = Inf, mod::Module = @__MODULE__)

Run tests for the source__structure__building_type relationships in Module mod.

test_source__structure__layer_id__structure_material(;
    limit::Number = Inf,
    mod::Module = @__MODULE__
)

Run tests for the source__structure__layer_id__structure_material relationship in Module mod.

test_statistical_building_type(;limit::Number=Inf, mod::Module = @__MODULE__)

Runs statistical data tests for the building_type objects in Module mod.

test_structural_building_type(;limit::Number=Inf, mod::Module = @__MODULE__)

Run structural data tests for the building_type objects in Module mod.

 test_structural_frame_material(; limit::Number = Inf, mod::Module = @__MODULE__)

Run structural data tests for the frame_material objects in Module mod.

test_structural_layers(; limit::Number = Inf, mod::Module = @__MODULE__)

Run tests in Module mod to ensure the structural layers are sensible.

Essentially, this means checking that the layer_number are continuous, the zeroth layer_tag is either load-bering structure or thermal insulation, and that the layer_weights sum to ≈ 1 for potentially overlapping layers (meaning those with identical layer_number).

test_structure(; limit::Number = Inf, mod::Module = @__MODULE__)

Tun tests for the structure objects in Module mod.

test_structure__structure_type(; limit::Number = Inf, mod::Module = @__MODULE__)

Run tests for the structure__structure_type relationships in Module mod.

test_structure_material(; limit::Number = Inf, mod::Module = @__MODULE__)

Run tests for the structure_material objects in Module mod.

test_structure_material__frame_material(; limit::Number = Inf, mod::Module = @__MODULE__)

Run tests for the structure_material__frame_material relationships in Module mod.

test_structure_type(; limit::Number = Inf, mod::Module = @__MODULE__)

Run tests for the structure_type objects in Module mod.

test_ventilation_source__building_type(; limit::Number = Inf, mod::Module = @__MODULE__)

Run tests for the ventilation_source__building_type relationships in Module mod.

test_structure_type__ventilation_space_heat_flow_direction(;
    limit::Number = Inf,
    mod::Module = @__MODULE__,
)

Run tests for the structure_type__ventilation_space_heat_flow_direction relationship in Module mod.

test_ventilation_space_heat_flow_direction(;
    limit::Number = Inf,
    mod::Module = @__MODULE__
)

Run tests for the ventilation_space_heat_flow_direction objects in mod.

thermal_conductivity(
    material::Object;
    weight::Float64 = 0.5,
    mod::Module = @__MODULE__
)

Return the average thermal conductivity of the material in [W/mK].

Calculated as a weighted average based on the minimum_thermal_conductivity_W_mK and maximum_thermal_conductivity_W_mK parameters in the input data, where the 0 <= weight <= 1 can be used to tweak the calculation.

\[\lambda_{\text{weighted}} = w \lambda_{\text{max}} + (1-w) \lambda_{\text{min}}\]

The mod keyword is used to tweak the Module from which the parameters are read.

total_building_type_weight(source::Object, structure::Object; mod::Module = @__MODULE__)

Return the total building_type_weight of the structure from mod, 0 if not applicable.