Class GeneralizedAdditiveModel<T>

Namespace

AiDotNet.Regression

Assembly

AiDotNet.dll

Implements a Generalized Additive Model (GAM) for regression, which models the target as a sum of smooth functions of individual features, allowing for flexible nonlinear relationships while maintaining interpretability.

public class GeneralizedAdditiveModel<T> : RegressionBase<T>, IRegression<T>, IFullModel<T, Matrix<T>, Vector<T>>, IModel<Matrix<T>, Vector<T>, ModelMetadata<T>>, IModelSerializer, ICheckpointableModel, IParameterizable<T, Matrix<T>, Vector<T>>, IFeatureAware, IFeatureImportance<T>, ICloneable<IFullModel<T, Matrix<T>, Vector<T>>>, IGradientComputable<T, Matrix<T>, Vector<T>>, IJitCompilable<T>

Type Parameters

T

The numeric type used for calculations, typically float or double.

Inheritance

object

RegressionBase<T>

GeneralizedAdditiveModel<T>

Implements

IRegression<T>

IFullModel<T, Matrix<T>, Vector<T>>

IModel<Matrix<T>, Vector<T>, ModelMetadata<T>>

IModelSerializer

ICheckpointableModel

IParameterizable<T, Matrix<T>, Vector<T>>

IFeatureAware

IFeatureImportance<T>

ICloneable<IFullModel<T, Matrix<T>, Vector<T>>>

IGradientComputable<T, Matrix<T>, Vector<T>>

IJitCompilable<T>

Inherited Members

RegressionBase<T>.NumOps

RegressionBase<T>.Engine

RegressionBase<T>.Options

RegressionBase<T>.Regularization

RegressionBase<T>.Coefficients

RegressionBase<T>.Intercept

RegressionBase<T>.HasIntercept

RegressionBase<T>.FeatureNames

RegressionBase<T>.ExpectedParameterCount

RegressionBase<T>.SolveSystem(Matrix<T>, Vector<T>)

RegressionBase<T>.GetParameters()

RegressionBase<T>.WithParameters(Vector<T>)

RegressionBase<T>.GetActiveFeatureIndices()

RegressionBase<T>.IsFeatureUsed(int)

RegressionBase<T>.SetParameters(Vector<T>)

RegressionBase<T>.SetActiveFeatureIndices(IEnumerable<int>)

RegressionBase<T>.SetCoefficientsAndIntercept(Vector<T>, T)

RegressionBase<T>.GetFeatureImportance()

RegressionBase<T>.DeepCopy()

RegressionBase<T>.Clone()

RegressionBase<T>.ParameterCount

RegressionBase<T>.DefaultLossFunction

RegressionBase<T>.ComputeGradients(Matrix<T>, Vector<T>, ILossFunction<T>)

RegressionBase<T>.ApplyGradients(Vector<T>, T)

RegressionBase<T>.SaveModel(string)

RegressionBase<T>.LoadModel(string)

RegressionBase<T>.SaveState(Stream)

RegressionBase<T>.LoadState(Stream)

RegressionBase<T>.SupportsJitCompilation

RegressionBase<T>.ExportComputationGraph(List<ComputationNode<T>>)

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Extension Methods

DistributedExtensions.AsDistributedForHighBandwidth<T, TInput, TOutput>(IFullModel<T, TInput, TOutput>, ICommunicationBackend<T>)

DistributedExtensions.AsDistributedForLowBandwidth<T, TInput, TOutput>(IFullModel<T, TInput, TOutput>, ICommunicationBackend<T>)

DistributedExtensions.AsDistributed<T, TInput, TOutput>(IFullModel<T, TInput, TOutput>, ICommunicationBackend<T>)

DistributedExtensions.AsDistributed<T, TInput, TOutput>(IFullModel<T, TInput, TOutput>, IShardingConfiguration<T>)

Remarks

Generalized Additive Models extend linear regression by allowing nonlinear relationships between features and the target variable, while maintaining additivity. Each feature is transformed using basis functions (typically splines), and the model is expressed as a sum of these transformations. This approach balances flexibility and interpretability, as the effect of each feature can be visualized independently.

