Updated documentation as per new feature

docs/04_Core_Scripts.md

@@ -251,7 +251,15 @@ The parameter that needs to be specified under the `OBM_buildings_per_cell` sect
 
 ## What the code does:
 
-This script processes the OBM buildings and assigns them building structural classes as per the SERA model. This script goes by cell, the list of cells being defined either by means of a bounding box, country, administrative unit within a country, or arbitrary list, as specified in the configuration file under `Cells to Process`. All the OBM buildings belonging to a cell are retrieved from the OBM PSQL database in the form of a Pandas DataFrame. A simple function assigns the broad occupancy case (Res, Com, Ind, Other) to each building, based on a dictionary that groups the possible values of gem_occupancy in the PSQL database into these broad cases, as specified in the configuration file under `Ocuppancy String Groups`. Then the code goes by each of the four occupancy cass. If there are OBM buildings of this occupancy case in this cell, the code generates the corresponding HDF5 file. Buildings are sub-grouped within the cell file per administrative unit. For Res, Com, Ind, the code retrieves the corresponding distribution of SERA classes (if SERA is defined for the cell), and narrows it down based on the number of storeys if available. 
+This script processes the OBM buildings and assigns them building structural classes as per the SERA model. This script goes by cell, the list of cells being defined either by means of a bounding box, country, administrative unit within a country, or arbitrary list, as specified in the configuration file under `Cells to Process`. All the OBM buildings belonging to a cell are retrieved from the OBM PSQL database in the form of a Pandas DataFrame. A simple function assigns the broad occupancy case (Res, Com, Ind, Other) to each building, based on a dictionary that groups the possible values of gem_occupancy in the PSQL database into these broad cases, as specified in the configuration file under `Ocuppancy String Groups`. Then the code goes by each of the four occupancy cass. If there are OBM buildings of this occupancy case in this cell, the code generates the corresponding HDF5 file. Buildings are sub-grouped within the cell file per administrative unit. For Res, Com, Ind, the code retrieves the corresponding distribution of SERA classes (if SERA is defined for the cell), and narrows it down based on the number of storeys if available. For the specific case of commercial occupancy, the distribution of SERA classes is narrowed down as well based on the specific occupancy class, as per the following table:
+
+
+| OCCUPANCY_TYPE | Meaning | OBM Occupancies |
+| ------ | ------ | ------ |
+| Hotels | hotels and restaurants | RES3, COM5 |
+| Offices | offices | COM3 |
+| Trade | wholesale and retail trade | COM1, COM2 |
+
 
 The output of this code is the OBM Buildings HDF5 Files. Each HDF5 file corresponds to one particular cell and one particular occupancy case (Res, Com, Ind, Oth). The file is not created if there are no OBM buildings for a particular cell and occupancy case. The structure of the files is:
 
@@ -261,10 +269,10 @@ The attributes `lon` and `lat` correspond to the centroid of the building. The `
 
 If the building is classified as "Oth", then no SERA-dependent administrative unit can be assigned to the building and only the `country_iso_2` string is used in the HDF5 file. This can happen as well for Res, Com or Ind buildings whose centroids fall outside of the boundaries of the administrative units according to the available boundary shapefiles.
 
-When the number of storeys is not available (=UNK), the proportions of SERA building classes assigned to the building are exactly those from SERA associated with this cell ID and administrative unit. When the number of storeys is available, only those SERA classes compatible with the number of storeys are retained. Important observations/decisions:
+When the number of storeys is not available (=UNK), the proportions of SERA building classes assigned to the building are exactly those from SERA associated with this cell ID and administrative unit. When the number of storeys is available, only those SERA classes compatible with the number of storeys are retained. The same happens with the narrowing down based on commercial occupancy classes. Important observations/decisions:
 - Cases have been identified in which the number of storeys in OBM was zero. Such cases are taken as equivalent to unknown. However, the code still writes “0” in the HDF5 file.
 - Cases have been identified in which the number of storeys in OBM was not an integer. For this reason, the ceiling of the float is taken as the number of storeys, so that, for example, 4.5 gets interpreted as 5 storeys. This is, a priori, a conservative assumption, as buildings with larger number of storeys tend to be more vulnerable. However, this may not always be the case, as it may lead to narrowing down the possible building classes in a way that leads to lower vulnerability (e.g. if assuming 5 storeys leads only to well-designed reinforced concrete buildings but assuming 4 storeys would lead to considering concrete buildings designed only for gravitational loads too).
-- Cases have been identified in which the number of storeys in OBM led to no SERA building class being eligible. In those cases, no classes are assigned and the building is treated as “OBM without SERA classes”, which means that it is not included in the GDE export for OpenQuake. When this occurs, the flag `Sto_SERA_inconsist_criterion` is set to True to indicate that there is an inconsistency between the number of storeys reported in OBM and the classes defined in the SERA model (otherwise the flag is False). This approach might be changed in the future, for example, by assigning the classes with the closest number of storeys or similar strategies. 
+- Cases have been identified in which the number of storeys and/or the commercial occupancy class in OBM led to no SERA building class being eligible. In those cases, no classes are assigned and the building is treated as “OBM without SERA classes”, which means that it is not included in the GDE export for OpenQuake. When this occurs, the flag `Sto_SERA_inconsist_criterion` is set to True to indicate that there is an inconsistency between the number of storeys reported in OBM and the classes defined in the SERA model (otherwise the flag is False). This approach might be changed in the future, for example, by assigning the classes with the closest number of storeys or similar strategies. 
 
 
 # GDE_gather_SERA_and_OBM.py