Main Content

# RegressionLinearCoderConfigurer

Coder configurer for linear regression model with high-dimensional data

## Description

A `RegressionLinearCoderConfigurer` object is a coder configurer of a linear regression model (`RegressionLinear`) with high-dimensional data.

A coder configurer offers convenient features to configure code generation options, generate C/C++ code, and update model parameters in the generated code.

• Configure code generation options and specify the coder attributes for linear model parameters by using object properties.

• Generate C/C++ code for the `predict` and `update` functions of the linear regression model by using `generateCode`. Generating C/C++ code requires MATLAB® Coder™.

• Update model parameters in the generated C/C++ code without having to regenerate the code. This feature reduces the effort required to regenerate, redeploy, and reverify C/C++ code when you retrain the linear model with new data or settings. Before updating model parameters, use `validatedUpdateInputs` to validate and extract the model parameters to update.

This flow chart shows the code generation workflow using a coder configurer.

For the code generation usage notes and limitations of a linear regression model, see the Code Generation sections of `RegressionLinear`, `predict`, and `update`.

## Creation

After training a linear regression model by using `fitrlinear`, create a coder configurer for the model by using `learnerCoderConfigurer`. Use the properties of a coder configurer to specify the coder attributes of the `predict` and `update` arguments. Then, use `generateCode` to generate C/C++ code based on the specified coder attributes.

## Properties

expand all

### `predict` Arguments

The properties listed in this section specify the coder attributes of the `predict` function arguments in the generated code.

Coder attributes of the predictor data to pass to the generated C/C++ code for the `predict` function of the linear regression model, specified as a `LearnerCoderInput` object.

When you create a coder configurer by using the `learnerCoderConfigurer` function, the input argument `X` determines the default values of the `LearnerCoderInput` coder attributes:

• `SizeVector` — The default value is the array size of the input `X`.

• If the `Value` attribute of the `ObservationsIn` property for the `RegressionLinearCoderConfigurer` is `'rows'`, then this `SizeVector` value is ```[n p]```, where `n` corresponds to the number of observations and `p` corresponds to the number of predictors.

• If the `Value` attribute of the `ObservationsIn` property for the `RegressionLinearCoderConfigurer` is `'columns'`, then this `SizeVector` value is ```[p n]```.

To switch the elements of `SizeVector` (for example, to change `[n p]` to `[p n]`), modify the `Value` attribute of the `ObservationsIn` property for the `RegressionLinearCoderConfigurer` accordingly. You cannot modify the `SizeVector` value directly.

• `VariableDimensions` — The default value is ```[0 0]```, which indicates that the array size is fixed as specified in `SizeVector`.

You can set this value to `[1 0]` if the `SizeVector` value is `[n p]` or to `[0 1]` if it is `[p n]`, which indicates that the array has variable-size rows and fixed-size columns. For example, `[1 0]` specifies that the first value of `SizeVector` (`n`) is the upper bound for the number of rows, and the second value of `SizeVector` (`p`) is the number of columns.

• `DataType` — This value is `single` or `double`. The default data type depends on the data type of the input `X`.

• `Tunability` — This value must be `true`, meaning that `predict` in the generated C/C++ code always includes predictor data as an input.

You can modify the coder attributes by using dot notation. For example, to generate C/C++ code that accepts predictor data with 100 observations (in rows) of three predictor variables (in columns), specify these coder attributes of `X` for the coder configurer `configurer`:

```configurer.X.SizeVector = [100 3]; configurer.X.DataType = 'double'; configurer.X.VariableDimensions = [0 0];```
```[0 0]``` indicates that the first and second dimensions of `X` (number of observations and number of predictor variables, respectively) have fixed sizes.

To allow the generated C/C++ code to accept predictor data with up to 100 observations, specify these coder attributes of `X`:

```configurer.X.SizeVector = [100 3]; configurer.X.DataType = 'double'; configurer.X.VariableDimensions = [1 0];```
```[1 0]``` indicates that the first dimension of `X` (number of observations) has a variable size and the second dimension of `X` (number of predictor variables) has a fixed size. The specified number of observations, 100 in this example, becomes the maximum allowed number of observations in the generated C/C++ code. To allow any number of observations, specify the bound as `Inf`.

Coder attributes of the predictor data observation dimension (`'ObservationsIn'` name-value pair argument of `predict`), specified as an `EnumeratedInput` object.

