gather

Gather properties of Statistics and Machine Learning Toolbox object from GPU

Since R2020b

Syntax

gatheredObj = gather(obj)

[gatheredObj1,gatheredObj2,...,gatheredObjn] = gather(obj1,obj2,...,objn)

Description

gatheredObj = gather(obj) gathers all properties of the input object obj and returns the gathered object gatheredObj. All properties of the output object are stored in the local workspace.

Use gather to create a Statistics and Machine Learning Toolbox™ object with properties stored in the local workspace from an object fitted using data stored as a GPU array. For more details on GPU arrays, see gpuArray (Parallel Computing Toolbox). Using a GPU requires Parallel Computing Toolbox™ and a supported GPU device. For information on supported devices, see GPU Computing Requirements (Parallel Computing Toolbox).

[gatheredObj1,gatheredObj2,...,gatheredObjn] = gather(obj1,obj2,...,objn) gathers the properties of multiple objects obj1,obj2,...,objn and returns the corresponding gathered objects gatheredObj1,gatheredObj2,...,gatheredObjn. The number of input arguments and output arguments must match.

Examples

Gather Properties of Linear Regression Model

Gather the properties of a linear regression model fitted with GPU array data.

Load the carsmall data set. Create X as a numeric matrix that contains three car performance metrics. Create Y as a numeric vector that contains the corresponding miles per gallon.

load carsmall
X = [Weight,Horsepower,Acceleration];
Y = MPG;

Convert the predictor X and response Y to gpuArray (Parallel Computing Toolbox) objects.

X = gpuArray(X);
Y = gpuArray(Y);

Fit a linear regression model mdl by using fitlm.

mdl = fitlm(X,Y);

Display the coefficients of mdl and determine whether the estimated coefficient values are GPU arrays.

mdl.Coefficients

ans=4×4 table
                    Estimate        SE          tStat        pValue  
                   __________    _________    _________    __________

    (Intercept)        47.977       3.8785        12.37    4.8957e-21
    x1             -0.0065416    0.0011274      -5.8023    9.8742e-08
    x2              -0.042943     0.024313      -1.7663       0.08078
    x3              -0.011583      0.19333    -0.059913       0.95236

isgpuarray(mdl.Coefficients.Estimate)

ans = logical
   1

Gather the properties of the linear regression model.

gatheredMdl = gather(mdl);

Display the coefficients of gatheredMdl and determine whether the estimated coefficient values are GPU arrays.

gatheredMdl.Coefficients

ans=4×4 table
                    Estimate        SE          tStat        pValue  
                   __________    _________    _________    __________

    (Intercept)        47.977       3.8785        12.37    4.8957e-21
    x1             -0.0065416    0.0011274      -5.8023    9.8742e-08
    x2              -0.042943     0.024313      -1.7663       0.08078
    x3              -0.011583      0.19333    -0.059913       0.95236

isgpuarray(gatheredMdl.Coefficients.Estimate)

ans = logical
   0

Gather Properties of Multiple Models

Gather the properties of a linear regression model and a k-nearest neighbor classifier. Both models are fitted using GPU array data.

Load the carsmall data set. Create X as a numeric matrix that contains three car performance metrics, and convert the predictor X to a gpuArray object.

load carsmall
X = [Weight,Horsepower,Acceleration];
X = gpuArray(X);

Fit a linear regression model of MPG (miles per gallon) as a function of the predictor X.

mdlLinear = fitlm(X,MPG);

Train a 3-nearest neighbor classifier using the predictor X and the classes Cylinders. Standardize the noncategorical predictor data.

mdlKNN = fitcknn(X,Cylinders,'NumNeighbors',3,'Standardize',1);

Gather the properties of the mdLinear and mdlKNN models.

[gMdlLinear,gMdlKNN] = gather(mdlLinear,mdlKNN);

Determine whether the p-value of the Durbin-Watson test for the regression model mdlLinear is a GPU array.

isgpuarray(dwtest(mdlLinear))

ans = logical
   1

Determine whether the p-value of the Durbin-Watson test for the gathered regression model gMdlLinear is a GPU array.

