SH::Sample Class Reference

a base class that manages a set of files belonging to a particular data set and the associated meta-data. More...

#include <Sample.h>

Inheritance diagram for SH::Sample:
SH::SampleComposite SH::SampleGrid SH::SampleHist SH::SampleLocal SH::SampleMeta

List of all members.

Public Member Functions

void testInvariant () const
 test the invariant of this object
virtual ~Sample ()
 standard destructor
const std::string & name () const
 the name of the sample we are using
void name (std::string val_name)
 set the value of name
std::size_t numFiles () const
 the number of files in the sample
std::string fileName (std::size_t index) const
 the name of the file with the given index
SamplePtr makeLocal () const
 Make this a local sample, i.e. one which can be directly opened with TFile::Open.
const TagList & tags () const
 the tag list we are using
void tags (const TagList &tags)
 set the content of tags()
void addTag (const std::string &tag)
 add a tag to the content of tags()
void updateLocation (const std::string &from, const std::string &to)
 update all file references starting with from to to
MetaObject * meta ()
 the meta-information for this sample
const MetaObject * meta () const
std::vector< std::string > makeFileList () const
 make a list of all files, prestaging them if necessary
TChain * makeTChain () const
 create a TChain object, containing all these files
TDSet * makeTDSet () const
 create a TDSet object, containing all these files
TObject * readHist (const std::string &name) const
 read an object from a histogram file
bool contains (const std::string &name) const
 whether this sample contains a sample of the given name
void addSamples (SampleHandler &result)
 add all samples this sample corresponds to to the given sample handler
void print () const
 print the debugging output to the screen
void printContent () const
Long64_t getNumEntries () const
 get the number of entries
 RCU_DEPRECATED ("use meta() instead, or (preferably) access of meta-data by name") TCollection *metaDataList()
 get the meta-data list
 RCU_DEPRECATED ("use meta() instead, or (preferably) access of meta-data by name") const TCollection *metaDataList() const
void removeMeta (const std::string &name)
void addReplaceMeta (TNamed *meta_swallow)
TObject * getMeta (const std::string &name)
const TObject * getMeta (const std::string &name) const
double getMetaDouble (const std::string &name, double def_val=0) const
std::string getMetaString (const std::string &name, const std::string &def_val="") const
void setMetaDouble (const std::string &name, double value)
void setMetaString (const std::string &name, const std::string &value)
void fetchMeta (const Sample &source)

Protected Member Functions

 Sample (const std::string &name)
 standard constructor
virtual std::size_t getNumFiles () const =0
virtual std::string getFileName (std::size_t index) const =0
virtual SamplePtr doMakeLocal () const =0
virtual std::vector< std::string > doMakeFileList () const =0
virtual void doUpdateLocation (const std::string &from, const std::string &to)
virtual TObject * doReadHist (const std::string &name) const
virtual bool getContains (const std::string &name) const
virtual void doAddSamples (SampleHandler &result)

Friends

class SamplePtr

Detailed Description

a base class that manages a set of files belonging to a particular data set and the associated meta-data.

While for most people this is essentially just a fancy file list, it hides a lot of flexibility. Besides a simple file list, this could also be a sample on the grid, or on tape storage that first needs to be pre-staged before it can be used.

Constructor & Destructor Documentation

virtual SH::Sample::~Sample (  )  [virtual]

standard destructor

Guarantee
no-fail
SH::Sample::Sample ( const std::string &  name  )  [protected]

standard constructor

Guarantee
strong
Failures
low level errors II

Member Function Documentation

void SH::Sample::addReplaceMeta ( TNamed *  meta_swallow  ) 

add a meta-data object and remove any existing meta-data with the same name

Parameters:
meta_swallow the meta-object to add
Precondition:
meta_swallow != 0
Guarantee
basic, may delete some entries without adding the new one
Failures
out of memory II

void SH::Sample::addSamples ( SampleHandler &  result  ) 

add all samples this sample corresponds to to the given sample handler

Guarantee
basic, may only add some
Failures
out of memory II
Rationale this is used with composite samples to find the
actual list of samples to run on.
void SH::Sample::addTag ( const std::string &  tag  ) 

add a tag to the content of tags()

Guarantee
strong
Failures
out of memory II
bool SH::Sample::contains ( const std::string &  name  )  const

whether this sample contains a sample of the given name

Returns:
whether this sample contains a sample of the given name (or whether the sample itself has the given name)
Guarantee
no-fail
Rationale
this is used with composite sample to make sure we don't create ring like structures that would lead to endless recursion. the reason to check by name, not by address is that we will probably want to add these samples to a sample handler at some point.
virtual void SH::Sample::doAddSamples ( SampleHandler &  result  )  [protected, virtual]

add all samples this sample corresponds to to the given sample handler

Guarantee
basic, may only add some
Failures
out of memory II
Rationale this is used with composite samples to find the
actual list of samples to run on.

Rationale
the virtual part of SH::Sample::addSamples()

