Main Content

gather

Gather properties of Statistics and Machine Learning Toolbox object from GPU

Since R2020b

    Description

    example

    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).

    example

    [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

    collapse all

    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 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

    collapse all

    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

    collapse all

    Supported Regression Models

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

    Model TypeFull or Compact Model ObjectModel Creation Function
    Ensemble of learners for regressionRegressionEnsemble, CompactRegressionEnsemble, or RegressionBaggedEnsemblefitrensemble or RegressionEnsemble object function compact
    Full generalized linear regression modelGeneralizedLinearModel or CompactGeneralizedLinearModelfitglm or GeneralizedLinearModel object function compact
    Full linear regression modelLinearModel or CompactLinearModelfitlm or LinearModel object function compact
    Regression tree modelRegressionTree or CompactRegressionTreefitrtree or RegressionTree object function compact
    Support vector machine regression modelRegressionSVM, CompactRegressionSVM, or RegressionPartitionedSVMfitrsvm
    Cross-validated regression ensembleRegressionPartitionedEnsemblefitrensemble
    Cross-validated regression modelRegressionPartitionedModelfitrtree

    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 TypeFull or Compact Model ObjectModel Creation Function
    Multiclass model for support vector machines or other classifiersClassificationECOC or CompactClassificationECOCfitcecoc or ClassificationECOC object function compact
    Ensemble of learners for classificationClassificationEnsemble, CompactClassificationEnsemble, or ClassificationBaggedEnsemblefitcensemble or ClassificationEnsemble object function compact
    k-nearest neighbor classifierClassificationKNNfitcknn
    Support vector machine (SVM) classifierClassificationSVM or CompactClassificationSVMfitcsvm or ClassificationSVM object function compact
    Binary decision tree for multiclass classificationClassificationTree or CompactClassificationTreefitctree or ClassificationTree object function compact
    Cross-validated ECOC modelClassificationPartitionedECOCfitcecoc
    Cross-validated classification ensembleClassificationPartitionedEnsemblefitcensemble
    Cross-validated classification modelClassificationPartitionedModelfitcknn, fitcsvm, 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 DistributionProbability Distribution ObjectObject Creation Function
    Beta distributionBetaDistributionfitdist with distname specified as 'Beta'
    Binomial distributionBinomialDistributionfitdist with distname specified as 'Binomial'
    Birnbaum-Saunders distributionBirnbaumSaundersDistributionfitdist with distname specified as 'BirnbaumSaunders'
    Burr distributionBurrDistributionfitdist with distname specified as 'Burr'
    Exponential distributionExponentialDistributionfitdist with distname specified as 'Exponential'
    Extreme Value distributionExtremeValueDistributionfitdist with distname specified as 'ExtremeValue'
    Gamma distributionGammaDistributionfitdist with distname specified as 'Gamma'
    Generalized Extreme Value distributionGeneralizedExtremeValueDistributionfitdist with distname specified as 'GeneralizedExtremeValue'
    Generalized Pareto distributionGeneralizedParetoDistributionfitdist with distname specified as 'GeneralizedPareto'
    Half-normal distributionHalfNormalDistributionfitdist with distname specified as 'HalfNormal'
    Inverse Gaussian distributionInverseGaussianDistributionfitdist with distname specified as 'InverseGaussian'
    Kernel distributionKernelDistributionfitdist with distname specified as 'Kernel'
    Logistic distributionLogisticDistributionfitdist with distname specified as 'Logistic'
    Loglogistic distributionLoglogisticDistributionfitdist with distname specified as 'Loglogistic'
    Lognormal distributionLognormalDistributionfitdist with distname specified as 'Lognormal'
    Nakagami distributionNakagamiDistributionfitdist with distname specified as 'Nakagami'
    Negative Binomial distributionNegativeBinomialDistributionfitdist with distname specified as 'NegativeBinomial'
    Normal distributionNormalDistributionfitdist with distname specified as 'Normal'
    Poisson distributionPoissonDistributionfitdist with distname specified as 'Poisson'
    Rayleigh distributionRayleighDistributionfitdist with distname specified as 'Rayleigh'
    t Location-Scale distributiontLocationScaleDistributionfitdist with distname specified as 'tLocationScale'
    Weibull distributionWeibullDistributionfitdist 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

    Version History

    Introduced in R2020b

    expand all