For Beginners: A Generalized Additive Model is like a more flexible version of linear regression.

Instead of assuming that each feature has a straight-line relationship with the target (like y = mx + b), GAMs allow each feature to have its own curved relationship with the target. The model then adds up all these individual curves to make a prediction.

Think of it this way:

• Linear regression: House price = a × Size + b × Age + c × Location + ...
• GAM: House price = f1(Size) + f2(Age) + f3(Location) + ... Where f1, f2, f3 are curves rather than straight lines

The benefit is that you can:

• Capture more complex patterns in your data
• Still understand how each feature individually affects the prediction
• Visualize the shape of the relationship for each feature

GAMs are a good middle ground between simple linear models and complex "black box" models like neural networks.

Constructors

GeneralizedAdditiveModel(GeneralizedAdditiveModelOptions<T>?, IRegularization<T, Matrix<T>, Vector<T>>?)

Initializes a new instance of the GeneralizedAdditiveModel<T> class.

public GeneralizedAdditiveModel(GeneralizedAdditiveModelOptions<T>? options = null, IRegularization<T, Matrix<T>, Vector<T>>? regularization = null)

Parameters

options GeneralizedAdditiveModelOptions<T>

Optional configuration options for the Generalized Additive Model.

regularization IRegularization<T, Matrix<T>, Vector<T>>

Optional regularization strategy to prevent overfitting.

Remarks

This constructor creates a new Generalized Additive Model with the specified options and regularization strategy. If no options are provided, default values are used. If no regularization is specified, no regularization is applied.

For Beginners: This is how you create a new GAM model.

When creating a GAM, you can specify:

• Options: Controls how many splines to use and their shape
• Regularization: Helps prevent the model from becoming too wiggly or overfitting

If you don't specify these parameters, the model will use reasonable default settings.

Example:

// Create a GAM with default settings
var gam = new GeneralizedAdditiveModel<double>();

// Create a GAM with custom options
var options = new GeneralizedAdditiveModelOptions<double> { 
    NumSplines = 10,
    Degree = 3
};
var customGam = new GeneralizedAdditiveModel<double>(options);

Methods

CalculateFeatureImportances()

Calculates the importance of each feature in the model based on the magnitude of its coefficients.

protected override Vector<T> CalculateFeatureImportances()

Returns

Vector<T>

A vector of feature importance scores.

CreateNewInstance()

Creates a new instance of the GeneralizedAdditiveModel with the same configuration as the current instance.

protected override IFullModel<T, Matrix<T>, Vector<T>> CreateNewInstance()

Returns

IFullModel<T, Matrix<T>, Vector<T>>

A new GeneralizedAdditiveModel instance with the same options and regularization as the current instance.

Remarks

This method creates a new instance of the GeneralizedAdditiveModel with the same configuration options and regularization settings as the current instance. This is useful for model cloning, ensemble methods, or cross-validation scenarios where multiple instances of the same model with identical configurations are needed.

For Beginners: This method creates a fresh copy of the model's blueprint.

When you need multiple versions of the same type of model with identical settings:

• This method creates a new, empty model with the same configuration
• It's like making a copy of a recipe before you start cooking
• The new model has the same settings but no trained data
• This is useful for techniques that need multiple models, like cross-validation

For example, when testing your model on different subsets of data, you'd want each test to use a model with identical settings.

Deserialize(byte[])

Loads a previously serialized Generalized Additive Model from a byte array.

public override void Deserialize(byte[] modelData)

Parameters

modelData byte[]

The byte array containing the serialized model.

Remarks

This method reconstructs a Generalized Additive Model from a byte array that was previously created using the Serialize method. It restores the model's configuration options, basis functions, and learned coefficients, allowing the model to be used for predictions without retraining.

For Beginners: This method loads a previously saved model from a sequence of bytes.

Deserialization allows you to:

• Load a model that was saved earlier
• Use a model without having to retrain it
• Share models between different applications

When you deserialize a model:

• All settings are restored
• The basis functions are reconstructed
• The learned coefficients are recovered
• The model is ready to make predictions immediately

