vtkStatisticsAlgorithm.h 12.4 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
/*=========================================================================

Program:   Visualization Toolkit
Module:    vtkStatisticsAlgorithm.h

Copyright (c) Ken Martin, Will Schroeder, Bill Lorensen
All rights reserved.
See Copyright.txt or http://www.kitware.com/Copyright.htm for details.

This software is distributed WITHOUT ANY WARRANTY; without even
the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
PURPOSE.  See the above copyright notice for more information.

=========================================================================*/
/*-------------------------------------------------------------------------
Philippe Pébay's avatar
Philippe Pébay committed
16
  Copyright 2011 Sandia Corporation.
17 18 19 20 21 22
  Under the terms of Contract DE-AC04-94AL85000 with Sandia Corporation,
  the U.S. Government retains certain rights in this software.
  -------------------------------------------------------------------------*/
// .NAME vtkStatisticsAlgorithm - Base class for statistics algorithms
//
// .SECTION Description
23
// All statistics algorithms can conceptually be operated with several operations:
24
// * Learn: given an input data set, calculate a minimal statistical model (e.g.,
25
//   sums, raw moments, joint probabilities).
26
// * Derive: given an input minimal statistical model, derive the full model
27 28
//   (e.g., descriptive statistics, quantiles, correlations, conditional
//    probabilities).
29 30 31 32 33
//   NB: It may be, or not be, a problem that a full model was not derived. For
//   instance, when doing parallel calculations, one only wants to derive the full
//   model after all partial calculations have completed. On the other hand, one
//   can also directly provide a full model, that was previously calculated or
//   guessed, and not derive a new one.
34
// * Assess: given an input data set, input statistics, and some form of
35 36
//   threshold, assess a subset of the data set.
// * Test: perform at least one statistical test.
37 38 39 40
// Therefore, a vtkStatisticsAlgorithm has the following ports
// * 3 optional input ports:
//   * Data (vtkTable)
//   * Parameters to the learn operation (vtkTable)
41
//   * Input model (vtkMultiBlockDataSet)
42 43 44
// * 3 output ports:
//   * Data (input annotated with assessments when the Assess operation is ON).
//   * Output model (identical to the the input model when Learn operation is OFF).
45
//   * Output of statistical tests. Some engines do not offer such tests yet, in
46
//     which case this output will always be empty even when the Test operation is ON.
47 48
//
// .SECTION Thanks
49
// Thanks to Philippe Pebay and David Thompson from Sandia National Laboratories
50
// for implementing this class.
51
// Updated by Philippe Pebay, Kitware SAS 2012
52

53 54
#ifndef vtkStatisticsAlgorithm_h
#define vtkStatisticsAlgorithm_h
55

56
#include "vtkFiltersStatisticsModule.h" // For export macro
57 58
#include "vtkTableAlgorithm.h"

59
class vtkDataObjectCollection;
60
class vtkMultiBlockDataSet;
61 62
class vtkStdString;
class vtkStringArray;
63
class vtkVariant;
64
class vtkVariantArray;
65
class vtkStatisticsAlgorithmPrivate;
66