When you create a coder configurer by using the `learnerCoderConfigurer` function, the `'ObservationsIn'` name-value pair argument determines the default values of the `EnumeratedInput` coder attributes:

• `Value` — The default value is the predictor data observation dimension you use when creating the coder configurer, specified as `'rows'` or `'columns'`. If you do not specify `'ObservationsIn'` when creating the coder configurer, the default value is `'rows'`.

• `SelectedOption` — This value is always `'Built-in'`. This attribute is read-only.

• `BuiltInOptions` — Cell array of `'rows'` and `'columns'`. This attribute is read-only.

• `IsConstant` — This value must be `true`.

• `Tunability`The default value is `false` if you specify `'ObservationsIn','rows'` when creating the coder configurer, and `true` if you specify `'ObservationsIn','columns'`. If you set `Tunability` to `false`, the software sets `Value` to `'rows'`. If you specify other attribute values when `Tunability` is `false`, the software sets `Tunability` to `true`.

Number of output arguments to return from the generated C/C++ code for the `predict` function of the linear regression model, specified as 1. `predict` returns `YHat` (predicted responses) in the generated C/C++ code.

The `NumOutputs` property is equivalent to the `'-nargout'` compiler option of `codegen` (MATLAB Coder). This option specifies the number of output arguments in the entry-point function of code generation. The object function `generateCode` generates two entry-point functions—`predict.m` and `update.m` for the `predict` and `update` functions of a linear regression model, respectively—and generates C/C++ code for the two entry-point functions. The specified value for the `NumOutputs` property corresponds to the number of output arguments in the entry-point function `predict.m`.

Data Types: `double`

### `update` Arguments

The properties listed in this section specify the coder attributes of the `update` function arguments in the generated code. The `update` function takes a trained model and new model parameters as input arguments, and returns an updated version of the model that contains the new parameters. To enable updating the parameters in the generated code, you need to specify the coder attributes of the parameters before generating code. Use a `LearnerCoderInput` object to specify the coder attributes of each parameter. The default attribute values are based on the model parameters in the input argument `Mdl` of `learnerCoderConfigurer`.

Coder attributes of the linear predictor coefficients (`Beta` of a linear regression model), specified as a `LearnerCoderInput` object.

The default attribute values of the `LearnerCoderInput` object are based on the input argument `Mdl` of `learnerCoderConfigurer`:

• `SizeVector` — This value must be `[p 1]`, where `p` is the number of predictors in `Mdl`.

• `VariableDimensions` — This value must be `[0 0]`, indicating that the array size is fixed as specified in `SizeVector`.

• `DataType` — This value is `'single'` or `'double'`. The default data type is consistent with the data type of the training data you use to train `Mdl`.

• `Tunability` — This value must be `true`.

Coder attributes of the bias term (`Bias` of a linear regression model), specified as a `LearnerCoderInput` object.

The default attribute values of the `LearnerCoderInput` object are based on the input argument `Mdl` of `learnerCoderConfigurer`:

• `SizeVector` — This value must be `[1 1]`.

• `VariableDimensions` — This value must be `[0 0]`, indicating that the array size is fixed as specified in `SizeVector`.

• `DataType` — This value is `'single'` or `'double'`. The default data type is consistent with the data type of the training data you use to train `Mdl`.

• `Tunability` — This value must be `true`.

### Other Configurer Options

File name of the generated C/C++ code, specified as a character vector.

The object function `generateCode` of `RegressionLinearCoderConfigurer` generates C/C++ code using this file name.

The file name must not contain spaces because they can lead to code generation failures in certain operating system configurations. Also, the name must be a valid MATLAB function name.

After creating the coder configurer `configurer`, you can specify the file name by using dot notation.

`configurer.OutputFileName = 'myModel';`

Data Types: `char`

Verbosity level, specified as `true` (logical 1) or `false` (logical 0). The verbosity level controls the display of notification messages at the command line.

ValueDescription
`true` (logical 1)The software displays notification messages when your changes to the coder attributes of a parameter result in changes for other dependent parameters.
`false` (logical 0)The software does not display notification messages.

To enable updating machine learning model parameters in the generated code, you need to configure the coder attributes of the parameters before generating code. The coder attributes of parameters are dependent on each other, so the software stores the dependencies as configuration constraints. If you modify the coder attributes of a parameter by using a coder configurer, and the modification requires subsequent changes to other dependent parameters to satisfy configuration constraints, then the software changes the coder attributes of the dependent parameters. The verbosity level determines whether or not the software displays notification messages for these subsequent changes.

