Skip to content

Utils#

cheersafe.tools.Utils contains lightweight file and DataFrame helpers used by the CHEERSafe runtime.

Purpose And When To Use#

Use Utils.from_json() and Utils.to_json() for the same JSON conversion rules used by the model. Use Utils.filter_column_values_df() when you need the first matching value from a pandas table after applying simple equality filters.

Inputs#

Method Inputs Units, indexing, shapes, or file dependencies
from_json(path_to_file, dict_key=None) JSON file path and optional dictionary key. JSON lists are converted to NumPy arrays. JSON dictionaries return the full dictionary unless dict_key is supplied, in which case that value is converted to a NumPy array.
to_json(data, path_to_file) JSON-compatible data, NumPy arrays/scalars, nested lists, tuples, or dictionaries. Parent directories are created when needed. NumPy arrays become lists and NumPy scalars become Python scalars.
filter_column_values_df(df, column_name, **kwargs) pandas DataFrame, output column name, and equality filters by column. Filters are exact equality conditions. The method returns the first matching row's selected column value as a NumPy array.

Utils does not use Config.INPUTS_PATH automatically. Pass the full path you want to read or write.

Outputs And Returns#

Method Return
from_json() np.ndarray for JSON lists or selected dictionary values; dict for full JSON objects.
to_json() None; writes a JSON file.
filter_column_values_df() np.ndarray containing the selected value from the first matching row.

AUTO_LOAD_DATASETS Behavior#

Utils methods do not inspect Config.AUTO_LOAD_DATASETS. They perform their I/O or filtering only when called.

AUTO_EXECUTE_METHODS Behavior#

Utils methods do not inspect Config.AUTO_EXECUTE_METHODS. They are class methods with no automatic initialization behavior.

Minimal Automatic Example#

There is no constructor-side automatic behavior for Utils; the direct call is the normal use:

PYTHONPATH=src python3 - <<'PY'
from cheersafe.tools import Utils

geometry = Utils.from_json("Inputs/BuildingGeometry_Old.json")
print(geometry.shape)
print(geometry[:, 0].shape)
PY

Minimal Manual-Control Example#

PYTHONPATH=src python3 - <<'PY'
from tempfile import TemporaryDirectory
import pandas as pd
from cheersafe.tools import Utils

df = pd.DataFrame({"BldgType": [1, 2], "Value": [[10, 20], [30, 40]]})
value = Utils.filter_column_values_df(df, "Value", BldgType=2)

with TemporaryDirectory() as tmpdir:
    out = f"{tmpdir}/manual_utils_example.json"
    Utils.to_json({"value": value}, out)
    print(Utils.from_json(out))
PY