openavmkit.utilities.settings

get_center

get_center(s, gdf=None)

Get the centroid of all the provided parcel geometry

Parameters:

Name	Type	Description	Default
s	dict	Settings dictionary	required
gdf	GeoDataFrame	Parcel geometry	None

Return

tuple[float, float] Centroid of all the parcel geometry

Source code in openavmkit/utilities/settings.py

def get_center(s: dict, gdf: gpd.GeoDataFrame = None) -> tuple[float, float]:
    """
    Get the centroid of all the provided parcel geometry

    Parameters
    ----------
    s : dict
        Settings dictionary
    gdf : gpd.GeoDataFrame
        Parcel geometry

    Return
    ------
    tuple[float, float]
        Centroid of all the parcel geometry
    """
    center: dict | None = s.get("locality", {}).get("center", None)
    if center is not None:
        if "longitude" not in center or "latitude" not in center:
            raise ValueError(
                "Could not find both 'longitude' and 'latitude' in 'settings.locality.center'!"
            )
        latitude = center["latitude"]
        longitude = center["longitude"]
        return longitude, latitude
    elif gdf is not None:
        # calculate the center of the gdf
        centroid = gdf.geometry.unary_union.centroid
        return centroid.x, centroid.y
    else:
        raise ValueError("Could not find locality.center in settings!")

get_data_dictionary

get_data_dictionary(settings)

Get the data dictionary object

Parameters:

Name	Type	Description	Default
settings	dict	Settings dictionary	required

Returns:

Type	Description
dict	The data dictionary for this locality

Source code in openavmkit/utilities/settings.py

def get_data_dictionary(settings: dict):
    """
    Get the data dictionary object

    Parameters
    ----------
    settings : dict
        Settings dictionary

    Returns
    -------
    dict
        The data dictionary for this locality
    """
    return settings.get("data_dictionary", {})

get_fields_boolean

get_fields_boolean(s, df=None, types=None)

Retrieve boolean field names based on settings and optional filters.

Parameters:

Name	Type	Description	Default
s	dict	Settings dictionary containing field configurations.	required
df	DataFrame	DataFrame to filter fields by presence. Defaults to None.	None
types	list[str]	List of field classification types to include (e.g., ["land", "impr", "other"]). Defaults to None, which includes all types.	None

Returns:

Type	Description
list[str]	List of boolean field names matching the specified criteria.

Source code in openavmkit/utilities/settings.py

def get_fields_boolean(
    s: dict,
    df: pd.DataFrame = None,
    types: list[str] = None
) -> list[str]:
    """
    Retrieve boolean field names based on settings and optional filters.

    Parameters
    ----------
    s : dict
        Settings dictionary containing field configurations.
    df : pandas.DataFrame, optional
        DataFrame to filter fields by presence. Defaults to None.
    types : list[str], optional
        List of field classification types to include (e.g., ["land", "impr", "other"]).
        Defaults to None, which includes all types.

    Returns
    -------
    list[str]
        List of boolean field names matching the specified criteria.
    """
    if types is None:
        types = ["land", "impr", "other"]
    bools = []

    # Determine which boolean field to get based on na_handling
    field_type = "boolean"

    if "land" in types:
        bools += s.get("field_classification", {}).get("land", {}).get(field_type, [])
    if "impr" in types:
        bools += s.get("field_classification", {}).get("impr", {}).get(field_type, [])
    if "other" in types:
        bools += s.get("field_classification", {}).get("other", {}).get(field_type, [])

    if df is not None:
        bools = [bool for bool in bools if bool in df]
    return bools

get_fields_categorical

get_fields_categorical(s, df=None, include_boolean=False, types=None)

Retrieve categorical field names based on settings and optional filters.

Parameters:

Name	Type	Description	Default
s	dict	Settings dictionary containing field configurations.	required
df	DataFrame	DataFrame to filter fields by presence. Defaults to None.	None
include_boolean	bool	Whether to include boolean fields in the results or not. Defaults to False.	False
types	list[str]	List of field classification types to include (e.g., ["land", "impr", "other"]). Defaults to None, which includes all types.	None

Returns:

Type	Description
list[str]	List of categorical field names matching the specified criteria.

Source code in openavmkit/utilities/settings.py