Reimplemented in SH::SampleComposite.

virtual std::vector<std::string> SH::Sample::doMakeFileList (  )  const [protected, pure virtual]

make a list of all files, prestaging them if necessary

Guarantee
basic
Failures
out of memory III
file catalogue failures
prestaging failures

Rationale
the virtual part of Sample::makeFileList

Implemented in SH::SampleComposite, SH::SampleGrid, SH::SampleHist, SH::SampleLocal, and SH::SampleMeta.

virtual SamplePtr SH::Sample::doMakeLocal (  )  const [protected, pure virtual]

Make this a local sample, i.e. one which can be directly opened with TFile::Open.

Returns:
the local sample, or "this" if this already is a local sample
Guarantee
strong
Failures
out of memory III
can not make local sample

Rationale
the virtual part of SH::Sample::makeLocal()

Implemented in SH::SampleComposite, SH::SampleGrid, SH::SampleHist, and SH::SampleLocal.

virtual TObject* SH::Sample::doReadHist ( const std::string &  name  )  const [protected, virtual]

read an object from a histogram file

Returns
the object read or NULL if it was not found
Guarantee
strong
Failures
out of memory II
i/o errors

Rationale
the virtual part of SH::Sample::readHist()

Reimplemented in SH::SampleHist.

virtual void SH::Sample::doUpdateLocation ( const std::string &  from,
const std::string &  to 
) [protected, virtual]

update all file references starting with from to to

Parameters:
from the original path to the data area
to the new path to the data area
Guarantee
basic, may update partially
Failures
out of memory II
Precondition:
!from.empty()
Postcondition:
!to.empty()
Rationale
this is needed when moving data around without recreating the samples from scratch

Rationale
the virtual part of SH::Sample::updateLocation()

Reimplemented in SH::SampleComposite, SH::SampleHist, and SH::SampleLocal.

void SH::Sample::fetchMeta ( const Sample &  source  ) 

fetch the meta-data from the given sample. fields that have a name that starts with "nc_" are not copied.

Guarantee
basic, may only fetch some meta-data
Failures
out of memory II
Rationale this is used by EventLoop, to copy the
meta-data from the input samples to the output samples. the prefix "nc_" is used to indicate meta-data entries that only apply to the current sample, or are options to the specific EventLoop job.

std::string SH::Sample::fileName ( std::size_t  index  )  const

the name of the file with the given index

Parameters:
index the index of the file
Guarantee
no-fail
Precondition:
index < numFiles()
Postcondition:
!result.empty()
Warning:
this is meant more for debugging and may or may not do what you want, e.g. if this is a grid dataset the file may not be directly accessible.
virtual bool SH::Sample::getContains ( const std::string &  name  )  const [protected, virtual]

whether this sample contains a sample of the given name

Returns:
whether this sample contains a sample of the given name (or whether the sample itself has the given name)
Guarantee
no-fail
Rationale
this is used with composite sample to make sure we don't create ring like structures that would lead to endless recursion. the reason to check by name, not by address is that we will probably want to add these samples to a sample handler at some point.

Rationale
the virtual part of SH::Sample::contains()

Reimplemented in SH::SampleComposite.

virtual std::string SH::Sample::getFileName ( std::size_t  index  )  const [protected, pure virtual]

the name of the file with the given index

Parameters:
index the index of the file
Guarantee
no-fail
Precondition:
index < numFiles()
Postcondition:
!result.empty()
Warning:
this is meant more for debugging and may or may not do what you want, e.g. if this is a grid dataset the file may not be directly accessible.

Rationale
the virtual part of Sample::fileName()

Implemented in SH::SampleComposite, SH::SampleGrid, SH::SampleHist, and SH::SampleLocal.

const TObject* SH::Sample::getMeta ( const std::string &  name  )  const

the meta-data object with the given name

Returns:
the meta-data object with the given name, or NULL if there is no such entry
Parameters:
name the name of the meta-data object
Guarantee
no-fail

TObject* SH::Sample::getMeta ( const std::string &  name  ) 

the meta-data object with the given name

Returns:
the meta-data object with the given name, or NULL if there is no such entry
Parameters:
name the name of the meta-data object
Guarantee
no-fail

double SH::Sample::getMetaDouble ( const std::string &  name,
double  def_val = 0 
) const

the meta-data double with the given name

Returns:
the meta-data with the given name, or def_value if that meta-data is not available or does not have the right type
Parameters:
name the name of the meta-data object
dev_val the value to return if no meta-data object of the given name exists, or if it does not have the right type
Guarantee
no-fail

std::string SH::Sample::getMetaString ( const std::string &  name,
const std::string &  def_val = "" 
) const

the meta-data string with the given name

Returns:
the meta-data with the given name, or def_value if that meta-data is not available or does not have the right type
Parameters:
name the name of the meta-data object
dev_val the value to return if no meta-data object of the given name exists, or if it does not have the right type
Guarantee
no-fail
Rationale
I return the string by value, because returning by reference seems to break the python binding.

