settings

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': [...]}

dict

required

Settings dictionary

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)

dict

required

Settings dictionary

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': [...]}

dict

required

Settings dictionary

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']
)

dict

required

Settings dictionary

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']
)

dict

required

Settings dictionary

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']
)

dict

required

Settings dictionary

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')

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

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)

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)

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)

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']
)

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

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}")

Core Modules

Analysis & Evaluation

Data Processing

Specialized Analysis

Utilities

Cloud & Storage

Quality & Reports

Settings Loading

load_settings()

Field Classification

get_fields_land()

get_fields_land_as_list()

get_fields_impr()

get_fields_categorical()

get_fields_numeric()

get_fields_boolean()

Model Configuration

get_model_group()

get_model_group_ids()

Locality Settings

get_valuation_date()

get_look_back_dates()

get_center()

Unit Conversions

area_unit()

big_area_unit()

length_unit()

big_length_unit()

Data Dictionary

get_data_dictionary()

get_grouped_fields_from_data_dictionary()

Variable Interactions

get_variable_interactions()

Usage Example

Build docs developers (and LLMs) love

Core Modules

Analysis & Evaluation

Data Processing

Specialized Analysis

Utilities

Cloud & Storage

Quality & Reports

​Settings Loading

​load_settings()

​Field Classification

​get_fields_land()

​get_fields_land_as_list()

​get_fields_impr()

​get_fields_categorical()

​get_fields_numeric()

​get_fields_boolean()

​Model Configuration

​get_model_group()

​get_model_group_ids()

​Locality Settings

​get_valuation_date()

​get_look_back_dates()

​get_center()

​Unit Conversions

​area_unit()

​big_area_unit()

​length_unit()

​big_length_unit()

​Data Dictionary

​get_data_dictionary()

​get_grouped_fields_from_data_dictionary()

​Variable Interactions

​get_variable_interactions()

​Usage Example

Build docs developers (and LLMs) love

Settings Loading

load_settings()

Field Classification

get_fields_land()

get_fields_land_as_list()

get_fields_impr()

get_fields_categorical()

get_fields_numeric()

get_fields_boolean()

Model Configuration

get_model_group()

get_model_group_ids()

Locality Settings

get_valuation_date()

get_look_back_dates()

get_center()

Unit Conversions

area_unit()

big_area_unit()

length_unit()

big_length_unit()

Data Dictionary

get_data_dictionary()

get_grouped_fields_from_data_dictionary()

Variable Interactions

get_variable_interactions()

Usage Example