def get_fields_categorical(
    s: dict,
    df: pd.DataFrame = None,
    include_boolean: bool = False,
    types: list[str] = None,
):
    """
    Retrieve categorical field names based on settings and optional filters.

    Parameters
    ----------
    s : dict
        Settings dictionary containing field configurations.
    df : pandas.DataFrame, optional
        DataFrame to filter fields by presence. Defaults to None.
    include_boolean : bool, optional
        Whether to include boolean fields in the results or not. Defaults to False.
    types : list[str], optional
        List of field classification types to include (e.g., ["land", "impr", "other"]).
        Defaults to None, which includes all types.

    Returns
    -------
    list[str]
        List of categorical field names matching the specified criteria.
    """
    if types is None:
        types = ["land", "impr", "other"]
    cats = []
    if "land" in types:
        cats += s.get("field_classification", {}).get("land", {}).get("categorical", [])
    if "impr" in types:
        cats += s.get("field_classification", {}).get("impr", {}).get("categorical", [])
    if "other" in types:
        cats += (
            s.get("field_classification", {}).get("other", {}).get("categorical", [])
        )
    if include_boolean:
        if "land" in types:
            cats += s.get("field_classification", {}).get("land", {}).get("boolean", [])
        if "impr" in types:
            cats += s.get("field_classification", {}).get("impr", {}).get("boolean", [])
        if "other" in types:
            cats += (
                s.get("field_classification", {}).get("other", {}).get("boolean", [])
            )
    if df is not None:
        cats = [cat for cat in cats if cat in df]
    return cats

get_fields_date

get_fields_date(s, df)

Get all fields pertaining to dates

Parameters:

Name	Type	Description	Default
s	dict	Settings dictionary	required
df	DataFrame	Your dataset	required

Returns:

Type	Description
list[str]	List of field names pertaining to dates

Source code in openavmkit/utilities/settings.py

def get_fields_date(s: dict, df: pd.DataFrame):
    """
    Get all fields pertaining to dates

    Parameters
    ----------
    s : dict
        Settings dictionary
    df : pd.DataFrame
        Your dataset

    Returns
    -------
    list[str]
        List of field names pertaining to dates
    """

    # TODO: add to this as necessary
    all_date_fields = ["sale_date", "date"]
    date_fields = [field for field in all_date_fields if field in df]
    for field in df:
        if "_date" in field and field not in date_fields:
            date_fields.append(field)

    return date_fields

get_fields_impr

get_fields_impr(s, df=None)

Get all fields in the given dataframe that are classified in settings as pertaining to buildings/improvements.

Parameters:

Name	Type	Description	Default
s	dict	Settings dictionary	required
df	DataFrame	Your dataset	None

Returns:

Type	Description
dict	All fields pertaining to buildings/improvements, organized as a dictionary containing three keys: "categorical": list of categorical fields "numeric": list of numerical fields "boolean": list of boolean fields

Source code in openavmkit/utilities/settings.py

def get_fields_impr(s: dict, df: pd.DataFrame = None):
    """
    Get all fields in the given dataframe that are classified in settings as pertaining to buildings/improvements.

    Parameters
    ----------
    s : dict
        Settings dictionary
    df : pd.DataFrame
        Your dataset

    Returns
    -------
    dict
        All fields pertaining to buildings/improvements, organized as a dictionary containing three keys:

          - "categorical": list of categorical fields
          - "numeric": list of numerical fields
          - "boolean": list of boolean fields
    """
    return _get_fields(s, "impr", df)

get_fields_impr_as_list

get_fields_impr_as_list(s, df=None)

Get all fields in the given dataframe that are classified in settings as pertaining to buildings/improvements.

Parameters:

Name	Type	Description	Default
s	dict	Settings dictionary	required
df	DataFrame	Your dataset	None

Returns:

Type	Description
list	A list of all field names pertaining to buildings/improvements

Source code in openavmkit/utilities/settings.py

def get_fields_impr_as_list(s: dict, df: pd.DataFrame = None):
    """
    Get all fields in the given dataframe that are classified in settings as pertaining to buildings/improvements.

    Parameters
    ----------
    s : dict
        Settings dictionary
    df : pd.DataFrame
        Your dataset

    Returns
    -------
    list
        A list of all field names pertaining to buildings/improvements
    """
    fields = get_fields_impr(s, df)
    return (
        fields.get("categorical", [])
        + fields.get("numeric", [])
        + fields.get("boolean", [])
    )

get_fields_land

get_fields_land(s, df=None)

Get all fields in the given dataframe that are classified in settings as pertaining to land.

Parameters:

