settings

Settings file loading, validation, and accessor functions

The settings module provides comprehensive utilities for loading, validating, and accessing configuration settings for OpenAVM Kit, including field classifications, model groups, and locality-specific configurations.

Settings Loading

load_settings()

Load settings file from disk and merge with templates.

from openavmkit.utilities.settings import load_settings

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

settings_file · str · default: "'in/settings.json'"

Path to the settings file

settings_object · dict · default: "None"

Already loaded settings object (if provided, settings_file is ignored)

error · bool · default: "True"

Whether to raise errors or emit warnings if something is wrong

warning · bool · default: "True"

Whether to emit warnings if something is wrong

settings · dict

The settings object, merged with templates and with variables replaced. Returns None if settings cannot be loaded.

---

Field Classification

get_fields_land()

Get all fields classified as pertaining to land.

from openavmkit.utilities.settings import get_fields_land

fields = get_fields_land(settings, df)
# Returns: {'categorical': [...], 'numeric': [...], 'boolean': [...]}

s · dict · required

Settings dictionary

df · pd.DataFrame · default: "None"

Optional DataFrame to filter fields by presence

fields · dict

Dictionary containing:

• categorical: list of categorical land fields
• numeric: list of numerical land fields
• boolean: list of boolean land fields

Automatically includes spatial fields like dist_to_*, within_*, proximity_to_*, and spatial_lag_*.

---

get_fields_land_as_list()

Get all land fields as a single flat list.

fields = get_fields_land_as_list(settings, df)

s · dict · required

Settings dictionary

df · pd.DataFrame · default: "None"

Optional DataFrame to filter fields

fields · list[str]

Flat list of all land field names

---

get_fields_impr()

Get all fields classified as pertaining to buildings/improvements.

fields = get_fields_impr(settings, df)
# Returns: {'categorical': [...], 'numeric': [...], 'boolean': [...]}

s · dict · required

Settings dictionary

df · pd.DataFrame · default: "None"

Optional DataFrame to filter fields

fields · dict

Dictionary with categorical, numeric, and boolean keys

---

get_fields_categorical()

Retrieve categorical field names based on settings.

from openavmkit.utilities.settings import get_fields_categorical

cat_fields = get_fields_categorical(
    settings,
    df=None,
    include_boolean=False,
    types=['land', 'impr', 'other']
)

s · dict · required

Settings dictionary

df · pd.DataFrame · default: "None"

DataFrame to filter fields by presence

include_boolean · bool · default: "False"

Whether to include boolean fields

types · list[str] · default: "['land', 'impr', 'other']"

Field classification types to include

fields · list[str]

List of categorical field names

---

get_fields_numeric()

Retrieve numeric field names based on settings.

numeric_fields = get_fields_numeric(
    settings,
    df=None,
    include_boolean=False,
    types=['land', 'impr', 'other']
)

s · dict · required

Settings dictionary

df · pd.DataFrame · default: "None"

DataFrame to filter fields by presence

include_boolean · bool · default: "False"

Whether to include boolean fields

types · list[str] · default: "['land', 'impr', 'other']"

Field classification types to include

fields · list[str]

List of numeric field names

---

get_fields_boolean()

Retrieve boolean field names based on settings.

bool_fields = get_fields_boolean(
    settings,
    df=None,
    types=['land', 'impr', 'other']
)

s · dict · required

Settings dictionary

df · pd.DataFrame · default: "None"

DataFrame to filter fields by presence

types · list[str] · default: "['land', 'impr', 'other']"

Field classification types to include

fields · list[str]

List of boolean field names

---

Model Configuration

get_model_group()

Get a model group definition object from settings.

from openavmkit.utilities.settings import get_model_group

model_group = get_model_group(settings, 'single_family')

s · dict · required

Settings dictionary

key · str · required

The name of the model group

model_group · dict

Model group definition containing configuration for that model group

---

get_model_group_ids()

Get all model group IDs in the preferred order.

from openavmkit.utilities.settings import get_model_group_ids

ids = get_model_group_ids(settings, df=None)

settings · dict · required

Settings dictionary

df · pd.DataFrame · default: "None"

Optional DataFrame to filter by model groups present in the data

ids · list[str]

Ordered list of model group IDs