After creating the coder configurer `configurer`, you can modify the verbosity level by using dot notation.

`configurer.Verbose = false;`

Data Types: `logical`

### Options for Code Generation Customization

To customize the code generation workflow, use the `generateFiles` function and the following three properties with `codegen` (MATLAB Coder), instead of using the `generateCode` function.

After generating the two entry-point function files (`predict.m` and `update.m`) by using the `generateFiles` function, you can modify these files according to your code generation workflow. For example, you can modify the `predict.m` file to include data preprocessing, or you can add these entry-point functions to another code generation project. Then, you can generate C/C++ code by using the `codegen` (MATLAB Coder) function and the `codegen` arguments appropriate for the modified entry-point functions or code generation project. Use the three properties described in this section as a starting point to set the `codegen` arguments.

This property is read-only.

`codegen` (MATLAB Coder) arguments, specified as a cell array.

This property enables you to customize the code generation workflow. Use the `generateCode` function if you do not need to customize your workflow.

Instead of using `generateCode` with the coder configurer `configurer`, you can generate C/C++ code as follows:

```generateFiles(configurer) cgArgs = configurer.CodeGenerationArguments; codegen(cgArgs{:})```
If you customize the code generation workflow, modify `cgArgs` accordingly before calling `codegen`.

If you modify other properties of `configurer`, the software updates the `CodeGenerationArguments` property accordingly.

Data Types: `cell`

This property is read-only.

List of tunable input arguments of the entry-point function `predict.m` for code generation, specified as a cell array. The cell array contains another cell array that includes `coder.PrimitiveType` (MATLAB Coder) objects and `coder.Constant` (MATLAB Coder) objects.

If you modify the coder attributes of `predict` arguments, then the software updates the corresponding objects accordingly. If you specify the `Tunability` attribute as `false`, then the software removes the corresponding objects from the `PredictInputs` list.

The cell array in `PredictInputs` is equivalent to `configurer.CodeGenerationArguments{6}` for the coder configurer `configurer`.

Data Types: `cell`

This property is read-only.

List of the tunable input arguments of the entry-point function `update.m` for code generation, specified as a cell array of a structure including `coder.PrimitiveType` (MATLAB Coder) objects. Each `coder.PrimitiveType` object includes the coder attributes of a tunable machine learning model parameter.

If you modify the coder attributes of a model parameter by using the coder configurer properties (`update` Arguments properties), then the software updates the corresponding `coder.PrimitiveType` object accordingly. If you specify the `Tunability` attribute of a machine learning model parameter as `false`, then the software removes the corresponding `coder.PrimitiveType` object from the `UpdateInputs` list.

The structure in `UpdateInputs` is equivalent to `configurer.CodeGenerationArguments{3}` for the coder configurer `configurer`.

Data Types: `cell`

## Object Functions

 `generateCode` Generate C/C++ code using coder configurer `generateFiles` Generate MATLAB files for code generation using coder configurer `validatedUpdateInputs` Validate and extract machine learning model parameters to update

## Examples

collapse all

Train a machine learning model, and then generate code for the `predict` and `update` functions of the model by using a coder configurer.

Simulate 10,000 observations from the model

`$y={x}_{100}+2{x}_{200}+e.$`

• $X={x}_{1},...,{x}_{1000}$ is a 10,000-by-1000 numeric matrix with standard normal elements.

• $e$ is a random normal error with mean 0 and standard deviation 0.3.

```rng('default') % For reproducibility n = 10000; p = 1000; X = randn(n,p); Y = X(:,100) + 2*X(:,200) + 0.3*randn(n,1);```

Train a linear regression model using the simulated data. Pass the transposed predictor matrix `Xnew` to `fitrlinear`, and use the `'ObservationsIn'` name-value pair argument to specify that the columns of `Xnew` correspond to observations.

```Xnew = X'; Mdl = fitrlinear(Xnew,Y,'ObservationsIn','columns');```

`Mdl` is a `RegressionLinear` object.

Create a coder configurer for the `RegressionLinear` model by using `learnerCoderConfigurer`. Specify the predictor data `Xnew`, and use the `'ObservationsIn'` name-value pair argument to specify the observation dimension of `Xnew`. The `learnerCoderConfigurer` function uses these input arguments to configure the coder attributes of the corresponding input arguments of `predict`.