Name	Type	Description	Default
s	dict	Settings dictionary	required
df	DataFrame	Your dataset	None

Returns:

Type	Description
dict	All fields pertaining to land, organized as a dictionary containing three keys: "categorical": list of categorical fields "numeric": list of numerical fields "boolean": list of boolean fields

Source code in openavmkit/utilities/settings.py

def get_fields_land(s: dict, df: pd.DataFrame = None):
    """
    Get all fields in the given dataframe that are classified in settings as pertaining to land.

    Parameters
    ----------
    s : dict
        Settings dictionary
    df : pd.DataFrame
        Your dataset

    Returns
    -------
    dict
        All fields pertaining to land, organized as a dictionary containing three keys:

          - "categorical": list of categorical fields
          - "numeric": list of numerical fields
          - "boolean": list of boolean fields
    """
    fields_land = _get_fields(s, "land", df)
    fields_unclassified = _get_unclassified_fields(s, df)

    for field in fields_unclassified:
        if field.startswith("dist_to_") or field.startswith("within_") or field.startswith("proximity_to_") or field.startswith("spatial_lag_"):
            fields_land["numeric"].append(field)

    for key in fields_land:
        # remove duplicates:
        fields_land[key] = list(set(fields_land[key]))

    return fields_land

get_fields_land_as_list

get_fields_land_as_list(s, df=None)

Get all fields in the given dataframe that are classified in settings as pertaining to land.

Parameters:

Name	Type	Description	Default
s	dict	Settings dictionary	required
df	DataFrame	Your dataset	None

Returns:

Type	Description
list	A list of all field names pertaining to land

Source code in openavmkit/utilities/settings.py

def get_fields_land_as_list(s: dict, df: pd.DataFrame = None):
    """
    Get all fields in the given dataframe that are classified in settings as pertaining to land.

    Parameters
    ----------
    s : dict
        Settings dictionary
    df : pd.DataFrame
        Your dataset

    Returns
    -------
    list
        A list of all field names pertaining to land
    """
    fields = get_fields_land(s, df)
    return (
        fields.get("categorical", [])
        + fields.get("numeric", [])
        + fields.get("boolean", [])
    )

get_fields_numeric

get_fields_numeric(s, df=None, include_boolean=False, types=None)

Retrieve numeric field names based on settings and optional filters.

Parameters:

Name	Type	Description	Default
s	dict	Settings dictionary containing field configurations.	required
df	DataFrame	DataFrame to filter fields by presence. Defaults to None.	None
include_boolean	bool	Whether to include boolean fields in the results or not. Defaults to False.	False
types	list[str]	List of field classification types to include (e.g., ["land", "impr", "other"]). Defaults to None, which includes all types.	None

Returns:

Type	Description
list[str]	List of numeric field names matching the specified criteria.

Source code in openavmkit/utilities/settings.py

def get_fields_numeric(
    s: dict,
    df: pd.DataFrame = None,
    include_boolean: bool = False,
    types: list[str] = None,
):
    """
     Retrieve numeric field names based on settings and optional filters.

     Parameters
     ----------
     s : dict
         Settings dictionary containing field configurations.
     df : pandas.DataFrame, optional
         DataFrame to filter fields by presence. Defaults to None.
     include_boolean : bool, optional
         Whether to include boolean fields in the results or not. Defaults to False.
     types : list[str], optional
         List of field classification types to include (e.g., ["land", "impr", "other"]).
         Defaults to None, which includes all types.

     Returns
     -------
     list[str]
         List of numeric field names matching the specified criteria.
     """
    if types is None:
        types = ["land", "impr", "other"]
    nums = []
    if "land" in types:
        nums += s.get("field_classification", {}).get("land", {}).get("numeric", [])
    if "impr" in types:
        nums += s.get("field_classification", {}).get("impr", {}).get("numeric", [])
    if "other" in types:
        nums += s.get("field_classification", {}).get("other", {}).get("numeric", [])
    if include_boolean:
        if "land" in types:
            nums += s.get("field_classification", {}).get("land", {}).get("boolean", [])
        if "impr" in types:
            nums += s.get("field_classification", {}).get("impr", {}).get("boolean", [])
        if "other" in types:
            nums += (
                s.get("field_classification", {}).get("other", {}).get("boolean", [])
            )
    if df is not None:
        nums = [num for num in nums if num in df]
    return nums

get_fields_other

get_fields_other(s, df=None)

Get all fields in the given dataframe that are classified in settings as pertaining to neither land nor buildings/improvements.

