EasyHybrid.jl

Documentation for EasyHybrid.jl.

EasyHybrid.EasyHybrid Module

julia

EasyHybrid

EasyHybrid is a Julia package for hybrid machine learning models, combining neural networks and traditional statistical methods. It provides tools for data preprocessing, model training, and evaluation, making it easier to build and deploy hybrid models.

EasyHybrid.BulkDensitySOC Type

julia

BulkDensitySOC(NN, predictors, targets, oBD)

A hybrid model with a neural network NN, predictors and one global parameter oBD.

EasyHybrid.BulkDensitySOC Method

julia

BulkDensitySOC(NN, predictors, oBD)(ds_k)

Hybrid model for bulk density based on the Federer (1993) paper http://dx.doi.org/10.1139/x93-131 plus SOC concentrations, density and coarse fraction

EasyHybrid.FluxPartModel_NEE_ET2 Method

FluxPartModel_NEE_ET2( RUE_predictors::AbstractArray{Symbol}, Rb_predictors::AbstractArray{Symbol}, WUE_predictors::AbstractArray{Symbol}, Ecoeff_predictors::AbstractArray{Symbol}; forcing=[:SW_IN, :TA], Q10=[1.5f0], neurons=15 )

EasyHybrid.FluxPartModel_NEE_ET2 Method

(m::FluxPartModel_NEE_ET2)(dk, infer::Symbol)

EasyHybrid.FluxPartModel_Q10 Method

FluxPartModel_Q10(RUE_predictors, Rb_predictors; Q10=[1.5f0])

EasyHybrid.FluxPartModel_Q10 Method

(m::FluxPartModel_Q10)(dk, infer::Symbol)

EasyHybrid.LinearHM Type

julia

LinearHM(NN, predictors, forcing, β)

A linear hybrid model with a neural network NN, predictors and forcing terms.

EasyHybrid.LinearHM Method

julia

LinearHM(NN, predictors, forcing, β)(ds_k)

Model definition ŷ = α x + β

Apply the linear hybrid model to the input data ds_k (a KeyedArray with proper dimensions). The model uses the neural network NN to compute new α's based on the predictors and then computes ŷ using the forcing term x.

Returns:

A tuple containing the predicted values ŷ and a named tuple with the computed values of α and the state st.

Example:

julia

using Lux
using EasyHybrid
using Random
using AxisKeys

ds_k = KeyedArray(rand(Float32, 3,4); data=[:a, :b, :c], sample=1:4)
m = Lux.Chain(Dense(2, 5), Dense(5, 1))
# Instantiate the model
# Note: The model is initialized with a neural network and the predictors and forcing terms
lh_model = LinearHM(m, (:a, :b), (:c,), 1.5f0)
rng = Random.default_rng()
Random.seed!(rng, 0)
ps, st = LuxCore.setup(rng, lh_model)
# Apply the model to the data
ŷ, αst = LuxCore.apply(lh_model, ds_k, ps, st)

EasyHybrid.LinearHybridModel Method

LinearHybridModel(predictors::AbstractArray{Symbol}, forcing::AbstractArray{Symbol}, out_dim::Int, neurons::Int; b=[1.5f0])

EasyHybrid.LinearHybridModel Method

(lhm::LinearHybridModel)(df, infer::Symbol)

EasyHybrid.LinearHybridModel_2outputs Method

LinearHybridModel_2outputs(predictors::AbstractArray{Symbol}, forcing::AbstractArray{Symbol}, out_dim::Int, neurons::Int, nn_chain; a=[1.0f0], b=[1.5f0])

- nn_chain :: DenseNN, a Dense neural network

EasyHybrid.LinearHybridModel_2outputs Method

LinearHybridModel_2outputs(df, infer::Symbol)

EasyHybrid.LoggingLoss Type

julia

LoggingLoss

A structure to define a logging loss function for hybrid models. It allows for multiple loss types and an aggregation function to be specified.

Arguments:

loss_types::Vector{Symbol}: A vector of loss types to compute, e.g., [:mse, :mae].
training_loss::Symbol: The loss type to use during training, e.g., :mse.
agg::Function: A function to aggregate the losses, e.g., sum or mean.
train_mode::Bool: A flag indicating whether the model is in training mode. If true, it uses training_loss; otherwise, it uses loss_types.

EasyHybrid.RespirationRbQ10 Type

julia

RespirationRbQ10(NN, predictors, forcing, targets, Q10)

A linear hybrid model with a neural network NN, predictors, targets and forcing terms.

EasyHybrid.RespirationRbQ10 Method

julia

RespirationRbQ10(NN, predictors, forcing, targets, Q10)(ds_k)

Model definition ŷ = Rb(αᵢ(t)) * Q10^((T(t) - T_ref)/10)

ŷ (respiration rate) is computed as a function of the neural network output Rb(αᵢ(t)) and the temperature T(t) adjusted by the reference temperature T_ref (default 15°C) using the Q10 temperature sensitivity factor. ````

EasyHybrid.Rs_components Type

julia

Rs_components(NN, predictors, forcing, targets, Q10_het, Q10_root, Q10_myc)

A linear hybrid model with a neural network NN, predictors, targets and forcing terms.

EasyHybrid.Rs_components Method

julia

Rs_components(NN, predictors, forcing, targets, Q10)(ds_k)

Model definition ŷ = Rb(αᵢ(t)) * Q10^((T(t) - T_ref)/10)

ŷ (respiration rate) is computed as a function of the neural network output Rb(αᵢ(t)) and the temperature T(t) adjusted by the reference temperature T_ref (default 15°C) using the Q10 temperature sensitivity factor. ````

EasyHybrid.SinusHybridModel Method

SinusHybridModel(predictors, forcing, out_dim; neurons=15, b=[1.5f0])

EasyHybrid.SinusHybridModel Method

(lhm::SinusHybridModel)(dk, infer::Symbol)

EasyHybrid.WrappedTuples Type

julia

WrappedTuples(vec::Vector{<:NamedTuple})

Wraps a vector of named tuples to allow dot-access to each field as a vector.

EasyHybrid.DenseNN Method

DenseNN(in_dim, out_dim, neurons)

EasyHybrid.Dense_RUE_Rb Method

Dense_RUE_Rb(in_dim; neurons=15, out_dim=1, affine=true)

EasyHybrid.GRU_NN Method

GRU_NN(in_dim,out_dim, neurons)

EasyHybrid.compute_bulk_density Method

julia

compute_bulk_density(SOCconc, oBD, mBD)

model for bulk density based on the Federer (1993) paper http://dx.doi.org/10.1139/x93-131 plus SOC concentrations, density and coarse fraction

EasyHybrid.compute_loss Function

julia

compute_loss(ŷ, y, y_nan, targets, training_loss::Symbol, agg::Function)
compute_loss(ŷ, y, y_nan, targets, loss_types::Vector{Symbol}, agg::Function)

Compute the loss for the given predictions and targets using the specified training loss (or vector of losses) type and aggregation function.

Arguments:

ŷ: Predicted values.
y: Target values.
y_nan: Mask for NaN values.
targets: The targets for which the loss is computed.
training_loss::Symbol: The loss type to use during training, e.g., :mse.
loss_types::Vector{Symbol}: A vector of loss types to compute, e.g., [:mse, :mae].
agg::Function: The aggregation function to apply to the computed losses, e.g., sum or mean.

Returns a single loss value if training_loss is provided, or a NamedTuple of losses for each type in loss_types.

EasyHybrid.evec Method

evec(nt::NamedTuple)

EasyHybrid.get_predictions_targets Method

julia

get_predictions_targets(HM, x, (y_t, y_nan), ps, st, targets)

Get predictions and targets from the hybrid model and return them along with the NaN mask.

EasyHybrid.loss_fn Function

julia

loss_fn(ŷ, y, y_nan, ::Val{:rmse})
loss_fn(ŷ, y, y_nan, ::Val{:mse})
loss_fn(ŷ, y, y_nan, ::Val{:mae})
loss_fn(ŷ, y, y_nan, ::Val{:pearson})
loss_fn(ŷ, y, y_nan, ::Val{:r2})