`configurer = learnerCoderConfigurer(Mdl,Xnew,'ObservationsIn','columns')`
```configurer = RegressionLinearCoderConfigurer with properties: Update Inputs: Beta: [1x1 LearnerCoderInput] Bias: [1x1 LearnerCoderInput] Predict Inputs: X: [1x1 LearnerCoderInput] ObservationsIn: [1x1 EnumeratedInput] Code Generation Parameters: NumOutputs: 1 OutputFileName: 'RegressionLinearModel' Properties, Methods ```

`configurer` is a `RegressionLinearCoderConfigurer` object, which is a coder configurer of a `RegressionLinear` object.

To generate C/C++ code, you must have access to a C/C++ compiler that is configured properly. MATLAB Coder locates and uses a supported, installed compiler. You can use `mex` `-setup` to view and change the default compiler. For more details, see Change Default Compiler.

Generate code for the `predict` and `update` functions of the linear regression model (`Mdl`) with default settings.

`generateCode(configurer)`
```generateCode creates these files in output folder: 'initialize.m', 'predict.m', 'update.m', 'RegressionLinearModel.mat' Code generation successful. ```

The `generateCode` function completes these actions:

• Generate the MATLAB files required to generate code, including the two entry-point functions `predict.m` and `update.m` for the `predict` and `update` functions of `Mdl`, respectively.

• Create a MEX function named `RegressionLinearModel` for the two entry-point functions.

• Create the code for the MEX function in the `codegen\mex\RegressionLinearModel` folder.

• Copy the MEX function to the current folder.

Display the contents of the `predict.m`, `update.m`, and `initialize.m` files by using the `type` function.

`type predict.m`
```function varargout = predict(X,varargin) %#codegen % Autogenerated by MATLAB, 23-Feb-2021 19:18:39 [varargout{1:nargout}] = initialize('predict',X,varargin{:}); end ```
`type update.m`
```function update(varargin) %#codegen % Autogenerated by MATLAB, 23-Feb-2021 19:18:39 initialize('update',varargin{:}); end ```
`type initialize.m`
```function [varargout] = initialize(command,varargin) %#codegen % Autogenerated by MATLAB, 23-Feb-2021 19:18:39 coder.inline('always') persistent model if isempty(model) model = loadLearnerForCoder('RegressionLinearModel.mat'); end switch(command) case 'update' % Update struct fields: Beta % Bias model = update(model,varargin{:}); case 'predict' % Predict Inputs: X, ObservationsIn X = varargin{1}; if nargin == 2 [varargout{1:nargout}] = predict(model,X); else PVPairs = cell(1,nargin-2); for i = 1:nargin-2 PVPairs{1,i} = varargin{i+1}; end [varargout{1:nargout}] = predict(model,X,PVPairs{:}); end end end ```

Train a linear regression model using a partial data set, and create a coder configurer for the model. Use the properties of the coder configurer to specify coder attributes of the linear regression model parameters. Use the object function of the coder configurer to generate C code that predicts responses for new predictor data. Then retrain the model using the entire data set, and update parameters in the generated code without regenerating the code.

Train Model

Simulate 10,000 observations from the model

`$y={x}_{100}+2{x}_{200}+e.$`

• $X={x}_{1},...,{x}_{1000}$ is a 10,000-by-1000 numeric matrix with standard normal elements.

• $e$ is a random normal error with mean 0 and standard deviation 0.3.

```rng('default') % For reproducibility n = 10000; p = 1000; X = randn(n,p); Y = X(:,100) + 2*X(:,200) + 0.3*randn(n,1);```

Train a linear regression model using the first 500 observations. Transpose the predictor data, and use the `'ObservationsIn'` name-value pair argument to specify that the columns of `XTrain` correspond to observations.

```XTrain = X(1:500,:)'; YTrain = Y(1:500); Mdl = fitrlinear(XTrain,YTrain,'ObservationsIn','columns');```

`Mdl` is a `RegressionLinear` object.

Create Coder Configurer

Create a coder configurer for the `RegressionLinear` model by using `learnerCoderConfigurer`. Specify the predictor data `XTrain`, and use the `'ObservationsIn'` name-value pair argument to specify the observation dimension of `XTrain`. The `learnerCoderConfigurer` function uses these input arguments to configure the coder attributes of the corresponding input arguments of `predict`.

`configurer = learnerCoderConfigurer(Mdl,XTrain,'ObservationsIn','columns');`

`configurer` is a `RegressionLinearCoderConfigurer` object, which is a coder configurer of a `RegressionLinear` object.

Specify Coder Attributes of Parameters