Parameters:

Name	Type	Description	Default
s	dict	Settings dictionary	required
df	DataFrame	Your dataset	None

Returns:

Type	Description
dict	All fields pertaining neither to land nor to buildings/improvements, organized as a dictionary containing three keys: "categorical": list of categorical fields "numeric": list of numerical fields "boolean": list of boolean fields

Source code in openavmkit/utilities/settings.py

def get_fields_other(s: dict, df: pd.DataFrame = None):
    """
    Get all fields in the given dataframe that are classified in settings as pertaining to neither land nor
    buildings/improvements.

    Parameters
    ----------
    s : dict
        Settings dictionary
    df : pd.DataFrame
        Your dataset

    Returns
    -------
    dict
        All fields pertaining neither to land nor to buildings/improvements,
        organized as a dictionary containing three keys:

          - "categorical": list of categorical fields
          - "numeric": list of numerical fields
          - "boolean": list of boolean fields
    """
    return _get_fields(s, "other", df)

get_fields_other_as_list

get_fields_other_as_list(s, df=None)

Get all fields in the given dataframe that are classified in settings as pertaining to neither land nor to buildings/improvements.

Parameters:

Name	Type	Description	Default
s	dict	Settings dictionary	required
df	DataFrame	Your dataset	None

Returns:

Type	Description
list	A list of all field names pertaining neither to land nor to buildings/improvements

Source code in openavmkit/utilities/settings.py

def get_fields_other_as_list(s: dict, df: pd.DataFrame = None):
    """
    Get all fields in the given dataframe that are classified in settings as pertaining to neither land nor to
    buildings/improvements.

    Parameters
    ----------
    s : dict
        Settings dictionary
    df : pd.DataFrame
        Your dataset

    Returns
    -------
    list
        A list of all field names pertaining neither to land nor to buildings/improvements
    """
    fields = get_fields_other(s, df)
    return (
        fields.get("categorical", [])
        + fields.get("numeric", [])
        + fields.get("boolean", [])
    )

get_grouped_fields_from_data_dictionary

get_grouped_fields_from_data_dictionary(dd, group, types=None)

Get all field names from the data dictionary of the named group and, optionally, of the designated types.

Parameters:

Name	Type	Description	Default
dd	dict	The data dictionary	required
group	str	Name of a particular group in the data dictionary	required
types	list	If None, returns all field names in the group. If not, targets only those fields that match the listed types. Legal values are: "boolean", "str", "number", "percent", "date"	None

Returns:

Type	Description
list[str]	A list of field names belonging to the specified group

Source code in openavmkit/utilities/settings.py

def get_grouped_fields_from_data_dictionary(
    dd: dict, group: str, types: list[str] = None
) -> list[str]:
    """
    Get all field names from the data dictionary of the named group and, optionally, of the designated types.

    Parameters
    ----------
    dd : dict
        The data dictionary
    group : str
        Name of a particular group in the data dictionary
    types : list, optional
        If None, returns all field names in the group. If not, targets only those fields that match the
        listed types. Legal values are: "boolean", "str", "number", "percent", "date"

    Returns
    -------
    list[str]
        A list of field names belonging to the specified group
    """
    result = []
    for key in dd:
        entry = dd[key]
        if group in entry.get("groups", []):
            if types is None or entry.get("type") in types:
                result.append(key)
    return result

get_large_area_unit

get_large_area_unit(settings)

Get the designated "large" area unit (acre or hectare)

Parameters:

Name	Type	Description	Default
settings	dict	Settings dictionary	required

Returns:

Type	Description
str	"acre" if units are imperial and "ha" if units are metric

Source code in openavmkit/utilities/settings.py

def get_large_area_unit(settings: dict):
    """
    Get the designated "large" area unit (acre or hectare)

    Parameters
    ----------
    settings : dict
        Settings dictionary

    Returns
    -------
    str
        "acre" if units are imperial and "ha" if units are metric
    """
    base_units = settings.get("locality", {}).get("units", "imperial")
    if base_units == "imperial":
        return "acre"
    elif base_units == "metric":
        return "ha"  # hectare

get_long_distance_unit

get_long_distance_unit(settings)

Get the designated "long" distance unit (mile or kilometer)

Parameters:

Name	Type	Description	Default
settings	dict	Settings dictionary	required

Returns:

Type	Description
str	"mile" if units are imperial and "km" if units are metric

Source code in openavmkit/utilities/settings.py