Long64_t SH::Sample::getNumEntries (  )  const

get the number of entries

Guarantee
strong
Failures
i/o errors
virtual std::size_t SH::Sample::getNumFiles (  )  const [protected, pure virtual]

the number of files in the sample

Guarantee
no-fail

Rationale
the virtual part of Sample::numFiles()

Implemented in SH::SampleComposite, SH::SampleGrid, SH::SampleHist, and SH::SampleLocal.

std::vector<std::string> SH::Sample::makeFileList (  )  const

make a list of all files, prestaging them if necessary

Guarantee
basic
Failures
out of memory III
file catalogue failures
prestaging failures
SamplePtr SH::Sample::makeLocal (  )  const

Make this a local sample, i.e. one which can be directly opened with TFile::Open.

Returns:
the local sample, or "this" if this already is a local sample
Guarantee
strong
Failures
out of memory III
can not make local sample
TChain* SH::Sample::makeTChain (  )  const

create a TChain object, containing all these files

Guarantee
strong
Failures
out of memory II
chain making not supported
Postcondition:
result != 0
TDSet* SH::Sample::makeTDSet (  )  const

create a TDSet object, containing all these files

Guarantee
strong
Failures
out of memory II
Failures
dataset making not supported
Postcondition:
result != 0
const MetaObject* SH::Sample::meta (  )  const

the meta-information for this sample

Guarantee
no-fail
Invariant:
meta != 0

MetaObject* SH::Sample::meta (  ) 

the meta-information for this sample

Guarantee
no-fail
Invariant:
meta != 0
void SH::Sample::name ( std::string  val_name  ) 

set the value of name

Guarantee
no-fail / strong
Failures
out of memory II
Failures
Sample already owned by SampleHandler
Rationale
setting the sample name can be beneficial, if the sample auto-discovery set a duplicate (or otherwise unsuitable) name.
Warning:
this must be done before adding it to the SampleHandler, or alternatively a clone must be made that can then be added to a new SampleHandler.
const std::string& SH::Sample::name (  )  const

the name of the sample we are using

Guarantee
no-fail
std::size_t SH::Sample::numFiles (  )  const

the number of files in the sample

Guarantee
no-fail
void SH::Sample::print (  )  const

print the debugging output to the screen

Guarantee
basic, may print partially
Failures
out of memory II
Failures
stream errors
void SH::Sample::printContent (  )  const

print the debugging output to the screen

Guarantee
basic, may print partially
Failures
out of memory II
Failures
stream errors

Rationale
added a second print method for python where print is a keyword
SH::Sample::RCU_DEPRECATED ( "use meta()   instead,
or(preferably) access of meta-data by name"   
) const

SH::Sample::RCU_DEPRECATED ( "use meta()   instead,
or(preferably) access of meta-data by name"   
)

get the meta-data list

Guarantee
no-fail
Postcondition:
result != 0
Deprecated:
use meta() instead, or (preferably) access of meta-data by name
TObject* SH::Sample::readHist ( const std::string &  name  )  const

read an object from a histogram file

Returns
the object read or NULL if it was not found
Guarantee
strong
Failures
out of memory II
i/o errors
void SH::Sample::removeMeta ( const std::string &  name  ) 

remove all meta-information with the given name

Parameters:
name the meta-data name to remove
Guarantee
basic, may only delete some entries
Failures
out of memory II

void SH::Sample::setMetaDouble ( const std::string &  name,
double  value 
)

set the meta-data double with the given name

Parameters:
name the name of the meta-data
value the value to which it is set
Guarantee
basic, may clear old entry without adding new one
Failures
out of memory II

void SH::Sample::setMetaString ( const std::string &  name,
const std::string &  value 
)

set the meta-data string with the given name

Parameters:
name the name of the meta-data
value the value to which it is set
Guarantee
basic, may clear old entry without adding new one
Failures
out of memory II

void SH::Sample::tags ( const TagList &  tags  ) 

set the content of tags()

Guarantee
strong
Failures
out of memory II
const TagList& SH::Sample::tags (  )  const

the tag list we are using

Guarantee
no-fail
void SH::Sample::testInvariant (  )  const

test the invariant of this object

Guarantee
no-fail

Reimplemented in SH::SampleComposite, SH::SampleGrid, SH::SampleHist, SH::SampleLocal, and SH::SampleMeta.

void SH::Sample::updateLocation ( const std::string &  from,
const std::string &  to 
)

update all file references starting with from to to

Parameters:
from the original path to the data area
to the new path to the data area
Guarantee
basic, may update partially
Failures
out of memory II
Precondition:
!from.empty()
Postcondition:
!to.empty()
Rationale
this is needed when moving data around without recreating the samples from scratch
The documentation for this class was generated from the following file:
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines
Generated on 1 Dec 2017 for RootCore Packages by  doxygen 1.6.1