Specify the coder attributes of the linear regression model parameters so that you can update the parameters in the generated code after retraining the model. This example specifies the coder attributes of the predictor data that you want to pass to the generated code.

Specify the coder attributes of the `X` property of `configurer` so that the generated code accepts any number of observations. Modify the `SizeVector` and `VariableDimensions` attributes. The `SizeVector` attribute specifies the upper bound of the predictor data size, and the `VariableDimensions` attribute specifies whether each dimension of the predictor data has a variable size or fixed size.

```configurer.X.SizeVector = [1000 Inf]; configurer.X.VariableDimensions```
```ans = 1x2 logical array 0 1 ```

The size of the first dimension is the number of predictor variables. This value must be fixed for a machine learning model. Because the predictor data contains 1000 predictors, the value of the `SizeVector` attribute must be 1000 and the value of the `VariableDimensions` attribute must be `0`.

The size of the second dimension is the number of observations. Setting the value of the `SizeVector` attribute to `Inf` causes the software to change the value of the `VariableDimensions` attribute to `1`. In other words, the upper bound of the size is `Inf` and the size is variable, meaning that the predictor data can have any number of observations. This specification is convenient if you do not know the number of observations when generating code.

The order of the dimensions in `SizeVector` and `VariableDimensions` depends on the coder attributes of `ObservationsIn`.

`configurer.ObservationsIn`
```ans = EnumeratedInput with properties: Value: 'columns' SelectedOption: 'Built-in' BuiltInOptions: {'rows' 'columns'} IsConstant: 1 Tunability: 1 ```

When the `Value` attribute of the `ObservationsIn` property is `'columns'`, the first dimension of the `SizeVector` and `VariableDimensions` attributes of `X` corresponds to the number of predictors, and the second dimension corresponds to the number of observations. When the `Value` attribute of `ObservationsIn` is `'rows'`, the order of the dimensions is switched.

Generate Code

To generate C/C++ code, you must have access to a C/C++ compiler that is configured properly. MATLAB Coder locates and uses a supported, installed compiler. You can use `mex` `-setup` to view and change the default compiler. For more details, see Change Default Compiler.

Generate code for the `predict` and `update` functions of the linear regression model (`Mdl`).

`generateCode(configurer)`
```generateCode creates these files in output folder: 'initialize.m', 'predict.m', 'update.m', 'RegressionLinearModel.mat' Code generation successful. ```

The `generateCode` function completes these actions:

• Generate the MATLAB files required to generate code, including the two entry-point functions `predict.m` and `update.m` for the `predict` and `update` functions of `Mdl`, respectively.

• Create a MEX function named `RegressionLinearModel` for the two entry-point functions.

• Create the code for the MEX function in the `codegen\mex\RegressionLinearModel` folder.

• Copy the MEX function to the current folder.

Verify Generated Code

Pass some predictor data to verify whether the `predict` function of `Mdl` and the `predict` function in the MEX function return the same predicted responses. To call an entry-point function in a MEX function that has more than one entry point, specify the function name as the first input argument.

```YHat = predict(Mdl,XTrain,'ObservationsIn','columns'); YHat_mex = RegressionLinearModel('predict',XTrain,'ObservationsIn','columns');```

Compare `YHat` and `YHat_mex`.

`max(abs(YHat-YHat_mex))`
```ans = 0 ```

In general, `YHat_mex` might include round-off differences compared to `YHat`. In this case, the comparison confirms that `YHat` and `YHat_mex` are equal.

Retrain Model and Update Parameters in Generated Code

Retrain the model using the entire data set.

`retrainedMdl = fitrlinear(X',Y,'ObservationsIn','columns');`

Extract parameters to update by using `validatedUpdateInputs`. This function detects the modified model parameters in `retrainedMdl` and validates whether the modified parameter values satisfy the coder attributes of the parameters.

`params = validatedUpdateInputs(configurer,retrainedMdl);`

Update parameters in the generated code.

`RegressionLinearModel('update',params)`

Verify Generated Code

Compare the outputs from the `predict` function of `retrainedMdl` and the `predict` function in the updated MEX function.

```YHat = predict(retrainedMdl,X','ObservationsIn','columns'); YHat_mex = RegressionLinearModel('predict',X','ObservationsIn','columns'); max(abs(YHat-YHat_mex))```
```ans = 0 ```

The comparison confirms that `YHat` and `YHat_mex` are equal.

expand all

## See Also

### Topics

Introduced in R2019b

Download ebook