isgpuarray(dwtest(gMdlLinear))

ans = logical
   0

Determine whether the resubstitution loss of the classifier mdlKNN is a GPU array.

isgpuarray(resubLoss(mdlKNN))

ans = logical
   1

Determine whether the resubstitution loss of the gathered classifier gMdlKNN is a GPU array.

isgpuarray(resubLoss(gMdlKNN))

ans = logical
   1

Input Arguments

obj — Object fitted with GPU arrays or a gpuArray object

regression model object | classification model object | probability distribution object | cvpartition object | gpuArray object

Object fitted with GPU arrays or a gpuArray object, specified as a regression model object, classification model object, probability distribution object, cvpartition object, or gpuArray (Parallel Computing Toolbox) object. A gpuArray object represents an array stored on the GPU.

For more information on the Statistics and Machine Learning Toolbox objects supported by gather, see Supported Regression Models, Supported Classification Models, and Supported Probability Distribution Objects.

More About

Supported Regression Models

The gather function can gather the properties of the following regression model objects.

Model Type	Full or Compact Model Object	Model Creation Function
Ensemble of learners for regression	RegressionEnsemble, CompactRegressionEnsemble, or RegressionBaggedEnsemble	fitrensemble or RegressionEnsemble object function compact
Full generalized linear regression model	GeneralizedLinearModel or CompactGeneralizedLinearModel	fitglm or GeneralizedLinearModel object function compact
Full linear regression model	LinearModel or CompactLinearModel	fitlm or LinearModel object function compact
Regression linear model	RegressionLinear	fitrlinear
Regression neural network model	RegressionNeuralNetwork, CompactRegressionNeuralNetwork, or RegressionPartitionedNeuralNetwork	fitrnet
Regression tree model	RegressionTree or CompactRegressionTree	fitrtree or RegressionTree object function compact
Support vector machine regression model	RegressionSVM, CompactRegressionSVM, or RegressionPartitionedSVM	fitrsvm
Cross-validated regression ensemble	RegressionPartitionedEnsemble	fitrensemble
Cross-validated regression linear model	RegressionPartitionedLinear	fitrlinear
Cross-validated regression model	RegressionPartitionedModel	fitrtree

If you want to create a compact model fitted with GPU arrays, the input argument mdl of compact must be a full model object fitted with GPU array input arguments.

Supported Classification Models

The gather function can gather the properties of the following classification model objects.

Model Type	Full or Compact Model Object	Model Creation Function
Multiclass model for support vector machines or other classifiers	ClassificationECOC or CompactClassificationECOC	fitcecoc or ClassificationECOC object function compact
Ensemble of learners for classification	ClassificationEnsemble, CompactClassificationEnsemble, or ClassificationBaggedEnsemble	fitcensemble or ClassificationEnsemble object function compact
k-nearest neighbor classifier	ClassificationKNN	fitcknn
Support vector machine (SVM) classifier	ClassificationSVM or CompactClassificationSVM	fitcsvm or ClassificationSVM object function compact
Classification neural network model	ClassificationNeuralNetwork or CompactClassificationNeuralNetwork	fitcnet
Binary decision tree for multiclass classification	ClassificationTree or CompactClassificationTree	fitctree or ClassificationTree object function compact
Cross-validated ECOC model	ClassificationPartitionedECOC	fitcecoc
Cross-validated classification ensemble	ClassificationPartitionedEnsemble	fitcensemble
Cross-validated classification model	ClassificationPartitionedModel	fitcknn, fitcsvm, fitcnet, or fitctree

If you want to create a compact model fitted with GPU arrays, the input argument mdl of compact must be a full model object fitted with GPU array input arguments.

Supported Probability Distribution Objects

The gather function can gather the properties of the following probability distribution objects.