Example:

// Load from a file
byte[] modelData = File.ReadAllBytes("gam.model");

// Deserialize the model
var gam = new GeneralizedAdditiveModel<double>();
gam.Deserialize(modelData);

// Now you can use the model for predictions
var predictions = gam.Predict(newFeatures);

GetModelMetadata()

Gets metadata about the Generalized Additive Model and its configuration.

public override ModelMetadata<T> GetModelMetadata()

Returns

ModelMetadata<T>

A ModelMetadata object containing information about the model.

Remarks

This method returns metadata about the model, including its type, coefficients, feature importances, and configuration options. This information can be useful for model management, comparison, visualization, and documentation purposes.

For Beginners: This method provides information about your GAM model.

The metadata includes:

• The type of model (Generalized Additive Model)
• The coefficients for each basis function
• How important each feature is for predictions
• Configuration settings like the number of splines and their degree

This information is helpful when:

• Comparing different models
• Visualizing how each feature affects predictions
• Documenting your model's configuration
• Troubleshooting model performance

Example:

var metadata = gam.GetModelMetadata();
Console.WriteLine($"Model type: {metadata.ModelType}");
Console.WriteLine($"Number of splines: {metadata.AdditionalInfo["NumSplines"]}");

GetModelType()

Gets the model type of the Generalized Additive Model.

protected override ModelType GetModelType()

Returns

ModelType

The model type enumeration value.

Predict(Matrix<T>)

Predicts target values for the provided input features using the trained Generalized Additive Model.

public override Vector<T> Predict(Matrix<T> input)

Parameters

input Matrix<T>

A matrix where each row represents a sample to predict and each column represents a feature.

Returns

Vector<T>

A vector of predicted values corresponding to each input sample.

Remarks

This method predicts target values for new input data by transforming the input features into basis functions and applying the learned coefficients to compute the predictions.

For Beginners: This method uses your trained model to make predictions on new data.

The prediction process:

1. Each input feature is transformed into the same basis functions used during training
2. These basis functions are multiplied by the coefficients learned during training
3. The results are summed to produce the final prediction

This is similar to how linear regression makes predictions, but with transformed features that allow for non-linear relationships.

Example:

// Make predictions
var predictions = gam.Predict(newFeatures);

Serialize()

Serializes the Generalized Additive Model to a byte array for storage or transmission.

public override byte[] Serialize()

Returns

byte[]

A byte array containing the serialized model.

Remarks

This method converts the Generalized Additive Model into a byte array that can be stored in a file, database, or transmitted over a network. The serialized data includes the model's configuration options, basis functions, and learned coefficients.

For Beginners: This method saves your trained model as a sequence of bytes.

Serialization allows you to:

• Save your model to a file
• Store your model in a database
• Send your model over a network
• Keep your model for later use without having to retrain it

The serialized data includes:

• All the model's settings (like number of splines and their degree)
• The basis functions used to transform features
• The coefficients learned during training

Example:

// Serialize the model
byte[] modelData = gam.Serialize();

// Save to a file
File.WriteAllBytes("gam.model", modelData);

Train(Matrix<T>, Vector<T>)

Trains the Generalized Additive Model using the provided input features and target values.

public override void Train(Matrix<T> x, Vector<T> y)

Parameters

x Matrix<T>

A matrix where each row represents a sample and each column represents a feature.

y Vector<T>

A vector of target values corresponding to each sample in x.

Remarks

This method builds the Generalized Additive Model by creating basis functions (splines) for each feature, and then fitting coefficients to these basis functions to minimize the prediction error.

For Beginners: This method teaches the model how to make predictions using your data.

During training:

1. The model transforms each feature into a set of basis functions (mathematical curves)
2. For each feature, it creates multiple basis functions to capture different aspects of the relationship
3. It then finds the best coefficients (weights) for each basis function
4. These coefficients determine how much each curve contributes to the final prediction

After training, the model can predict values for new data by applying these same transformations and combining them according to the learned coefficients.

Example:

// Train the model
gam.Train(features, targets);