C++ API Reference for Intel® Data Analytics Acceleration Library 2018 Update 2

pca_types.h
1 /* file: pca_types.h */
2 /*******************************************************************************
3 * Copyright 2014-2018 Intel Corporation
4 * All Rights Reserved.
5 *
6 * If this software was obtained under the Intel Simplified Software License,
7 * the following terms apply:
8 *
9 * The source code, information and material ("Material") contained herein is
10 * owned by Intel Corporation or its suppliers or licensors, and title to such
11 * Material remains with Intel Corporation or its suppliers or licensors. The
12 * Material contains proprietary information of Intel or its suppliers and
13 * licensors. The Material is protected by worldwide copyright laws and treaty
14 * provisions. No part of the Material may be used, copied, reproduced,
15 * modified, published, uploaded, posted, transmitted, distributed or disclosed
16 * in any way without Intel's prior express written permission. No license under
17 * any patent, copyright or other intellectual property rights in the Material
18 * is granted to or conferred upon you, either expressly, by implication,
19 * inducement, estoppel or otherwise. Any license under such intellectual
20 * property rights must be express and approved by Intel in writing.
21 *
22 * Unless otherwise agreed by Intel in writing, you may not remove or alter this
23 * notice or any other notice embedded in Materials by Intel or Intel's
24 * suppliers or licensors in any way.
25 *
26 *
27 * If this software was obtained under the Apache License, Version 2.0 (the
28 * "License"), the following terms apply:
29 *
30 * You may not use this file except in compliance with the License. You may
31 * obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
32 *
33 *
34 * Unless required by applicable law or agreed to in writing, software
35 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
36 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
37 *
38 * See the License for the specific language governing permissions and
39 * limitations under the License.
40 *******************************************************************************/
41 
42 /*
43 //++
44 // Implementation of PCA algorithm interface.
45 //--
46 */
47 
48 #ifndef __PCA_TYPES_H__
49 #define __PCA_TYPES_H__
50 
51 #include "algorithms/algorithm.h"
52 #include "data_management/data/numeric_table.h"
53 #include "data_management/data/homogen_numeric_table.h"
54 #include "services/daal_defines.h"
55 #include "algorithms/covariance/covariance_batch.h"
56 #include "algorithms/covariance/covariance_online.h"
57 #include "algorithms/covariance/covariance_distributed.h"
58 #include "algorithms/normalization/zscore.h"
59 
60 namespace daal
61 {
62 namespace algorithms
63 {
73 namespace pca
74 {
79 enum Method
80 {
81  correlationDense = 0,
82  defaultDense = 0,
83  svdDense = 1
84 };
85 
90 enum InputDatasetId
91 {
92  data,
93  lastInputDatasetId = data
94 };
95 
100 enum InputCorrelationId
101 {
102  correlation,
103  lastInputCorrelationId = correlation
104 };
105 
110 enum Step2MasterInputId
111 {
112  partialResults,
113  lastStep2MasterInputId = partialResults
114 };
115 
120 enum PartialCorrelationResultId
121 {
122  nObservationsCorrelation, /* Number of processed observations */
123  crossProductCorrelation, /* Cross-product of the processed data */
124  sumCorrelation, /* Feature sums of the processed data */
125  lastPartialCorrelationResultId = sumCorrelation
126 };
127 
132 enum PartialSVDTableResultId
133 {
134  nObservationsSVD, /* Number of processed observations */
135  sumSVD, /* Feature sums of the processed data */
136  sumSquaresSVD, /* Feature sums of squares of the processed data */
137  lastPartialSVDTableResultId = sumSquaresSVD
138 };
139 
144 enum PartialSVDCollectionResultId
145 {
146  auxiliaryData = lastPartialSVDTableResultId + 1,
147  distributedInputs,
148  lastPartialSVDCollectionResultId = distributedInputs
149 };
150 
155 enum ResultId
156 {
157  eigenvalues,
158  eigenvectors,
159  means,
160  variances,
161  lastResultId = variances
162 };
163 
168 enum ResultCollectionId
169 {
170  dataForTransform
171 };
172 
178 enum ResultToComputeId
179 {
180  none = 0ULL,
181  mean = 0x00000001ULL,
182  variance = 0x00000002ULL,
183  eigenvalue = 0x00000004ULL
184 };
185 
189 namespace interface1
190 {
194 class DAAL_EXPORT InputIface : public daal::algorithms::Input
195 {
196 public:
197  InputIface(size_t nElements);
198  InputIface(const InputIface& other);
199 
204  virtual size_t getNFeatures() const = 0;
205 
210  virtual bool isCorrelation() const { return _isCorrelation; };
211 
212  virtual ~InputIface() {};
213 
214 protected:
215  bool _isCorrelation;
216 };
217 
222 class DAAL_EXPORT Input : public InputIface
223 {
224 public:
225  Input();
226  Input(const Input& other);
227 
228  virtual ~Input() {};
229 
235  data_management::NumericTablePtr get(InputDatasetId id) const;
236 
242  void set(InputDatasetId id, const data_management::NumericTablePtr &value);
243 
249  void set(InputCorrelationId id, const data_management::NumericTablePtr &value);
250 
255  size_t getNFeatures() const DAAL_C11_OVERRIDE;
256 
263  services::Status check(const daal::algorithms::Parameter *par, int method) const DAAL_C11_OVERRIDE;
264 };
265 
271 class PartialResultBase : public daal::algorithms::PartialResult
272 {
273 public:
274  PartialResultBase(const size_t nElements) : daal::algorithms::PartialResult(nElements) {};
275 
276  virtual size_t getNFeatures() const = 0;
277 
278  virtual ~PartialResultBase() {};
279 };
280 
286 template<Method method>
287 class PartialResult : public PartialResultBase {};
288 
294 template<> class DAAL_EXPORT PartialResult<daal::algorithms::pca::correlationDense> : public PartialResultBase
295 {
296 public:
297  DECLARE_SERIALIZABLE_CAST(PartialResult<daal::algorithms::pca::correlationDense>);
298  PartialResult();
299 
305  data_management::NumericTablePtr get(PartialCorrelationResultId id) const;
306 
307  virtual size_t getNFeatures() const DAAL_C11_OVERRIDE;
308 
314  void set(const PartialCorrelationResultId id, const data_management::NumericTablePtr &value);
315 
316  virtual ~PartialResult() {};
317 
325  services::Status check(const daal::algorithms::Input *input, const daal::algorithms::Parameter *parameter, int method) const DAAL_C11_OVERRIDE;
326 
327 
334  services::Status check(const daal::algorithms::Parameter *par, int method) const DAAL_C11_OVERRIDE;
335 
343  template <typename algorithmFPType>
344  DAAL_EXPORT services::Status allocate(const daal::algorithms::Input *input, const daal::algorithms::Parameter *parameter, const int method);
345 
353  template <typename algorithmFPType>
354  DAAL_EXPORT services::Status initialize(const daal::algorithms::Input *input, const daal::algorithms::Parameter *parameter, const int method);
355 protected:
356 
357  services::Status checkImpl(size_t nFeatures) const;
358 
360  template<typename Archive, bool onDeserialize>
361  services::Status serialImpl(Archive *arch)
362  {
363  return daal::algorithms::PartialResult::serialImpl<Archive, onDeserialize>(arch);
364  }
365 };
366 
372 template<> class DAAL_EXPORT PartialResult<daal::algorithms::pca::svdDense> : public PartialResultBase
373 {
374 public:
375  DECLARE_SERIALIZABLE_CAST(PartialResult<daal::algorithms::pca::svdDense>);
376  PartialResult();
377 
383  data_management::NumericTablePtr get(PartialSVDTableResultId id) const;
384 
385  virtual size_t getNFeatures() const DAAL_C11_OVERRIDE;
386 
392  data_management::DataCollectionPtr get(PartialSVDCollectionResultId id) const;
393 
400  data_management::NumericTablePtr get(PartialSVDCollectionResultId id, const size_t &elementId) const;
401 
407  void set(PartialSVDTableResultId id, const data_management::NumericTablePtr &value);
408 
414  void set(PartialSVDCollectionResultId id, const data_management::DataCollectionPtr &value);
415 
421  void add(const PartialSVDCollectionResultId &id, const data_management::DataCollectionPtr &value);
422 
430  services::Status check(const daal::algorithms::Input *input, const daal::algorithms::Parameter *parameter, int method) const DAAL_C11_OVERRIDE;
431 
438  services::Status check(const daal::algorithms::Parameter *par, int method) const DAAL_C11_OVERRIDE;
439 
440  virtual ~PartialResult() {};
441 
449  template <typename algorithmFPType>
450  DAAL_EXPORT services::Status allocate(const daal::algorithms::Input *input, const daal::algorithms::Parameter *parameter, const int method);
451 
459  template <typename algorithmFPType>
460  DAAL_EXPORT services::Status initialize(const daal::algorithms::Input *input, const daal::algorithms::Parameter *parameter, const int method);
461 
462 protected:
463 
464  services::Status checkImpl(size_t nFeatures) const;
465 
467  template<typename Archive, bool onDeserialize>
468  services::Status serialImpl(Archive *arch)
469  {
470  return daal::algorithms::PartialResult::serialImpl<Archive, onDeserialize>(arch);
471  }
472 };
473 
478 template<typename algorithmFPType, Method method = correlationDense>
479 class DAAL_EXPORT BaseParameter : public daal::algorithms::Parameter
480 {
481 public:
483  BaseParameter();
484 };
485 
490 template<typename algorithmFPType, Method method>
491 class OnlineParameter : public BaseParameter<algorithmFPType, method> {};
492 
497 template<typename algorithmFPType>
498 class DAAL_EXPORT OnlineParameter<algorithmFPType, correlationDense> : public BaseParameter<algorithmFPType, correlationDense>
499 {
500 public:
502  OnlineParameter(const services::SharedPtr<covariance::OnlineImpl> &covarianceForOnlineParameter =
503  services::SharedPtr<covariance::Online<algorithmFPType, covariance::defaultDense> >
504  (new covariance::Online<algorithmFPType, covariance::defaultDense>()));
505 
506  services::SharedPtr<covariance::OnlineImpl> covariance;
512  services::Status check() const DAAL_C11_OVERRIDE;
513 };
514 
515 
520 template<typename algorithmFPType>
521 class DAAL_EXPORT OnlineParameter<algorithmFPType, svdDense> : public BaseParameter<algorithmFPType, svdDense>
522 {
523 public:
525  OnlineParameter();
526 
531  services::Status check() const DAAL_C11_OVERRIDE;
532 };
533 
538 template<ComputeStep step, typename algorithmFPType, Method method>
539 class DistributedParameter : public BaseParameter<algorithmFPType, method> {};
540 
545 template<typename algorithmFPType>
546 class DAAL_EXPORT DistributedParameter<step2Master, algorithmFPType, correlationDense> : public BaseParameter<algorithmFPType, correlationDense>
547 {
548 public:
550  DistributedParameter(const services::SharedPtr<covariance::DistributedIface<step2Master> > &covarianceForDistributedParameter =
551  services::SharedPtr<covariance::Distributed<step2Master, algorithmFPType, covariance::defaultDense> >
552  (new covariance::Distributed<step2Master, algorithmFPType, covariance::defaultDense>()));
553 
554  services::SharedPtr<covariance::DistributedIface<step2Master> > covariance;
560  services::Status check() const DAAL_C11_OVERRIDE;
561 };
562 
567 template<Method method>
568 class DistributedInput {};
569 
574 template<> class DAAL_EXPORT DistributedInput<correlationDense> : public InputIface
575 {
576 public:
577  DistributedInput();
578  DistributedInput(const DistributedInput& other);
579 
585  void set(Step2MasterInputId id, const data_management::DataCollectionPtr &ptr);
586 
592  data_management::DataCollectionPtr get(Step2MasterInputId id) const;
593 
598  services::SharedPtr<PartialResult<correlationDense> > getPartialResult(size_t id) const;
599 
605  void add(Step2MasterInputId id, const services::SharedPtr<PartialResult<correlationDense> > &value);
606 
611  size_t getNFeatures() const DAAL_C11_OVERRIDE;
612 
619  services::Status check(const daal::algorithms::Parameter *parameter, int method) const DAAL_C11_OVERRIDE;
620 };
621 
626 template<> class DAAL_EXPORT DistributedInput<svdDense> : public InputIface
627 {
628 public:
629  DistributedInput();
630  DistributedInput(const DistributedInput& other);
631 
637  void set(Step2MasterInputId id, const data_management::DataCollectionPtr &ptr);
638 
644  data_management::DataCollectionPtr get(Step2MasterInputId id) const;
645 
651  void add(Step2MasterInputId id, const services::SharedPtr<PartialResult<svdDense> > &value);
652 
657  services::SharedPtr<PartialResult<svdDense> > getPartialResult(size_t id) const;
658 
665  services::Status check(const daal::algorithms::Parameter *parameter, int method) const DAAL_C11_OVERRIDE;
666 
671  size_t getNFeatures() const DAAL_C11_OVERRIDE;
672 };
673 
674 } // namespace interface1
675 
676 namespace interface2
677 {
682 class DAAL_EXPORT BaseBatchParameter : public daal::algorithms::Parameter
683 {
684 public:
686  BaseBatchParameter();
687 
688  DAAL_UINT64 resultsToCompute;
689  size_t nComponents;
690  bool isDeterministic;
691 };
692 
693 
698 template<typename algorithmFPType, Method method>
699 class BatchParameter {};
700 
701 
706 template<typename algorithmFPType>
707 class DAAL_EXPORT BatchParameter<algorithmFPType, correlationDense> : public BaseBatchParameter
708 {
709 public:
711  BatchParameter(const services::SharedPtr<covariance::BatchImpl> &covarianceForBatchParameter =
712  services::SharedPtr<covariance::Batch<algorithmFPType, covariance::defaultDense> >
713  (new covariance::Batch<algorithmFPType, covariance::defaultDense>()));
714 
715  services::SharedPtr<covariance::BatchImpl> covariance;
722  services::Status check() const DAAL_C11_OVERRIDE;
723 };
724 
729 template<typename algorithmFPType>
730 class DAAL_EXPORT BatchParameter<algorithmFPType, svdDense> : public BaseBatchParameter
731 {
732 public:
734  BatchParameter(const services::SharedPtr<normalization::zscore::BatchImpl> &normalizationForBatchParameter =
735  services::SharedPtr<normalization::zscore::Batch<algorithmFPType, normalization::zscore::defaultDense> >
736  (new normalization::zscore::Batch<algorithmFPType, normalization::zscore::defaultDense>()));
737 
738  services::SharedPtr<normalization::zscore::BatchImpl> normalization;
745  services::Status check() const DAAL_C11_OVERRIDE;
746 };
747 
748 
753 class DAAL_EXPORT Result : public daal::algorithms::Result
754 {
755 public:
756  DECLARE_SERIALIZABLE_CAST(Result);
757  Result(const Result& o);
758  Result();
759 
760  virtual ~Result() {};
761 
767  data_management::NumericTablePtr get(ResultId id) const;
768 
774  data_management::KeyValueDataCollectionPtr get(ResultCollectionId id) const;
775 
782  void set(ResultCollectionId id, data_management::KeyValueDataCollectionPtr& collection);
783 
784 
790  void set(ResultId id, const data_management::NumericTablePtr &value);
791 
798  template<typename algorithmFPType>
799  DAAL_EXPORT services::Status allocate(const daal::algorithms::Input *input, daal::algorithms::Parameter *parameter, const Method method);
800 
806  template<typename algorithmFPType>
807  DAAL_EXPORT services::Status allocate(const daal::algorithms::PartialResult *partialResult, daal::algorithms::Parameter *parameter, const Method method);
808 
816  services::Status check(const daal::algorithms::Input *_input, const daal::algorithms::Parameter *par, int method) const DAAL_C11_OVERRIDE;
817 
825  services::Status check(const daal::algorithms::PartialResult *pr, const daal::algorithms::Parameter *parameter, int method) const DAAL_C11_OVERRIDE;
826 
827 protected:
828 
837  services::Status checkImpl(size_t nFeatures, size_t nComponents, DAAL_UINT64 resultsToCompute) const;
838 
840  template<typename Archive, bool onDeserialize>
841  services::Status serialImpl(Archive *arch)
842  {
843  return daal::algorithms::Result::serialImpl<Archive, onDeserialize>(arch);
844  }
845 };
846 typedef services::SharedPtr<Result> ResultPtr;
847 
849 } // namespace interface1
850 using interface1::InputIface;
851 using interface1::Input;
852 using interface1::PartialResultBase;
853 using interface1::PartialResult;
854 using interface2::BatchParameter;
855 using interface2::BaseBatchParameter;
856 using interface1::OnlineParameter;
857 using interface1::DistributedParameter;
858 using interface1::DistributedInput;
859 using interface2::Result;
860 using interface2::ResultPtr;
861 
862 } // pca
863 } // algorithm
864 } // namespace daal
865 #endif
daal::algorithms::pca::defaultDense
Definition: pca_types.h:82
daal::algorithms::pca::interface1::DistributedParameter
Class that specifies the parameters of the PCA algorithm in the distributed computing mode...
Definition: pca_types.h:539
daal::algorithms::pca::data
Definition: pca_types.h:92
daal::algorithms::pca::PartialCorrelationResultId
PartialCorrelationResultId
Definition: pca_types.h:120
daal::algorithms::pca::interface1::DistributedInput
Input objects for the PCA algorithm in the distributed processing mode.
Definition: pca_types.h:568
daal::algorithms::pca::dataForTransform
Definition: pca_types.h:170
daal::algorithms::pca::auxiliaryData
Definition: pca_types.h:146
daal::services::interface1::Status
Class that holds the results of API calls. In case of API routine failure it contains the list of err...
Definition: error_handling.h:491
daal
Definition: algorithm_base_common.h:57
daal::algorithms::pca::interface1::BaseParameter
Class that specifies the common parameters of the PCA algorithm.
Definition: pca_types.h:479
daal::algorithms::pca::interface1::PartialResultBase
Provides interface to access partial results obtained with the compute() method of the PCA algorithm ...
Definition: pca_types.h:271
daal::algorithms::pca::ResultCollectionId
ResultCollectionId
Definition: pca_types.h:168
daal::algorithms::pca::eigenvalue
Definition: pca_types.h:183
daal::algorithms::pca::interface2::BatchParameter< algorithmFPType, correlationDense >::covariance
services::SharedPtr< covariance::BatchImpl > covariance
Definition: pca_types.h:715
daal::algorithms::pca::interface2::BaseBatchParameter
Class that specifies the common parameters of the PCA Batch algorithms.
Definition: pca_types.h:682
daal::algorithms::pca::eigenvalues
Definition: pca_types.h:157
daal::algorithms::interface1::PartialResult
Base class to represent partial results of the computation. Algorithm-specific partial results are re...
Definition: algorithm_types.h:253
daal::algorithms::pca::correlation
Definition: pca_types.h:102
daal::algorithms::covariance::interface1::Online
Computes correlation or variance-covariance matrix in the online processing mode. ...
Definition: covariance_online.h:436
daal::algorithms::covariance::interface1::DistributedIface
Interface for the correlation or variance-covariance matrix algorithm in the distributed processing m...
Definition: covariance_distributed.h:176
daal::algorithms::pca::interface1::DistributedParameter< step2Master, algorithmFPType, correlationDense >::covariance
services::SharedPtr< covariance::DistributedIface< step2Master > > covariance
Definition: pca_types.h:554
daal_defines.h
daal::algorithms::pca::interface1::InputIface
Abstract class that specifies interface for classes that declare input of the PCA algorithm...
Definition: pca_types.h:194
daal::algorithms::pca::interface2::BaseBatchParameter::isDeterministic
bool isDeterministic
Definition: pca_types.h:690
daal::algorithms::pca::means
Definition: pca_types.h:159
daal::algorithms::interface1::Parameter
Base class to represent computation parameters. Algorithm-specific parameters are represented as deri...
Definition: algorithm_types.h:86
daal::algorithms::pca::variance
Definition: pca_types.h:182
daal::services::interface1::SharedPtr
Shared pointer that retains shared ownership of an object through a pointer. Several SharedPtr object...
Definition: daal_shared_ptr.h:187
daal::algorithms::pca::interface2::Result
Provides methods to access results obtained with the PCA algorithm.
Definition: pca_types.h:753
daal::algorithms::pca::interface1::OnlineParameter
Class that specifies the parameters of the PCA algorithm in the online computing mode.
Definition: pca_types.h:491
daal::algorithms::pca::InputCorrelationId
InputCorrelationId
Definition: pca_types.h:100
daal::algorithms::pca::eigenvectors
Definition: pca_types.h:158
daal::algorithms::pca::interface1::PartialResult< daal::algorithms::pca::svdDense >
Provides methods to access partial results obtained with the compute() method of PCA SVD algorithm in...
Definition: pca_types.h:372
daal::algorithms::pca::Step2MasterInputId
Step2MasterInputId
Definition: pca_types.h:110
daal::algorithms::pca::interface1::PartialResult
Provides methods to access partial results obtained with the compute() method of the PCA algorithm in...
Definition: pca_types.h:287
daal::algorithms::pca::interface2::BaseBatchParameter::nComponents
size_t nComponents
Definition: pca_types.h:689
daal::algorithms::pca::InputDatasetId
InputDatasetId
Definition: pca_types.h:90
daal::algorithms::pca::variances
Definition: pca_types.h:160
daal::algorithms::pca::svdDense
Definition: pca_types.h:83
daal::algorithms::pca::PartialSVDTableResultId
PartialSVDTableResultId
Definition: pca_types.h:132
daal::algorithms::pca::Method
Method
Definition: pca_types.h:79
daal::algorithms::pca::ResultToComputeId
ResultToComputeId
Definition: pca_types.h:178
daal::algorithms::pca::interface1::OnlineParameter< algorithmFPType, correlationDense >::covariance
services::SharedPtr< covariance::OnlineImpl > covariance
Definition: pca_types.h:506
daal::algorithms::pca::interface1::InputIface::isCorrelation
virtual bool isCorrelation() const
Definition: pca_types.h:210
daal::algorithms::math::abs::value
Definition: abs_types.h:112
daal::algorithms::pca::interface1::PartialResult< daal::algorithms::pca::correlationDense >
Provides methods to access partial results obtained with the compute() method of the PCA Correlation ...
Definition: pca_types.h:294
daal::step2Master
Definition: daal_defines.h:144
daal::algorithms::covariance::interface1::Distributed
Computes correlation or variance-covariance matrix in the distributed processing mode.
Definition: covariance_distributed.h:424
daal::algorithms::covariance::interface1::Batch
Computes correlation or variance-covariance matrix in the batch processing mode.
Definition: covariance_batch.h:369
daal::algorithms::pca::PartialSVDCollectionResultId
PartialSVDCollectionResultId
Definition: pca_types.h:144
daal::algorithms::pca::mean
Definition: pca_types.h:181
daal::algorithms::interface1::Input
Base class to represent computation input arguments. Algorithm-specific input arguments are represent...
Definition: algorithm_types.h:217
daal::algorithms::pca::distributedInputs
Definition: pca_types.h:147
daal::algorithms::pca::interface1::Input
Input objects for the PCA algorithm.
Definition: pca_types.h:222
daal::algorithms::pca::partialResults
Definition: pca_types.h:112
daal::algorithms::pca::interface2::BatchParameter< algorithmFPType, svdDense >::normalization
services::SharedPtr< normalization::zscore::BatchImpl > normalization
Definition: pca_types.h:738
daal::algorithms::pca::interface2::BatchParameter
Class that specifies the parameters of the PCA algorithm in the batch computing mode.
Definition: pca_types.h:699
daal::algorithms::pca::correlationDense
Definition: pca_types.h:81
daal::algorithms::pca::ResultId
ResultId
Definition: pca_types.h:155
daal::algorithms::normalization::zscore::interface2::Batch
Normalizes datasets in the batch processing mode.
Definition: zscore.h:198

For more complete information about compiler optimizations, see our Optimization Notice.