MassBalanceMachine.jl API

CustomMLP

A custom neural network regressor struct that wraps a Lux model for inference. All required inference metadata is automatically loaded from JSON files.

Fields

• model: The Lux neural network model
• nbFeatures::Int: Number of input features
• nNeurons::Vector: Layer sizes for the network
• activation: Activation function
• params::NamedTuple: Model parameters
• state::NamedTuple: Model state

CustomMLP(params_json::String, model_json::String)

Create a CustomMLP by loading inference configuration from JSON files.

Arguments

• params_json::String: Path to params.json file containing network architecture
• model_json::String: Path to model.json file containing input feature names and optional normalization bounds

Returns

• CustomMLP: Fully configured custom MLP instance

MLP(nNeurons::Vector, activation=relu)

A simple feedforward neural network built dynamically based on layer sizes.

Arguments

• nNeurons::Vector: Vector of layer sizes, must have at least 2 elements. Example: [inputsize, hiddensize1, ..., hiddensizen, outputsize]
• activation: Activation function to use between layers (default: relu) Example: relu, tanh, sigmoid, gelu, etc.

_hf_download(
    repo_id::AbstractString,
    revision::AbstractString,
    path_in_repo::AbstractString;
    dest::Union{Nothing,String}=nothing
)

Download files from a model stored in a HuggingFace repository and associated to the version revision. The repository is identified by repo_id (for example "MassBalanceMachine/MLP"). The downloaded file is stored in dest.

delete_model(name::String; dir = models_dir())

Remove the named model from the registry and delete its .jld2 file.

download_MLP(revision::String)

Download the version revision of the MLP from the HuggingFace repository and store it in the registry.

inject_weights_from_json(params_nt::NamedTuple, model_data::AbstractDict{String, Any})

Inject weights and biases from JSON model data directly into params NamedTuple. Matches the hierarchical structure of Lux params exactly. Verifies consistency between JSON and Lux-generated structure.

list_models(; dir = models_dir()) -> Vector{NamedTuple}

Print a formatted summary of all models in the registry and return a vector of NamedTuples with fields name, arch, features, saved_at.

load_data(csv_filepath::String, json_filepath::String; target_col::String="y")

Load data from a CSV file using feature columns specified in a model.json file.

Arguments

• csv_filepath::String: Path to the CSV file
• json_filepath::String: Path to the model.json file containing feature names
• target_col::String: Name of the target column (default: "y")

Returns

• Tuple: (features, targets, featurecols) where features is (nfeatures, n_samples)

load_model(name::String; dir = models_dir()) -> CustomMLP

Reconstruct a CustomMLP from the registry by name.

The Lux model is built from the stored architecture and the pre-saved weights and biases are injected directly — no PyTorch JSON parsing required.

Example

mlp = load_model("geo_norway_v1")
y, _ = mlp.model(x_batch, mlp.params, mlp.state)

models_dir() -> String

Return the default directory where named models are stored on disk.

normalize(df::DataFrame, feature_symbols::Vector{Symbol})

Normalize specified feature columns in the DataFrame to the range [0, 1].

Arguments

• df::DataFrame: Input DataFrame
• feature_symbols::Vector{Symbol}: Vector of column symbols to normalize

save_model(mlp::CustomMLP, name::String; dir = models_dir()) -> String

Serialize mlp into the model registry under the given name.

The Lux params and state (weights and biases) are written to a JLD2 file so subsequent loads require no JSON parsing or weight injection. All architecture and normalization metadata are stored alongside.

If a model with the same name already exists it is overwritten.

Returns the path to the saved .jld2 file.

Example

mlp = CustomMLP("path/to/params.json", "path/to/best_model.json")
save_model(mlp, "geo_norway_v1")

verify_normalized_features(csv_filepath::String, json_filepath::String, reference_filepath::String; target_col::String="y")

Verify that the generated normalized features match exactly the reference file.

Arguments

• csv_filepath::String: Path to the CSV file
• json_filepath::String: Path to the model.json file containing feature names
• reference_filepath::String: Path to the reference JSON file containing normalized features
• target_col::String: Name of the target column (default: "y")

Returns

• Bool: True if the normalized features match the reference file, False otherwise