Probability Distribution	Probability Distribution Object	Object Creation Function
Beta distribution	BetaDistribution	fitdist with distname specified as 'Beta'
Binomial distribution	BinomialDistribution	fitdist with distname specified as 'Binomial'
Birnbaum-Saunders distribution	BirnbaumSaundersDistribution	fitdist with distname specified as 'BirnbaumSaunders'
Burr distribution	BurrDistribution	fitdist with distname specified as 'Burr'
Exponential distribution	ExponentialDistribution	fitdist with distname specified as 'Exponential'
Extreme Value distribution	ExtremeValueDistribution	fitdist with distname specified as 'ExtremeValue'
Gamma distribution	GammaDistribution	fitdist with distname specified as 'Gamma'
Generalized Extreme Value distribution	GeneralizedExtremeValueDistribution	fitdist with distname specified as 'GeneralizedExtremeValue'
Generalized Pareto distribution	GeneralizedParetoDistribution	fitdist with distname specified as 'GeneralizedPareto'
Half-normal distribution	HalfNormalDistribution	fitdist with distname specified as 'HalfNormal'
Inverse Gaussian distribution	InverseGaussianDistribution	fitdist with distname specified as 'InverseGaussian'
Kernel distribution	KernelDistribution	fitdist with distname specified as 'Kernel'
Logistic distribution	LogisticDistribution	fitdist with distname specified as 'Logistic'
Loglogistic distribution	LoglogisticDistribution	fitdist with distname specified as 'Loglogistic'
Lognormal distribution	LognormalDistribution	fitdist with distname specified as 'Lognormal'
Nakagami distribution	NakagamiDistribution	fitdist with distname specified as 'Nakagami'
Negative Binomial distribution	NegativeBinomialDistribution	fitdist with distname specified as 'NegativeBinomial'
Normal distribution	NormalDistribution	fitdist with distname specified as 'Normal'
Poisson distribution	PoissonDistribution	fitdist with distname specified as 'Poisson'
Rayleigh distribution	RayleighDistribution	fitdist with distname specified as 'Rayleigh'
t Location-Scale distribution	tLocationScaleDistribution	fitdist with distname specified as 'tLocationScale'
Weibull distribution	WeibullDistribution	fitdist with distname specified as 'Weibull'

Tips

• Gathering GPU arrays can be costly and is generally not necessary unless you need to use the results with functions that do not support GPU arrays. For the complete list of Statistics and Machine Learning Toolbox functions that accept GPU arrays, see Function List (GPU Arrays).

• You can also call gather on other data types, such as distributed, codistributed, or tall arrays. If the data type does not support gathering, then gather has no effect.

Extended Capabilities

Tall Arrays

Calculate with arrays that have more rows than fit in memory.

The gather function supports tall arrays with the following usage notes and limitations:

• This function supports only cvpartition objects and unevaluated tall arrays.

For more information, see Tall Arrays.

GPU Arrays

Accelerate code by running on a graphics processing unit (GPU) using Parallel Computing Toolbox™.

This function fully supports GPU arrays. For more information, see Run MATLAB Functions on a GPU (Parallel Computing Toolbox).

Version History

Introduced in R2020b

R2024b: Create regression models (requires Parallel Computing Toolbox)

You can now use the gather function to create a gathered RegressionNeuralNetwork, CompactRegressionNeuralNetwork, or RegressionPartitionedNeuralNetwork model object from an equivalent object fitted with GPU array data.

R2024b: Create classification models

You can now use the gather function to create a gathered ClassificationNeuralNetwork or CompactClassificationNeuralNetwork model object from an equivalent object fitted with GPU array data. You can also create a gathered ClassificationPartitionedModel model object from an equivalent object that was fitted with GPU array data using the fitcnet and crossval functions.

R2024a: Create RegressionLinear and RegressionPartitionedLinear models

You can now use the gather function to create a gathered RegressionLinear or RegressionPartitionedLinear model object from an equivalent object fitted with GPU array data.

R2024a: Create ClassificationLinear and ClassificationPartitionedLinear models

You can use the gather function to create a ClassificationLinear or ClassificationPartitionedLinear model object from an equivalent object fitted with GPU array data.

R2023a: gather supports RegressionSVM, CompactRegressionSVM, and RegressionPartitionedSVM models

Starting in R2023a, you can use the gather function to create a RegressionSVM, CompactRegressionSVM, or RegressionPartitionedSVM model object from an equivalent object fitted with GPU array data.