def get_long_distance_unit(settings: dict):
    """
    Get the designated "long" distance unit (mile or kilometer)

    Parameters
    ----------
    settings : dict
        Settings dictionary

    Returns
    -------
    str
        "mile" if units are imperial and "km" if units are metric
    """
    base_units = settings.get("locality", {}).get("units", "imperial")
    if base_units == "imperial":
        return "mile"
    elif base_units == "metric":
        return "km"

get_model_group

get_model_group(s, key)

Get a model group definition object from the settings dictionary

Parameters:

Name	Type	Description	Default
s	dict	Settings object	required
key	str	The name of the model group	required

Returns:

Type	Description
dict	Model group definition

Source code in openavmkit/utilities/settings.py

def get_model_group(s: dict, key: str):
    """
    Get a model group definition object from the settings dictionary

    Parameters
    ----------
    s : dict
        Settings object
    key : str
        The name of the model group

    Returns
    -------
    dict
        Model group definition
    """
    return s.get("modeling", {}).get("model_groups", {}).get(key, {})

get_model_group_ids

get_model_group_ids(settings, df=None)

Get all model group ids specified in settings, in the preferred order specified by the user

Parameters:

Name	Type	Description	Default
settings	dict	Settings dictionary	required
df	DataFrame	Your dataset	None

Returns:

Type	Description
list[str]	Ordered list of model group ids

Source code in openavmkit/utilities/settings.py

def get_model_group_ids(settings: dict, df: pd.DataFrame = None):
    """
    Get all model group ids specified in settings, in the preferred order specified by the user

    Parameters
    ----------
    settings : dict
        Settings dictionary
    df : pd.DataFrame
        Your dataset

    Returns
    -------
    list[str]
        Ordered list of model group ids
    """
    modeling = settings.get("modeling", {})

    # Get the model groups defined in the settings
    model_groups = modeling.get("model_groups", {})

    # Get the preferred order, if any
    order = modeling.get("instructions", {}).get("model_group_order", [])

    if df is not None:
        # If a dataframe is provided, filter out model groups that are not present in the DataFrame
        model_groups_in_df = df["model_group"].unique()
        model_group_ids = [key for key in model_groups if key in model_groups_in_df]
    else:
        model_group_ids = [key for key in model_groups]

    # Order the model groups according to the preferred order
    ordered_ids = [key for key in order if key in model_group_ids]
    unordered_ids = [key for key in model_group_ids if key not in ordered_ids]
    ordered_ids += unordered_ids

    return ordered_ids

get_short_distance_unit

get_short_distance_unit(settings)

Get the designated "short" distance unit (foot or meter)

Parameters:

Name	Type	Description	Default
settings	dict	Settings dictionary	required

Returns:

Type	Description
str	"ft" if units are imperial and "m" if units are metric

Source code in openavmkit/utilities/settings.py

def get_short_distance_unit(settings: dict):
    """
    Get the designated "short" distance unit (foot or meter)

    Parameters
    ----------
    settings : dict
        Settings dictionary

    Returns
    -------
    str
        "ft" if units are imperial and "m" if units are metric
    """
    base_units = settings.get("locality", {}).get("units", "imperial")
    if base_units == "imperial":
        return "ft"
    elif base_units == "metric":
        return "m"

get_small_area_unit

get_small_area_unit(settings)

Get the designated "small" area unit (square feet or square meters)

Parameters:

Name	Type	Description	Default
settings	dict	Settings dictionary	required

Returns:

Type	Description
str	"sqft" if units are imperial and "sqm" if units are metric

Source code in openavmkit/utilities/settings.py

def get_small_area_unit(settings: dict):
    """
    Get the designated "small" area unit (square feet or square meters)

    Parameters
    ----------
    settings : dict
        Settings dictionary

    Returns
    -------
    str
        "sqft" if units are imperial and "sqm" if units are metric
    """
    base_units = settings.get("locality", {}).get("units", "imperial")
    if base_units == "imperial":
        return "sqft"
    elif base_units == "metric":
        return "sqm"

get_valuation_date

get_valuation_date(s)

Get the valuation date from the settings dictionary

Parameters:

Name	Type	Description	Default
s	dict	Settings dictionary	required

Returns:

Type	Description
datetime	The valuation date

Source code in openavmkit/utilities/settings.py

