| # Gaudi Framework, version v20r3
Generated: 24 Nov 2008

# Gaudi::Utils::Histos Namespace Reference

## Detailed Description

Collection of useful utilities for manipulations with AIDA hisgograms.

Author:
  Vanya BELYAEV ibelyaev@physics.syr.edu

Date:
  2007-08-08

## Classes
class | Table
| Simple class for the customizeble printout of the histogram tables. More...
## Namespaces
namespace | Formats
| The 15 format fields are predefined now:.

## Functions
void | fill (AIDA::IHistogram1D *histo, const double value, const double weight=1.0)
| simple function to fill AIDA::IHistogram1D objects
void | fill (AIDA::IHistogram2D *histo, const double valueX, const double valueY, const double weight=1.0)
| simple function to fill AIDA::IHistogram2D objects
void | fill (AIDA::IHistogram3D *histo, const double valueX, const double valueY, const double valueZ, const double weight=1.0)
| simple function to fill AIDA::IHistogram3D objects
void | fill (AIDA::IProfile1D *histo, const double valueX, const double valueY, const double weight=1.0)
| simple function to fill AIDA::IProfile1D objects
void | fill (AIDA::IProfile2D *histo, const double valueX, const double valueY, const double valueZ, const double weight=1.0)
| simple function to fill AIDA::IProfile2D objects
std::string | htitle (const AIDA::IBaseHistogram *histo, const std::string &title="")
| get the title
std::string | htitle (const AIDA::IHistogram *histo, const std::string &title="")
| get the title
std::string | htitle (const AIDA::IHistogram1D *histo, const std::string &title="")
| get the title
std::string | htitle (const AIDA::IHistogram2D *histo, const std::string &title="")
| get the title
std::string | htitle (const AIDA::IHistogram3D *histo, const std::string &title="")
| get the title
std::string | htitle (const AIDA::IProfile *histo, const std::string &title="")
| get the title
std::string | htitle (const AIDA::IProfile1D *histo, const std::string &title="")
| get the title
std::string | htitle (const AIDA::IProfile2D *histo, const std::string &title="")
| get the title
AIDA::IBaseHistogram * | toBase (AIDA::IHistogram1D *histo)
AIDA::IBaseHistogram * | toBase (AIDA::IHistogram2D *histo)
AIDA::IBaseHistogram * | toBase (AIDA::IHistogram3D *histo)
AIDA::IBaseHistogram * | toBase (AIDA::IProfile1D *histo)
AIDA::IBaseHistogram * | toBase (AIDA::IProfile2D *histo)
std::string | path (const AIDA::IBaseHistogram *aida)
| get the path in THS for AIDA histogram
std::string | format (const AIDA::IHistogram1D *histo, const std::string &fmt)
| Make the string representation of the historgam according to the specified format.
std::string | format (const AIDA::IHistogram1D *histo, const std::string &ID, const std::string &fmt1, const std::string &fmt2)
| format a full row in table, including ID, label, path or any other "extra" identifier in string form
template<class HISTO, class STREAM, class TERMINATOR>
STREAM & | printList (HISTO first, HISTO last, const std::string &fmt, STREAM &stream, TERMINATOR term)
| print the simple sequence (list-like) of histograms as table
template<class LIST, class STREAM, class TERMINATOR>
STREAM & | printList (const LIST &histos, const std::string &fmt, STREAM &stream, TERMINATOR term)
| print the simple container of histograms as table
template<class HISTO, class STREAM, class TERMINATOR>
STREAM & | printMap (HISTO begin, HISTO end, const std::string &fmt1, const std::string &fmt2, STREAM &stream, TERMINATOR term)
| Print the "associative sequence" (e.g.
template<class MAP, class STREAM, class TERMINATOR>
STREAM & | printMap (const MAP &histos, const std::string &fmt1, const std::string &fmt2, STREAM &stream, TERMINATOR term)
| Print the "associative sequence" (e.g.
std::string | format (const std::string &val1, const std::string &val2, const std::string &fmt)
| helper method to merge the headers for short format table

## Function Documentation

void Gaudi::Utils::Histos::fill | ( | AIDA::IProfile2D * | histo,
|  | const double | valueX,
|  | const double | valueY,
|  | const double | valueZ,
|  | const double | weight = `1.0` |
| ) |  |  |

simple function to fill AIDA::IProfile2D objects

See also:
  AIDA::IProfile2D

Parameters:

  | histo | pointer to the histogram
  | valueX | value to be added to the histogram
  | valueY | value to be added to the histogram
  | valueZ | value to be added to the histogram
  | weight | the "weight" assciated with this entry

Author:
  Vanya BELYAEV ibelyaev@physics.syr.edu

Date:
  2007-10-02

Definition at line 115 of file Fill.cpp.

    00120 {
    00121   if ( 0 != histo ) { histo -> fill ( valueX , valueY , valueZ , weight ) ; }
    00122 }

void Gaudi::Utils::Histos::fill | ( | AIDA::IProfile1D * | histo,
|  | const double | valueX,
|  | const double | valueY,
|  | const double | weight = `1.0` |
| ) |  |  |

simple function to fill AIDA::IProfile1D objects

See also:
  AIDA::IProfile1D

Parameters:

  | histo | pointer to the histogram
  | valueX | value to be added to the histogram
  | valueY | value to be added to the histogram
  | weight | the "weight" assciated with this entry

Author:
  Vanya BELYAEV ibelyaev@physics.syr.edu

Date:
  2007-10-02

Definition at line 95 of file Fill.cpp.

    00099 {
    00100   if ( 0 != histo ) { histo -> fill ( valueX , valueY , weight ) ; }
    00101 }

void Gaudi::Utils::Histos::fill | ( | AIDA::IHistogram3D * | histo,
|  | const double | valueX,
|  | const double | valueY,
|  | const double | valueZ,
|  | const double | weight = `1.0` |
| ) |  |  |

simple function to fill AIDA::IHistogram3D objects

See also:
  AIDA::IHistogram3D

Parameters:

  | histo | pointer to the histogram
  | valueX | value to be added to the histogram
  | valueY | value to be added to the histogram
  | valueZ | value to be added to the histogram
  | weight | the "weight" assciated with this entry

Author:
  Vanya BELYAEV ibelyaev@physics.syr.edu

Date:
  2007-10-02

Definition at line 75 of file Fill.cpp.

    00080 {
    00081   if ( 0 != histo ) { histo -> fill ( valueX , valueY , valueZ , weight ) ; }
    00082 }

void Gaudi::Utils::Histos::fill | ( | AIDA::IHistogram2D * | histo,
|  | const double | valueX,
|  | const double | valueY,
|  | const double | weight = `1.0` |
| ) |  |  |

simple function to fill AIDA::IHistogram2D objects

See also:
  AIDA::IHistogram2D

Parameters:

  | histo | pointer to the histogram
  | valueX | value to be added to the histogram
  | valueY | value to be added to the histogram
  | weight | the "weight" assciated with this entry

Author:
  Vanya BELYAEV ibelyaev@physics.syr.edu

Date:
  2007-10-02

Definition at line 55 of file Fill.cpp.

    00059 {
    00060   if ( 0 != histo ) { histo -> fill ( valueX , valueY , weight ) ; }
    00061 }

void Gaudi::Utils::Histos::fill | ( | AIDA::IHistogram1D * | histo,
|  | const double | value,
|  | const double | weight = `1.0` |
| ) |  |  |

simple function to fill AIDA::IHistogram1D objects

See also:
  AIDA::IHistogram1D

Parameters:

  | histo | pointer to the histogram
  | value | value to be added to the histogram
  | weight | the "weight" assciated with this entry

Author:
  Vanya BELYAEV ibelyaev@physics.syr.edu

Date:
  2007-10-02

Definition at line 37 of file Fill.cpp.

    00040 {
    00041   if ( 0 != histo ) { histo->fill ( value , weight ) ; }
    00042 }

std::string Gaudi::Utils::Histos::format | ( | const std::string & | val1,
|  | const std::string & | val2,
|  | const std::string & | fmt |
| ) |  |  |

helper method to merge the headers for short format table

Author:
  Vanya BELYAEV ibelyaev@physics.syr.edu

Date:
  2007-08-07

Definition at line 209 of file HistoTableFormat.cpp.

    00212 {
    00213   using namespace boost::io ;
    00214   boost::format _fmt ( fmt ) ;
    00215   // allow various number of arguments
    00216   _fmt.exceptions ( all_error_bits ^ ( too_many_args_bit | too_few_args_bit ) ) ;
    00217   //
    00218   _fmt
    00219     % val1   // format ID
    00220     % val2 ; // format the histogram
    00221   //
    00222   return _fmt.str() ;
    00223 }

std::string Gaudi::Utils::Histos::format | ( | const AIDA::IHistogram1D * | histo,
|  | const std::string & | ID,
|  | const std::string & | fmt1,
|  | const std::string & | fmt2 |
| ) |  |  |

format a full row in table, including ID, label, path or any other "extra" identifier in string form

      using namespace Gaudi::Utils::Histos
      const AIDA::IHistogram1D* histo = ... ;

      // define short format
      const std::string fmt1 = " |%1$-30.30s %|33t| %2" ;

      // define format for the histogram
      const std::string fmt2 = ... ;

      info () <<
            format   ( "My Histo" , histo , fmt1 , fmt2 )
              << endreq ;

Parameters:

  | histo | pointer to the histogram
  | ID | historgam ID, title, label or other extra information
  | fmt1 | "short" format used for the table
  | fmt2 | format used for the histogram printout

Returns:
  formatted row

Author:
  Vanya BELYAEV ibelyaev@physics.syr.edu

Date:
  2007-08-08

Definition at line 189 of file HistoTableFormat.cpp.

    00193 {
    00194   using namespace boost::io ;
    00195   boost::format _fmt ( fmt1 ) ;
    00196   // allow various number of arguments
    00197   _fmt.exceptions ( all_error_bits ^ ( too_many_args_bit | too_few_args_bit ) ) ;
    00198   //
    00199   _fmt
    00200     % ID                         // format ID
    00201     % format ( histo , fmt2 )  ; // format the histogram
    00202   //
    00203   return _fmt.str() ;
    00204 }

std::string Gaudi::Utils::Histos::format | ( | const AIDA::IHistogram1D * | histo,
|  | const std::string & | fmt |
| ) |  |  |

Make the string representation of the historgam according to the specified format.

The method could be used to access/print various quantities

      using namespace Gaudi::Utils::Histos ;

      const AIDA::IHistogram1D* histo = ... ;

      // print title in a free format:
      std::cout << format   ( histo , "%2%" ) << std::endl ;

      // print the path in HTS in a free format:
      std::cout << format   ( histo , " path in HTS: %1% " ) << std::endl ;

      // print the formatted nEntries/Overflow/Underflow:
      std::cout <<
         format   ( histo , " #nEntries/Overflow/Underflow=%3%/%4%/%5%" )
                << std::endl ;

      // print the formatted Mean+-ErrorMean:
      std::cout <<
         format   ( histo , " Mean+-Error=(%8%+-%9%)" )
                << std::endl ;

      // print the skewness and kurtosis:
      std::cout <<
         format   ( histo , " Skewness/Kurtosis=%12%/%14% " )
                << std::endl ;

Parameters:

  | histo | reference to the histogram
  | fmt | the printout format

Author:
  Vanya BELYAEV ibelyaev@physics.syr.edu

Date:
  2007-08-08

Definition at line 154 of file HistoTableFormat.cpp.

    00156 {
    00157   if ( 0 == histo ) { return "<NULL>" ; }
    00158   using namespace Gaudi::Utils ;
    00159   using namespace boost::io ;
    00160   boost::format _fmt ( fmt ) ;
    00161   // allow various number of arguments
    00162   _fmt.exceptions ( all_error_bits ^ ( too_many_args_bit | too_few_args_bit ) ) ;
    00163
    00164   _fmt
    00165     % ( "\"" + path ( histo )    + "\"" )   //  1) histogram path
    00166     % ( "\"" + histo -> title () + "\"" )   //  2) title
    00167     % histo -> allEntries            ()     //  3) # entries
    00168     % histo -> binEntries ( AIDA::IAxis::UNDERFLOW_BIN ) // 4) # underflow
    00169     % histo -> binEntries ( AIDA::IAxis::OVERFLOW_BIN  ) // 5) # overflow
    00170     % histo -> equivalentBinEntries  ()     //  6) equivalent entries
    00171     % histo -> sumBinHeights         ()     //  7) integral
    00172     % histo -> mean                  ()     //  8) mean value
    00173     % HistoStats:: meanErr    ( histo )     //  9) error in mean
    00174     % histo -> rms                   ()     // 10) rms
    00175     % HistoStats::rmsErr      ( histo )     // 11) error in rms
    00176     % HistoStats::skewness    ( histo )     // 12) skewness
    00177     % HistoStats::skewnessErr ( histo )     // 13) error in skewness
    00178     % HistoStats::kurtosis    ( histo )     // 14) kurtosis
    00179     % HistoStats::kurtosisErr ( histo ) ;   // 15) error in kurtosis
    00180   //
    00181   return _fmt.str() ;
    00182 }

std::string Gaudi::Utils::Histos::htitle | ( | const AIDA::IProfile2D * | histo,
|  | const std::string & | title = `""` |
| ) |  |  |

get the title

Definition at line 188 of file Fill.cpp.

    00190 { return htitle_ ( histo , title ) ; }

std::string Gaudi::Utils::Histos::htitle | ( | const AIDA::IProfile1D * | histo,
|  | const std::string & | title = `""` |
| ) |  |  |

get the title

Definition at line 181 of file Fill.cpp.

    00183 { return htitle_ ( histo , title ) ; }

std::string Gaudi::Utils::Histos::htitle | ( | const AIDA::IProfile * | histo,
|  | const std::string & | title = `""` |
| ) |  |  |

get the title

Definition at line 174 of file Fill.cpp.

    00176 { return htitle_ ( histo , title ) ; }

std::string Gaudi::Utils::Histos::htitle | ( | const AIDA::IHistogram3D * | histo,
|  | const std::string & | title = `""` |
| ) |  |  |

get the title

Definition at line 167 of file Fill.cpp.

    00169 { return htitle_ ( histo , title ) ; }

std::string Gaudi::Utils::Histos::htitle | ( | const AIDA::IHistogram2D * | histo,
|  | const std::string & | title = `""` |
| ) |  |  |

get the title

Definition at line 160 of file Fill.cpp.

    00162 { return htitle_ ( histo , title ) ; }

std::string Gaudi::Utils::Histos::htitle | ( | const AIDA::IHistogram1D * | histo,
|  | const std::string & | title = `""` |
| ) |  |  |

get the title

Definition at line 153 of file Fill.cpp.

    00155 { return htitle_ ( histo , title ) ; }

std::string Gaudi::Utils::Histos::htitle | ( | const AIDA::IHistogram * | histo,
|  | const std::string & | title = `""` |
| ) |  |  |

get the title

Definition at line 146 of file Fill.cpp.

    00148 { return htitle_ ( histo , title ) ; }

std::string Gaudi::Utils::Histos::htitle | ( | const AIDA::IBaseHistogram * | histo,
|  | const std::string & | title = `""` |
| ) |  |  |

get the title

Definition at line 139 of file Fill.cpp.

    00141 { return htitle_ ( histo , title ) ; }

std::string Gaudi::Utils::Histos::path | ( | const AIDA::IBaseHistogram * | aida | ) |

get the path in THS for AIDA histogram

Author:
  Vanya BELYAEV ibelyaev@physics.syr.edu

Date:
  2007-08-08

Definition at line 136 of file HistoTableFormat.cpp.

    00137 {
    00138   if ( 0 == aida     ) { return "" ; }                          // RETURN
    00139   const DataObject* object   = dynamic_cast<const DataObject*>( aida ) ;
    00140   if ( 0 == object   ) { return "" ; }                          // RETURN
    00141   IRegistry*        registry = object->registry() ;
    00142   if ( 0 == registry ) { return "" ; }                          // RETURN
    00143   std::string _path = registry->identifier() ;
    00144   std::string::size_type n = _path.find("/stat/") ;
    00145   if ( 0 == n ) { return std::string(_path,6) ; }               // RETURN
    00146   return _path ;                                                // RETURN
    00147 }

template<class LIST, class STREAM, class TERMINATOR>

STREAM& Gaudi::Utils::Histos::printList | ( | const LIST & | histos,
|  | const std::string & | fmt,
|  | STREAM & | stream,
|  | TERMINATOR | term |
| ) |  |  | `[inline]`

print the simple container of histograms as table

      using namespace Gaudi::Utils::Histos ;

      SEQUENCE histos = ... ;

      // print a table with three columns:  path, title and #entries

      printList
        ( histos          ,
          " | %1$|-40.40s | %2$-30.30s | %3$=7d | " ,
          std::cout       ,
          '\n'            ) ;

Parameters:

  | histos | the sequence of histograms
  | stream | the stream to be used for printout
  | term | the terminmator for the stream
  | fmt | the format to be used

Definition at line 230 of file HistoTableFormat.h.

    00234       {
    00235         return printList
    00236           ( histos.begin () , histos.end  () , fmt , stream , term ) ;
    00237       }

template<class HISTO, class STREAM, class TERMINATOR>

STREAM& Gaudi::Utils::Histos::printList | ( | HISTO | first,
|  | HISTO | last,
|  | const std::string & | fmt,
|  | STREAM & | stream,
|  | TERMINATOR | term |
| ) |  |  | `[inline]`

print the simple sequence (list-like) of histograms as table

      SEQUENCE histos = ... ;

      // print a table with three colums  path, title and #entries

      Gaudi::Utils::Histos::printList
        ( histos.begin () ,
          histos.end   () ,
          " | %1$|-40.40s | %2$-30.30s | %3$=7d | " ,
          std::cout       ,
          '\n'            ) ;

Parameters:

  | first | begin-iterator for the sequence
  | last | end-iterator for the sequence
  | stream | the stream to be used for printout
  | term | the terminmator for the stream
  | fmt | the format to be used

Definition at line 194 of file HistoTableFormat.h.

    00199       {
    00200         for ( ; first != last ; ++first )
    00201         { stream << format   ( *first , fmt ) << term ; }  // print table rows
    00202         return stream ;                                    // RETURN
    00203       }

template<class MAP, class STREAM, class TERMINATOR>

STREAM& Gaudi::Utils::Histos::printMap | ( | const MAP & | histos,
|  | const std::string & | fmt1,
|  | const std::string & | fmt2,
|  | STREAM & | stream,
|  | TERMINATOR | term |
| ) |  |  | `[inline]`

Print the "associative sequence" (e.g.

part of std:map) of histograms as table:

      using namespace Gaudi::Utils::Histos ;

      const std::map<std::string,AIDA::IHistogram1D*>& m = ... ;

      printMap
       ( m          ,
         "| %1$-10.10s | %2% " , // short format
         Gaudi::Utils::Histos::Formats::histoFormatOnly ,
         always()   ,
         endreq     ) ;

Print only mean and rms:

      using namespace Gaudi::Utils::Histos ;

      const std::map<GaudiAlg::ID,AIDA::IHistogram1D*>& m = ... ;

      printMap
        ( m          ,
          "| %1$-10.10s | %2% "    , // short format
          " %8$10.5g+-%10$-10.5g|", // mean+-rms
          always()   ,
          endreq     ) ;

Parameters:

  | begin | 'begin'-iterator for the mapping sequence
  | end | 'end'-iterator for the mapping sequence
  | fmt1 | 'short' format for the table printout
  | fmt3 | format for the printout of the histogram
  | stream | the stream for printout
  | term | stream terminator

Definition at line 346 of file HistoTableFormat.h.

    00351       {
    00352         return printMap
    00353           ( histos.begin () , histos.end() , fmt1 , fmt2 , stream , term ) ;
    00354       }

template<class HISTO, class STREAM, class TERMINATOR>

STREAM& Gaudi::Utils::Histos::printMap | ( | HISTO | begin,
|  | HISTO | end,
|  | const std::string & | fmt1,
|  | const std::string & | fmt2,
|  | STREAM & | stream,
|  | TERMINATOR | term |
| ) |  |  | `[inline]`

Print the "associative sequence" (e.g.

part of std:map) of histograms as table:

      using namespace Gaudi::Utils::Histos ;

      const std::map<std::string,AIDA::IHistogram1D*>& m = ... ;

      printMap
       ( m.begin () ,
         m.end   () ,
         "| %1$-10.10s | %2% " , // short format
         Gaudi::Utils::Histos::Formats::histoFormatOnly ,
         always()   ,
         endreq     ) ;

Print only mean and rms:

      using namespace Gaudi::Utils::Histos ;

      const std::map<GaudiAlg::ID,AIDA::IHistogram1D*>& m = ... ;

      printMap
        ( m.begin () ,
          m.end   () ,
          "| %1$-10.10s | %2% "    , // short format
          " %8$10.5g+-%10$-10.5g|", // mean+-rms
          always()   ,
          endreq     ) ;

Parameters:

  | begin | 'begin'-iterator for the mapping sequence
  | end | 'end'-iterator for the mapping sequence
  | fmt1 | 'short' format for the table printout
  | fmt3 | format for the printout of the histogram
  | stream | the stream for printout
  | term | stream terminator

Definition at line 285 of file HistoTableFormat.h.

    00291       {
    00292         for ( ; begin != end ; ++begin )
    00293         {
    00294           stream << format
    00295             ( begin -> second , // the histogram
    00296               begin -> first  , // the key
    00297               fmt1  ,  fmt2   ) << term ;
    00298         }
    00299         return stream ;
    00300       }

AIDA::IBaseHistogram * Gaudi::Utils::Histos::toBase | ( | AIDA::IProfile2D * | histo | ) |

Definition at line 210 of file Fill.cpp.

    00210 { return histo ; }

AIDA::IBaseHistogram * Gaudi::Utils::Histos::toBase | ( | AIDA::IProfile1D * | histo | ) |

Definition at line 206 of file Fill.cpp.

    00206 { return histo ; }

AIDA::IBaseHistogram * Gaudi::Utils::Histos::toBase | ( | AIDA::IHistogram3D * | histo | ) |

Definition at line 202 of file Fill.cpp.

    00202 { return histo ; }

AIDA::IBaseHistogram * Gaudi::Utils::Histos::toBase | ( | AIDA::IHistogram2D * | histo | ) |

Definition at line 198 of file Fill.cpp.

    00198 { return histo ; }

AIDA::IBaseHistogram * Gaudi::Utils::Histos::toBase | ( | AIDA::IHistogram1D * | histo | ) |

Definition at line 194 of file Fill.cpp.

    00194 { return histo ; }