Class NegativeBinomialRegression<T>

Namespace

AiDotNet.Regression

Assembly

AiDotNet.dll

Represents a negative binomial regression model for count data that may exhibit overdispersion.

public class NegativeBinomialRegression<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>

NegativeBinomialRegression<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>.GetModelMetadata()

RegressionBase<T>.CalculateFeatureImportances()

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

Negative binomial regression is a type of generalized linear model used for modeling count data when the variance exceeds the mean (overdispersion), which violates the assumption of Poisson regression. It extends Poisson regression by adding a dispersion parameter that accounts for the extra variance in the data. The model uses a log link function to ensure that predictions are always positive, as required for count data.

For Beginners: Negative binomial regression is a special model for predicting counts when your data shows more variation than expected.

Think of it like predicting the number of customer service calls a business receives each day:

• A simple model might assume consistent variation around the average (Poisson model)
• But real data often shows much more variation - some days have way more calls than expected
• Negative binomial regression handles this "extra randomness" by including a special adjustment (dispersion parameter)

For example, the model might predict that a business receives 15 calls per day on average, but also accounts for the fact that some days might have 5 calls while others have 40, which is more extreme variation than simpler models would expect.

Constructors

NegativeBinomialRegression(NegativeBinomialRegressionOptions<T>?, IRegularization<T, Matrix<T>, Vector<T>>?)

Initializes a new instance of the NegativeBinomialRegression<T> class with optional custom options and regularization.

public NegativeBinomialRegression(NegativeBinomialRegressionOptions<T>? options = null, IRegularization<T, Matrix<T>, Vector<T>>? regularization = null)

Parameters

options NegativeBinomialRegressionOptions<T>

Custom options for the negative binomial regression algorithm. If null, default options are used.

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

Regularization method to prevent overfitting. If null, no regularization is applied.

Remarks

This constructor creates a new negative binomial regression model with the specified options and regularization. If no options are provided, default values are used. Regularization helps prevent overfitting by penalizing large coefficient values. The dispersion parameter is initially set to 1, which is equivalent to a Poisson model.

For Beginners: This creates a new negative binomial regression model with your chosen settings.

When creating the model:

• You can provide custom settings (options) or use the defaults
• You can add regularization, which helps prevent the model from memorizing the training data
• The model starts with a dispersion value of 1 (standard amount of randomness)

The model will adjust the dispersion parameter during training based on the actual variation in your data.

Methods

CreateNewInstance()

Creates a new instance of the Negative Binomial Regression model with the same configuration.

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

Returns

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

A new instance of the Negative Binomial Regression model.

Remarks

This method creates a deep copy of the current Negative Binomial Regression model, including its options, coefficients, intercept, dispersion parameter, and regularization settings. The new instance is completely independent of the original, allowing modifications without affecting the original model.

For Beginners: This method creates an exact copy of your trained model.

Think of it like making a perfect duplicate:

• It copies all the configuration settings (like maximum iterations and tolerance)
• It preserves the coefficients (the importance values for each feature)
• It maintains the intercept (the starting point or base value)
• It keeps the dispersion parameter (the "extra randomness adjuster")

Creating a copy is useful when you want to:

• Create a backup before further modifying the model
• Create variations of the same model for different purposes
• Share the model with others while keeping your original intact

Exceptions

InvalidOperationException

Thrown when the creation fails or required components are null.

Deserialize(byte[])

Deserializes the negative binomial regression model from a byte array.

public override void Deserialize(byte[] modelData)

Parameters

modelData byte[]

A byte array containing the serialized model data.

Remarks

This method restores a negative binomial regression model from a serialized byte array, reconstructing its parameters and configuration. This allows a previously trained model to be loaded from storage or after being received over a network.

For Beginners: This method rebuilds the model from a saved format.

Deserialization:

• Takes a sequence of bytes that represents a model
• Reconstructs the original model with all its learned parameters
• Restores the coefficients, intercept, dispersion parameter, and options
• Allows you to use a previously trained model without retraining

It's like unpacking a model that was packed up for storage or sharing, so you can use it again exactly as it was before.

GetModelType()

Gets the type of regression model.

protected override ModelType GetModelType()

Returns

ModelType

The model type, in this case, NegativeBinomialRegression.

Remarks

This method returns an enumeration value indicating that this is a negative binomial regression model. This is used for type identification when working with different regression models in a unified manner.

For Beginners: This method simply identifies what kind of model this is.

It returns a label (NegativeBinomialRegression) that:

• Identifies this specific type of model
• Helps other code handle the model appropriately
• Is used when saving or loading models

It's like a name tag that lets other parts of the program know what kind of model they're working with.

Predict(Matrix<T>)

Makes predictions for new data points using the trained negative binomial regression model.

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

Parameters

X Matrix<T>

The feature matrix where each row is a sample to predict.

Returns

Vector<T>

A vector containing the predicted count values.

Remarks

This method makes predictions by applying the learned coefficients to the input features and transforming the result with the exponential function. This ensures that the predictions are always positive, as required for count data. The predictions represent the expected counts based on the input features.

For Beginners: This is where the model makes predictions on new data.

The prediction process:

1. For each data point, multiply each feature by its corresponding coefficient
2. Add all these products together (plus the intercept)
3. Apply the exponential function to ensure the result is positive
4. The final value is the predicted count

For example, if predicting daily customer service calls based on day of week, staffing level, and weather conditions, the model combines these factors mathematically to estimate the expected number of calls.

Serialize()

Serializes the negative binomial regression model to a byte array for storage or transmission.

public override byte[] Serialize()

Returns

byte[]

A byte array containing the serialized model data.

Remarks

This method converts the entire negative binomial regression model, including its parameters and configuration, into a byte array that can be stored in a file or database, or transmitted over a network. The model can later be restored using the Deserialize method.

For Beginners: This method saves the model to a format that can be stored or shared.

Serialization:

• Converts all the model's data into a sequence of bytes
• Preserves the model's coefficients, intercept, dispersion parameter, and options
• Allows you to save the trained model to a file
• Lets you load the model later without having to retrain it

It's like taking a snapshot of the model that you can use later or share with others.

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

Trains the negative binomial regression model using the provided features and target values.

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

Parameters

X Matrix<T>

The feature matrix where each row is a sample and each column is a feature.

y Vector<T>

The target vector containing the count values to predict.

Remarks

This method trains the negative binomial regression model using iteratively reweighted least squares (IRLS), which is a form of Fisher scoring. It iteratively updates the coefficients by solving a weighted least squares problem until convergence. After finding the optimal coefficients, it updates the dispersion parameter to account for the observed variance in the data.

For Beginners: This is where the model learns from your data.

During training:

1. The model starts with initial guesses for the coefficients
2. It calculates predictions based on current coefficients
3. It computes how much to adjust each coefficient to improve predictions
4. It updates the coefficients and checks if they've stabilized
5. Steps 2-4 repeat until the changes become very small or a maximum number of iterations is reached
6. Finally, it calculates the dispersion parameter to account for extra variation in the data

This process finds the best coefficients for predicting count data while accounting for the extra randomness that's often present in real-world counts.

Exceptions

ArgumentException

Thrown when the number of rows in X does not match the length of y.