def get_valuation_date(s: dict):
    """
    Get the valuation date from the settings dictionary

    Parameters
    ----------
    s : dict
        Settings dictionary

    Returns
    -------
    datetime
        The valuation date
    """
    val_date_str: str | None = (
        s.get("modeling", {}).get("metadata", {}).get("valuation_date", None)
    )

    if val_date_str is None:
        # return January 1 of this year:
        return datetime(datetime.now().year, 1, 1)

    # process the date from string to datetime using format YYYY-MM-DD:
    val_date = datetime.strptime(val_date_str, "%Y-%m-%d")
    return val_date

get_variable_interactions

get_variable_interactions(entry, settings, df=None)

Get variable interaction information from a dictionary object

Parameters:

Name	Type	Description	Default
entry	dict	The dictionary object that may contain variable interactions	required
settings	dict	Global settings dictionary	required
df	DataFrame	Your dataset	None

Returns:

Type

Description

dict | None

Interactions dictionary which maps field names to other field names, indicating variable interactions. Example: Interacting a categorical field like "neighborhood" with a numeric field like "land_area_sqft" means that every one-hot-encoded descendant like "neighborhood=River Heights" will be multiplied against the numeric value of "land_area_sqft", so this is a way to interact neighborhood dummies with land size.

Source code in openavmkit/utilities/settings.py

def get_variable_interactions(entry: dict, settings: dict, df: pd.DataFrame = None):
    """
    Get variable interaction information from a dictionary object

    Parameters
    ----------
    entry : dict
        The dictionary object that may contain variable interactions
    settings : dict
        Global settings dictionary
    df : pd.DataFrame
        Your dataset

    Returns
    -------
    dict | None
        Interactions dictionary which maps field names to other field names, indicating variable interactions.

        Example:
        Interacting a categorical field like "neighborhood" with a numeric field like "land_area_sqft" means that
        every one-hot-encoded descendant like "neighborhood=River Heights" will be multiplied against the numeric
        value of "land_area_sqft", so this is a way to interact neighborhood dummies with land size.
    """
    interactions: dict | None = entry.get("interactions", None)
    if interactions is None:
        return {}
    is_default = interactions.get("default", False)
    if is_default:
        result = {}
        fields_land = get_fields_categorical(
            settings, df, include_boolean=True, types=["land"]
        )
        fields_impr = get_fields_categorical(
            settings, df, include_boolean=True, types=["impr"]
        )
        for field in fields_land:
            result[field] = "land_area_sqft"
        for field in fields_impr:
            result[field] = "bldg_area_finished_sqft"
        return result
    else:
        return interactions.get("fields", {})

load_settings

load_settings(settings_file='in/settings.json', settings_object=None, error=True, warning=True)

Load settings file from disk

Parameters:

Name	Type	Description	Default
settings_file	str	Path to the settings file	'in/settings.json'
settings_object	dict	Already loaded settings object	None
error	bool	Whether to raise errors or simply emit warnings if something is wrong	True
warning	bool	Whether to emit warnings if something is wrong	True

Returns:

Type	Description
dict	The settings object

Source code in openavmkit/utilities/settings.py

def load_settings(
    settings_file: str = "in/settings.json", settings_object: dict = None, error:bool=True, warning:bool=True
):
    """
    Load settings file from disk

    Parameters
    ----------
    settings_file : str
        Path to the settings file
    settings_object : dict, optional
        Already loaded settings object
    error : bool, optional
        Whether to raise errors or simply emit warnings if something is wrong
    warning : bool, optional
        Whether to emit warnings if something is wrong

    Returns
    -------
    dict
        The settings object
    """
    settings : dict | None = None

    if settings_object is None:
        try:
            with open(settings_file, "r") as f:
                settings = json.load(f)
        except FileNotFoundError:
            cwd = os.getcwd()
            full_path = os.path.join(cwd, settings_file)
            exists = os.path.exists(full_path)
            msg = f"Could not find settings file: {settings_file}. Go to '{cwd}' and create a settings.json file there! {full_path} exists? {exists}"
            if error:
                raise FileNotFoundError(msg)
            else:
                if warning:
                    warnings.warn(msg)

    else:
        settings = settings_object

    if settings is None:
        return None

    template = _load_settings_template()
    # merge settings with template; settings will overwrite template values
    settings = _merge_settings(template, settings)
    base_dd = {"data_dictionary": _load_data_dictionary_template()}
    settings = _merge_settings(base_dd, settings)
    settings = _remove_comments_from_settings(settings)
    settings = _replace_variables(settings)
    return settings