Compute the loss for the given predictions and targets using the specified loss type.

Arguments:

ŷ: Predicted values.
y: Target values.
y_nan: Mask for NaN values.
::Val{:rmse}: Root Mean Square Error or ::Val{:mse}: Mean Square Error or ::Val{:mae}: Mean Absolute Error or ::Val{:pearson}: Pearson correlation coefficient or ::Val{:r2}: R-squared.

You can define additional loss functions as needed by adding more methods to this function.

Example:

In your working script just do the following:

julia

import EasyHybrid: loss_fn
function EasyHybrid.loss_fn(ŷ, y, y_nan, ::Val{:nse})
    return 1 - sum((ŷ[y_nan] .- y[y_nan]).^2) / sum((y[y_nan] .- mean(y[y_nan])).^2)
end

EasyHybrid.lossfn Method

julia

lossfn(HM::LuxCore.AbstractLuxContainerLayer, x, (y_t, y_nan), ps, st, logging::LoggingLoss)

Arguments:

HM::LuxCore.AbstractLuxContainerLayer: The hybrid model to compute the loss for.
x: Input data for the model.
(y_t, y_nan): Tuple containing the target values and a mask for NaN values.
ps: Parameters of the model.
st: State of the model.
logging::LoggingLoss: Logging configuration for the loss function.

EasyHybrid.prepare_data Method

julia

prepare_data(hm, data)

Utility function to see if the data is already in the expected format or if further filtering and re-packing is needed.

Arguments:

hm: The Hybrid Model
data: either a Tuple of KeyedArrays or a single KeyedArray.

Returns a tuple of KeyedArrays

EasyHybrid.select_cols Method

select_cols(df, predictors, x)

EasyHybrid.select_cols Method

select_cols(df::KeyedArray, predictors, x)

EasyHybrid.select_predictors Method

select_predictors(df, predictors)

EasyHybrid.select_predictors Method

select_predictors(dk::KeyedArray, predictors)

EasyHybrid.select_variable Method

select_variable(df::KeyedArray, x)

EasyHybrid.split_data Method

split_data(df::DataFrame, target, xvars, seqID; f=0.8, batchsize=32, shuffle=true, partial=true)

EasyHybrid.split_data Method

split_data(df::DataFrame, target, xvars; f=0.8, batchsize=32, shuffle=true, partial=true)

EasyHybrid.to_keyedArray Function

tokeyedArray(dfg::Union{Vector,GroupedDataFrame{DataFrame}}, vars=All())

EasyHybrid.to_keyedArray Method

tokeyedArray(df::DataFrame)

EasyHybrid.train Method

julia

train(hybridModel, data, save_ps; nepochs=200, batchsize=10, opt=Adam(0.01), file_name=nothing, loss_types=[:mse, :mae], training_loss=:mse, agg=sum)

Train a hybrid model using the provided data and save the training process to a file in JLD2 format. Default output file is trained_model.jld2 at the current working directory under output_tmp.

Arguments:

hybridModel: The hybrid model to be trained.
data: The training data, either a tuple of KeyedArrays or a single KeyedArray.
save_ps: A tuple of physical parameters to save during training.
nepochs: Number of training epochs (default: 200).
batchsize: Size of the training batches (default: 10).
opt: The optimizer to use for training (default: Adam(0.01)).
file_name: The name of the file to save the training process (default: nothing-> "trained_model.jld2").
loss_types: A vector of loss types to compute during training (default: [:mse, :mae]).
training_loss: The loss type to use during training (default: :mse).
agg: The aggregation function to apply to the computed losses (default: sum).

EasyHybrid.@hybrid Macro

julia

@hybrid ModelName α β γ

Macro to define hybrid model structs with arbitrary numbers of physical parameters.

This defines a struct with:

Default fields: NN (neural network), predictors, forcing, targets.
Additional physical parameters, i.e., α β γ.

Examples

julia

@hybrid MyModel α β γ
@hybrid FluidModel (:viscosity, :density)
@hybrid SimpleModel :a :b