---

Locality Settings

get_valuation_date()

Get the valuation date from settings.

from openavmkit.utilities.settings import get_valuation_date
from datetime import datetime

val_date = get_valuation_date(settings)

s · dict · required

Settings dictionary

date · datetime

The valuation date. Defaults to January 1 of current year if not specified in settings.

---

get_look_back_dates()

Get the look-back date range for ratio studies.

from openavmkit.utilities.settings import get_look_back_dates

look_back_date, val_date = get_look_back_dates(settings)

s · dict · required

Settings dictionary

return · tuple[datetime, datetime]

Tuple containing:

• look_back_date: Start of the look-back period
• val_date: Valuation date (end of period)

---

get_center()

Get the centroid of the locality.

from openavmkit.utilities.settings import get_center

lon, lat = get_center(settings, gdf=None)

s · dict · required

Settings dictionary

gdf · gpd.GeoDataFrame · default: "None"

Optional parcel geometry to calculate centroid from if not in settings

return · tuple[float, float]

Tuple of (longitude, latitude)

---

Unit Conversions

area_unit()

Get the designated small area unit.

from openavmkit.utilities.settings import area_unit

unit = area_unit(settings)  # Returns 'sqft' or 'sqm'

settings · dict · required

Settings dictionary

unit · str

'sqft' if units are imperial, 'sqm' if metric

---

big_area_unit()

Get the designated large area unit.

unit = big_area_unit(settings)  # Returns 'acre' or 'ha'

settings · dict · required

Settings dictionary

unit · str

'acre' if units are imperial, 'ha' (hectare) if metric

---

length_unit()

Get the designated small length unit.

unit = length_unit(settings)  # Returns 'ft' or 'm'

settings · dict · required

Settings dictionary

unit · str

'ft' if units are imperial, 'm' if metric

---

big_length_unit()

Get the designated large length unit.

unit = big_length_unit(settings)  # Returns 'mi' or 'km'

settings · dict · required

Settings dictionary

unit · str

'mi' if units are imperial, 'km' if metric

---

Data Dictionary

get_data_dictionary()

Get the data dictionary object.

from openavmkit.utilities.settings import get_data_dictionary

dd = get_data_dictionary(settings)

settings · dict · required

Settings dictionary

data_dictionary · dict

The data dictionary for this locality, mapping field names to their metadata

---

get_grouped_fields_from_data_dictionary()

Get all field names from a specific group in the data dictionary.

from openavmkit.utilities.settings import get_grouped_fields_from_data_dictionary

fields = get_grouped_fields_from_data_dictionary(
    dd,
    group='property_characteristics',
    types=['number', 'percent']
)

dd · dict · required

The data dictionary

group · str · required

Name of a particular group in the data dictionary

types · list · default: "None"

Optional list of types to filter by: 'boolean', 'str', 'number', 'percent', 'date'

fields · list[str]

List of field names belonging to the specified group

---

Variable Interactions

get_variable_interactions()

Get variable interaction information from a model group configuration.

from openavmkit.utilities.settings import get_variable_interactions

model_group = get_model_group(settings, 'single_family')
interactions = get_variable_interactions(model_group, settings, df)

entry · dict · required

Model group dictionary that may contain variable interactions

settings · dict · required

Global settings dictionary

df · pd.DataFrame · default: "None"

Your dataset

interactions · dict

Dictionary mapping field names to other field names for variable interactions.

For example, {'neighborhood': 'land_area_sqft'} means each one-hot-encoded neighborhood dummy will be multiplied by the land area value.

---

Usage Example

import pandas as pd
from openavmkit.utilities.settings import (
    load_settings,
    get_fields_land_as_list,
    get_fields_impr_as_list,
    get_valuation_date,
    area_unit
)

# Load settings
settings = load_settings('in/settings.json')

# Get field classifications
land_fields = get_fields_land_as_list(settings, df)
impr_fields = get_fields_impr_as_list(settings, df)

# Get valuation date
val_date = get_valuation_date(settings)
print(f"Valuation date: {val_date}")

# Get unit system
area = area_unit(settings)
print(f"Using {area} for area measurements")

# Get model groups
model_groups = get_model_group_ids(settings, df)
print(f"Model groups: {model_groups}")