67
class VTKFILTERSSTATISTICS_EXPORT vtkStatisticsAlgorithm : public vtkTableAlgorithm
68 69
{
public:
70
  vtkTypeMacro(vtkStatisticsAlgorithm, vtkTableAlgorithm);
71
  void PrintSelf(ostream& os, vtkIndent indent);
72

73
//BTX
74 75
  // Description:
  // enumeration values to specify input port types
76 77 78 79 80 81 82
  enum InputPorts
    {
    INPUT_DATA = 0,         //!< Port 0 is for learn data
    LEARN_PARAMETERS = 1,   //!< Port 1 is for learn parameters (initial guesses, etc.)
    INPUT_MODEL = 2         //!< Port 2 is for a priori models
    };

83 84
  // Description:
  // enumeration values to specify output port types
85 86
  enum OutputIndices
    {
87
    OUTPUT_DATA  = 0,       //!< Output 0 mirrors the input data, plus optional assessment columns
88
    OUTPUT_MODEL = 1,       //!< Output 1 contains any generated model
89
#ifndef VTK_LEGACY_REMOVE
90
    ASSESSMENT   = 2,       //!< This is an old, deprecated name for OUTPUT_TEST.
91
#endif
92
    OUTPUT_TEST  = 2        //!< Output 2 contains result of statistical test(s)
93
    };
94
//ETX
95

96
  // Description:
97 98
  // A convenience method for setting learn input parameters (if one is expected or allowed).
  // It is equivalent to calling SetInputConnection( 1, params );
99
  virtual void SetLearnOptionParameterConnection( vtkAlgorithmOutput* params )
100 101 102 103
    { this->SetInputConnection( vtkStatisticsAlgorithm::LEARN_PARAMETERS, params ); }

  // Description:
  // A convenience method for setting learn input parameters (if one is expected or allowed).
104
  // It is equivalent to calling SetInputData( 1, params );
105
  virtual void SetLearnOptionParameters( vtkDataObject* params )
106
    { this->SetInputData( vtkStatisticsAlgorithm::LEARN_PARAMETERS, params ); }
107 108

  // Description:
109
  // A convenience method for setting the input model connection (if one is expected or allowed).
110 111 112 113 114
  // It is equivalent to calling SetInputConnection( 2, model );
  virtual void SetInputModelConnection( vtkAlgorithmOutput* model )
    { this->SetInputConnection( vtkStatisticsAlgorithm::INPUT_MODEL, model ); }

  // Description:
115
  // A convenience method for setting the input model (if one is expected or allowed).
116
  // It is equivalent to calling SetInputData( 2, model );
117
  virtual void SetInputModel( vtkDataObject* model )
118
    { this->SetInputData( vtkStatisticsAlgorithm::INPUT_MODEL, model ); }
119

120
  // Description:
121
  // Set/Get the Learn operation.
122 123
  vtkSetMacro( LearnOption, bool );
  vtkGetMacro( LearnOption, bool );
124

125
  // Description:
126
  // Set/Get the Derive operation.
127 128
  vtkSetMacro( DeriveOption, bool );
  vtkGetMacro( DeriveOption, bool );
129

130
  // Description:
131
  // Set/Get the Assess operation.
132
  vtkSetMacro( AssessOption, bool );
133
  vtkGetMacro( AssessOption, bool );
134

135
  // Description:
136
  // Set/Get the Test operation.
137 138 139
  vtkSetMacro( TestOption, bool );
  vtkGetMacro( TestOption, bool );

140 141 142 143 144
  // Description:
  // Set/Get the number of tables in the primary model.
  vtkSetMacro( NumberOfPrimaryTables, vtkIdType );
  vtkGetMacro( NumberOfPrimaryTables, vtkIdType );

145 146
  // Description:
  // Set/get assessment names.
147 148
  virtual void SetAssessNames( vtkStringArray* );
  vtkGetObjectMacro(AssessNames,vtkStringArray);
149

150
//BTX
151 152 153 154
  // Description:
  // A base class for a functor that assesses data.
  class AssessFunctor {
  public:
155 156
    virtual void operator() ( vtkVariantArray*,
                              vtkIdType ) = 0;
157 158
    virtual ~AssessFunctor() { }
  };
159
//ETX
160

161 162 163 164 165 166 167 168 169 170 171 172 173 174
  // Description:
  // Add or remove a column from the current analysis request.
  // Once all the column status values are set, call RequestSelectedColumns()
  // before selecting another set of columns for a different analysis request.
  // The way that columns selections are used varies from algorithm to algorithm.
  //
  // Note: the set of selected columns is maintained in vtkStatisticsAlgorithmPrivate::Buffer
  // until RequestSelectedColumns() is called, at which point the set is appended
  // to vtkStatisticsAlgorithmPrivate::Requests.
  // If there are any columns in vtkStatisticsAlgorithmPrivate::Buffer at the time
  // RequestData() is called, RequestSelectedColumns() will be called and the
  // selection added to the list of requests.
  virtual void SetColumnStatus( const char* namCol, int status );

175 176 177 178
  // Description:
  // Set the the status of each and every column in the current request to OFF (0).
  virtual void ResetAllColumnStates();

179 180 181 182 183 184 185 186 187
  // Description:
  // Use the current column status values to produce a new request for statistics
  // to be produced when RequestData() is called. See SetColumnStatus() for more information.
  virtual int RequestSelectedColumns();

  // Description:
  // Empty the list of current requests.
  virtual void ResetRequests();

188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214
  // Description:
  // Return the number of requests.
  // This does not include any request that is in the column-status buffer
  // but for which RequestSelectedColumns() has not yet been called (even though
  // it is possible this request will be honored when the filter is run -- see SetColumnStatus()
  // for more information).
  virtual vtkIdType GetNumberOfRequests();

  // Description:
  // Return the number of columns for a given request.
  virtual vtkIdType GetNumberOfColumnsForRequest( vtkIdType request );

  // Description:
  // Provide the name of the \a c-th column for the \a r-th request.
  //
  // For the version of this routine that returns an integer,
  // if the request or column does not exist because \a r or \a c is out of bounds,
  // this routine returns 0 and the value of \a columnName is unspecified.
  // Otherwise, it returns 1 and the value of \a columnName is set.
  //
  // For the version of this routine that returns const char*,
  // if the request or column does not exist because \a r or \a c is out of bounds,
  // the routine returns NULL. Otherwise it returns the column name.
  // This version is not thread-safe.
  virtual const char* GetColumnForRequest( vtkIdType r, vtkIdType c );
  //BTX
  virtual int GetColumnForRequest( vtkIdType r, vtkIdType c, vtkStdString& columnName );
215
  //ETX
216

217 218 219 220 221 222 223 224 225
  // Description:
  // Convenience method to create a request with a single column name \p namCol in a single
  // call; this is the preferred method to select columns, ensuring selection consistency
  // (a single column per request).
  // Warning: no name checking is performed on \p namCol; it is the user's
  // responsibility to use valid column names.
  void AddColumn( const char* namCol );

  // Description:
226 227
  // Convenience method to create a request with a single column name pair
  //  (\p namColX, \p namColY) in a single call; this is the preferred method to select
228 229 230 231 232 233 234 235
  // columns pairs, ensuring selection consistency (a pair of columns per request).
  //
  // Unlike SetColumnStatus(), you need not call RequestSelectedColumns() after AddColumnPair().
  //
  // Warning: \p namColX and \p namColY are only checked for their validity as strings;
  // no check is made that either are valid column names.
  void AddColumnPair( const char* namColX, const char* namColY );

236
  // Description:
237
  // A convenience method (in particular for access from other applications) to
238 239 240
  // set parameter values of Learn mode.
  // Return true if setting of requested parameter name was excuted, false otherwise.
  // NB: default method (which is sufficient for most statistics algorithms) does not
241
  // have any Learn parameters to set and always returns false.
242 243 244
  virtual bool SetParameter( const char* parameter,
                             int index,
                             vtkVariant value );
245

246 247
  // Description:
  // Given a collection of models, calculate aggregate model
248
  virtual void Aggregate( vtkDataObjectCollection*,
249
                          vtkMultiBlockDataSet* ) = 0;
250

251 252 253 254 255
protected:
  vtkStatisticsAlgorithm();
  ~vtkStatisticsAlgorithm();

  virtual int FillInputPortInformation( int port, vtkInformation* info );
256
  virtual int FillOutputPortInformation( int port, vtkInformation* info );
257 258 259 260 261 262 263

  virtual int RequestData(
    vtkInformation*,
    vtkInformationVector**,
    vtkInformationVector* );

  // Description:
264 265 266
  // Execute the calculations required by the Learn option, given some input Data
  virtual void Learn( vtkTable*,
                      vtkTable*,
267
                      vtkMultiBlockDataSet* ) = 0;
268 269 270

  // Description:
  // Execute the calculations required by the Derive option.
271
  virtual void Derive( vtkMultiBlockDataSet* ) = 0;
272 273 274 275

  // Description:
  // Execute the calculations required by the Assess option.
  virtual void Assess( vtkTable*,
276
                       vtkMultiBlockDataSet*,
277
                       vtkTable* ) = 0;
278

279 280 281 282 283
  // Description:
  // A convenience implementation for generic assessment with variable number of variables.
  void Assess( vtkTable*,
               vtkMultiBlockDataSet*,
               vtkTable*,
284
               int );
285

286 287 288
  // Description:
  // Execute the calculations required by the Test option.
  virtual void Test( vtkTable*,
289
                     vtkMultiBlockDataSet*,
290
                     vtkTable* ) = 0;
291

292 293 294
  //BTX
  // Description:
  // A pure virtual method to select the appropriate assessment functor.
295
  virtual void SelectAssessFunctor( vtkTable* outData,
296 297 298 299 300
                                    vtkDataObject* inMeta,
                                    vtkStringArray* rowNames,
                                    AssessFunctor*& dfunc ) = 0;
  //ETX

301
  vtkIdType NumberOfPrimaryTables;
302 303 304
  bool LearnOption;
  bool DeriveOption;
  bool AssessOption;
305
  bool TestOption;
306
  vtkStringArray* AssessNames;
307
  vtkStatisticsAlgorithmPrivate* Internals;
308

309 310 311 312 313 314
private:
  vtkStatisticsAlgorithm(const vtkStatisticsAlgorithm&); // Not implemented
  void operator=(const vtkStatisticsAlgorithm&);   // Not implemented
};

#endif