ROOT logo
ROOT » HIST » HIST » THnSparse

class THnSparse: public THnBase



    Efficient multidimensional histogram.

 Use a THnSparse instead of TH1 / TH2 / TH3 / array for histogramming when
 only a small fraction of bins is filled. A 10-dimensional histogram with 10
 bins per dimension has 10^10 bins; in a naive implementation this will not
 fit in memory. THnSparse only allocates memory for the bins that have
 non-zero bin content instead, drastically reducing both the memory usage
 and the access time.

 To construct a THnSparse object you must use one of its templated, derived
 classes:
 THnSparseD (typedef for THnSparseT<ArrayD>): bin content held by a Double_t,
 THnSparseF (typedef for THnSparseT<ArrayF>): bin content held by a Float_t,
 THnSparseL (typedef for THnSparseT<ArrayL>): bin content held by a Long_t,
 THnSparseI (typedef for THnSparseT<ArrayI>): bin content held by an Int_t,
 THnSparseS (typedef for THnSparseT<ArrayS>): bin content held by a Short_t,
 THnSparseC (typedef for THnSparseT<ArrayC>): bin content held by a Char_t,

 They take name and title, the number of dimensions, and for each dimension
 the number of bins, the minimal, and the maximal value on the dimension's
 axis. A TH2 h("h","h",10, 0., 10., 20, -5., 5.) would correspond to
   Int_t bins[2] = {10, 20};
   Double_t xmin[2] = {0., -5.};
   Double_t xmax[2] = {10., 5.};
   THnSparse hs("hs", "hs", 2, bins, min, max);

 * Filling
 A THnSparse is filled just like a regular histogram, using
 THnSparse::Fill(x, weight), where x is a n-dimensional Double_t value.
 To take errors into account, Sumw2() must be called before filling the
 histogram.
 Bins are allocated as needed; the status of the allocation can be observed
 by GetSparseFractionBins(), GetSparseFractionMem().

 * Fast Bin Content Access
 When iterating over a THnSparse one should only look at filled bins to save
 processing time. The number of filled bins is returned by
 THnSparse::GetNbins(); the bin content for each (linear) bin number can
 be retrieved by THnSparse::GetBinContent(linidx, (Int_t*)coord).
 After the call, coord will contain the bin coordinate of each axis for the bin
 with linear index linidx. A possible call would be
   cout << hs.GetBinContent(0, coord);
   cout <<" is the content of bin [x = " << coord[0] "
        << " | y = " << coord[1] << "]" << endl;

 * Efficiency
 TH1 and TH2 are generally faster than THnSparse for one and two dimensional
 distributions. THnSparse becomes competitive for a sparsely filled TH3
 with large numbers of bins per dimension. The tutorial hist/sparsehist.C
 shows the turning point. On a AMD64 with 8GB memory, THnSparse "wins"
 starting with a TH3 with 30 bins per dimension. Using a THnSparse for a
 one-dimensional histogram is only reasonable if it has a huge number of bins.

 * Projections
 The dimensionality of a THnSparse can be reduced by projecting it to
 1, 2, 3, or n dimensions, which can be represented by a TH1, TH2, TH3, or
 a THnSparse. See the Projection() members. To only project parts of the
 histogram, call
   THnSparse::GetAxis(12)->SetRange(from_bin, to_bin);

 * Internal Representation
 An entry for a filled bin consists of its n-dimensional coordinates and
 its bin content. The coordinates are compacted to use as few bits as
 possible; e.g. a histogram with 10 bins in x and 20 bins in y will only
 use 4 bits for the x representation and 5 bits for the y representation.
 This is handled by the internal class THnSparseCompactBinCoord.
 Bin data (content and coordinates) are allocated in chunks of size
 fChunkSize; this parameter can be set when constructing a THnSparse. Each
 chunk is represented by an object of class THnSparseArrayChunk.

 Translation from an n-dimensional bin coordinate to the linear index within
 the chunks is done by GetBin(). It creates a hash from the compacted bin
 coordinates (the hash of a bin coordinate is the compacted coordinate itself
 if it takes less than 8 bytes, the size of a Long64_t.
 This hash is used to lookup the linear index in the TExMap member fBins;
 the coordinates of the entry fBins points to is compared to the coordinates
 passed to GetBin(). If they do not match, these two coordinates have the same
 hash - which is extremely unlikely but (for the case where the compact bin
 coordinates are larger than 4 bytes) possible. In this case, fBinsContinued
 contains a chain of linear indexes with the same hash. Iterating through this
 chain and comparing each bin coordinates with the one passed to GetBin() will
 retrieve the matching bin.

Function Members (Methods)

 
    This is an abstract class, constructors will not be documented.
    Look at the header to check for available constructors.

public:
virtual~THnSparse()
voidTObject::AbstractMethod(const char* method) const
voidTHnBase::Add(const THnBase* h, Double_t c = 1.)
voidTHnBase::Add(const TH1* hist, Double_t c = 1.)
voidAddBinContent(const Int_t* idx, Double_t v = 1.)
virtual voidAddBinContent(Long64_t bin, Double_t v = 1.)
virtual voidAddBinError2(Long64_t bin, Double_t e2)
virtual voidTObject::AppendPad(Option_t* option = "")
virtual voidTHnBase::Browse(TBrowser* b)
voidTHnBase::CalculateErrors(Bool_t calc = kTRUE)
static TClass*Class()
virtual const char*TObject::ClassName() const
virtual voidTNamed::Clear(Option_t* option = "")
virtual TObject*TNamed::Clone(const char* newname = "") const
virtual Int_tTNamed::Compare(const TObject* obj) const
Double_tTHnBase::ComputeIntegral()
virtual voidTNamed::Copy(TObject& named) const
virtual ROOT::THnBaseBinIter*CreateIter(Bool_t respectAxisRange) const
static THnSparse*CreateSparse(const char* name, const char* title, const TH1* h1, Int_t chunkSize = 1024*16)
static THnSparse*CreateSparse(const char* name, const char* title, const THnBase* hn, Int_t chunkSize = 1024*16)
virtual voidTObject::Delete(Option_t* option = "")MENU
virtual Int_tTObject::DistancetoPrimitive(Int_t px, Int_t py)
voidTHnBase::Divide(const THnBase* h)
voidTHnBase::Divide(const THnBase* h1, const THnBase* h2, Double_t c1 = 1., Double_t c2 = 1., Option_t* option = "")
virtual voidTObject::Draw(Option_t* option = "")
virtual voidTObject::DrawClass() constMENU
virtual TObject*TObject::DrawClone(Option_t* option = "") constMENU
virtual voidTObject::Dump() constMENU
virtual voidTObject::Error(const char* method, const char* msgfmt) const
virtual voidTObject::Execute(const char* method, const char* params, Int_t* error = 0)
virtual voidTObject::Execute(TMethod* method, TObjArray* params, Int_t* error = 0)
virtual voidTObject::ExecuteEvent(Int_t event, Int_t px, Int_t py)
virtual voidTObject::Fatal(const char* method, const char* msgfmt) const
Long64_tTHnBase::Fill(const Double_t* x, Double_t w = 1.)
Long64_tTHnBase::Fill(const char** name, Double_t w = 1.)
virtual voidTNamed::FillBuffer(char*& buffer)
virtual TObject*TObject::FindObject(const char* name) const
virtual TObject*TObject::FindObject(const TObject* obj) const
TFitResultPtrTHnBase::Fit(TF1* f1, Option_t* option = "", Option_t* goption = "")
TAxis*THnBase::GetAxis(Int_t dim) const
virtual Long64_tGetBin(const Int_t* idx) const
virtual Long64_tGetBin(const Double_t* x) const
virtual Long64_tGetBin(const char** name) const
virtual Long64_tGetBin(const Int_t* idx, Bool_t allocate = kTRUE)
virtual Long64_tGetBin(const Double_t* x, Bool_t allocate = kTRUE)
virtual Long64_tGetBin(const char** name, Bool_t allocate = kTRUE)
Double_tGetBinContent(const Int_t* idx) const
virtual Double_tGetBinContent(Long64_t bin, Int_t* idx = 0) const
Double_tTHnBase::GetBinError(const Int_t* idx) const
Double_tTHnBase::GetBinError(Long64_t linidx) const
virtual Double_tGetBinError2(Long64_t linidx) const
Bool_tTHnBase::GetCalculateErrors() const
Int_tGetChunkSize() const
virtual Option_t*TObject::GetDrawOption() const
static Long_tTObject::GetDtorOnly()
Double_tTHnBase::GetEntries() const
virtual const char*TObject::GetIconName() const
TObjArray*THnBase::GetListOfAxes()
const TObjArray*THnBase::GetListOfAxes() const
TList*THnBase::GetListOfFunctions()
virtual const char*TNamed::GetName() const
virtual Long64_tGetNbins() const
Int_tGetNChunks() const
Int_tTHnBase::GetNdimensions() const
virtual char*TObject::GetObjectInfo(Int_t px, Int_t py) const
static Bool_tTObject::GetObjectStat()
virtual Option_t*TObject::GetOption() const
voidTHnBase::GetRandom(Double_t* rand, Bool_t subBinRandom = kTRUE)
Double_tGetSparseFractionBins() const
Double_tGetSparseFractionMem() const
Double_tTHnBase::GetSumw() const
Double_tTHnBase::GetSumw2() const
Double_tTHnBase::GetSumwx(Int_t dim) const
Double_tTHnBase::GetSumwx2(Int_t dim) const
virtual const char*TNamed::GetTitle() const
virtual UInt_tTObject::GetUniqueID() const
Double_tTHnBase::GetWeightSum() const
virtual Bool_tTObject::HandleTimer(TTimer* timer)
virtual ULong_tTNamed::Hash() const
virtual voidTObject::Info(const char* method, const char* msgfmt) const
virtual Bool_tTObject::InheritsFrom(const char* classname) const
virtual Bool_tTObject::InheritsFrom(const TClass* cl) const
virtual voidTObject::Inspect() constMENU
voidTObject::InvertBit(UInt_t f)
virtual TClass*IsA() const
virtual Bool_tTObject::IsEqual(const TObject* obj) const
virtual Bool_tTHnBase::IsFolder() const
Bool_tTHnBase::IsInRange(Int_t* coord) const
Bool_tTObject::IsOnHeap() const
virtual Bool_tTNamed::IsSortable() const
Bool_tTObject::IsZombie() const
virtual voidTNamed::ls(Option_t* option = "") const
voidTObject::MayNotUse(const char* method) const
Long64_tTHnBase::Merge(TCollection* list)
voidTHnBase::Multiply(const THnBase* h)
voidTHnBase::Multiply(TF1* f, Double_t c = 1.)
virtual Bool_tTObject::Notify()
voidTObject::Obsolete(const char* method, const char* asOfVers, const char* removedFromVers) const
static voidTObject::operator delete(void* ptr)
static voidTObject::operator delete(void* ptr, void* vp)
static voidTObject::operator delete[](void* ptr)
static voidTObject::operator delete[](void* ptr, void* vp)
void*TObject::operator new(size_t sz)
void*TObject::operator new(size_t sz, void* vp)
void*TObject::operator new[](size_t sz)
void*TObject::operator new[](size_t sz, void* vp)
virtual voidTObject::Paint(Option_t* option = "")
virtual voidTObject::Pop()
virtual voidTHnBase::Print(Option_t* option = "") const
voidTHnBase::PrintBin(Int_t* coord, Option_t* options) const
voidTHnBase::PrintBin(Long64_t idx, Option_t* options) const
voidTHnBase::PrintEntries(Long64_t from = 0, Long64_t howmany = -1, Option_t* options = 0) const
TH1D*Projection(Int_t xDim, Option_t* option = "") const
TH2D*Projection(Int_t yDim, Int_t xDim, Option_t* option = "") const
THnSparse*Projection(Int_t ndim, const Int_t* dim, Option_t* option = "") const
TH3D*Projection(Int_t xDim, Int_t yDim, Int_t zDim, Option_t* option = "") const
THnBase*THnBase::ProjectionND(Int_t ndim, const Int_t* dim, Option_t* option = "") const
virtual Int_tTObject::Read(const char* name)
THnSparse*Rebin(Int_t group) const
THnSparse*Rebin(const Int_t* group) const
voidTHnBase::RebinnedAdd(const THnBase* h, Double_t c = 1.)
virtual voidTObject::RecursiveRemove(TObject* obj)
virtual voidReset(Option_t* option = "")
voidTObject::ResetBit(UInt_t f)
virtual voidTObject::SaveAs(const char* filename = "", Option_t* option = "") constMENU
virtual voidTObject::SavePrimitive(ostream& out, Option_t* option = "")
voidTHnBase::Scale(Double_t c)
voidSetBinContent(const Int_t* idx, Double_t v)
virtual voidSetBinContent(Long64_t bin, Double_t v)
voidTHnBase::SetBinEdges(Int_t idim, const Double_t* bins)
voidTHnBase::SetBinError(const Int_t* idx, Double_t e)
voidTHnBase::SetBinError(Long64_t bin, Double_t e)
virtual voidSetBinError2(Long64_t bin, Double_t e2)
voidTObject::SetBit(UInt_t f)
voidTObject::SetBit(UInt_t f, Bool_t set)
virtual voidTObject::SetDrawOption(Option_t* option = "")MENU
static voidTObject::SetDtorOnly(void* obj)
voidTHnBase::SetEntries(Double_t entries)
virtual voidSetFilledBins(Long64_t nbins)
virtual voidTNamed::SetName(const char* name)MENU
virtual voidTNamed::SetNameTitle(const char* name, const char* title)
static voidTObject::SetObjectStat(Bool_t stat)
virtual voidTHnBase::SetTitle(const char* title)
virtual voidTObject::SetUniqueID(UInt_t uid)
virtual voidShowMembers(TMemberInspector&)
virtual Int_tTNamed::Sizeof() const
virtual voidStreamer(TBuffer&)
voidStreamerNVirtual(TBuffer& ClassDef_StreamerNVirtual_b)
virtual voidSumw2()
virtual voidTObject::SysError(const char* method, const char* msgfmt) const
Bool_tTObject::TestBit(UInt_t f) const
Int_tTObject::TestBits(UInt_t f) const
virtual voidTObject::UseCurrentStyle()
virtual voidTObject::Warning(const char* method, const char* msgfmt) const
virtual Int_tTObject::Write(const char* name = 0, Int_t option = 0, Int_t bufsize = 0)
virtual Int_tTObject::Write(const char* name = 0, Int_t option = 0, Int_t bufsize = 0) const
protected:
THnSparseArrayChunk*AddChunk()
voidTHnBase::AddInternal(const THnBase* h, Double_t c, Bool_t rebinned)
Bool_tTHnBase::CheckConsistency(const THnBase* h, const char* tag) const
THnBase*THnBase::CloneEmpty(const char* name, const char* title, const TObjArray* axes, Bool_t keepTargetAxis) const
TH1*THnBase::CreateHist(const char* name, const char* title, const TObjArray* axes, Bool_t keepTargetAxis) const
static THnBase*THnBase::CreateHnAny(const char* name, const char* title, const TH1* h1, Bool_t sparse, Int_t chunkSize = 1024*16)
static THnBase*THnBase::CreateHnAny(const char* name, const char* title, const THnBase* hn, Bool_t sparse, Int_t chunkSize = 1024*16)
virtual voidTObject::DoError(int level, const char* location, const char* fmt, va_list va) const
virtual voidFillBin(Long64_t bin, Double_t w)
voidTHnBase::FillBinBase(Double_t w)
voidFillExMap()
virtual TArray*GenerateArray() const
Long64_tGetBinIndexForCurrentBin(Bool_t allocate)
THnSparseArrayChunk*GetChunk(Int_t idx) const
THnSparseCompactBinCoord*GetCompactCoord() const
voidTHnBase::Init(const char* name, const char* title, const TObjArray* axes, Bool_t keepTargetAxis, Int_t chunkSize = 1024*16)
virtual voidInitStorage(Int_t* nbins, Int_t chunkSize)
voidTObject::MakeZombie()
Bool_tTHnBase::PrintBin(Long64_t idx, Int_t* coord, Option_t* options) const
TObject*THnBase::ProjectionAny(Int_t ndim, const Int_t* dim, Bool_t wantNDim, Option_t* option = "") const
THnBase*THnBase::RebinBase(Int_t group) const
THnBase*THnBase::RebinBase(const Int_t* group) const
virtual voidReserve(Long64_t nbins)
voidTHnBase::ResetBase(Option_t* option = "")
voidTHnBase::UpdateXStat(const Double_t* x, Double_t w = 1.)
private:
THnSparse&operator=(const THnSparse&)

Data Members

protected:
TObjArrayTHnBase::fAxesaxes of the histogram
TObjArrayTHnBase::fBrowsables! browser-helpers for each axis
Double_tTHnBase::fEntriesnumber of entries, spread over chunks
Double_t*THnBase::fIntegral! array with bin weight sums
enum THnBase::THnBase::fIntegralStatus! status of integral
TStringTNamed::fNameobject identifier
Int_tTHnBase::fNdimensionsnumber of dimensions
TStringTNamed::fTitleobject title
Double_tTHnBase::fTsumwtotal sum of weights
Double_tTHnBase::fTsumw2total sum of weights squared; -1 if no errors are calculated
TArrayDTHnBase::fTsumwxtotal sum of weight*X for each dimension
TArrayDTHnBase::fTsumwx2total sum of weight*X*X for each dimension
private:
TObjArrayfBinContentarray of THnSparseArrayChunk
TExMapfBins! filled bins
TExMapfBinsContinued! filled bins for non-unique hashes, containing pairs of (bin index 0, bin index 1)
Int_tfChunkSizenumber of entries for each chunk
THnSparseCompactBinCoord*fCompactCoord! compact coordinate
Long64_tfFilledBinsnumber of filled bins

Class Charts

Inheritance Inherited Members Includes Libraries
Class Charts

Function documentation

~THnSparse()
 Destruct a THnSparse
void AddBinContent(Long64_t bin, Double_t v = 1.)
 Add "v" to the content of bin with index "bin"
THnSparseArrayChunk* AddChunk()
 Create a new chunk of bin content
void InitStorage(Int_t* nbins, Int_t chunkSize)
 Initialize the storage of a histogram created via Init()
void FillExMap()
We have been streamed; set up fBins
void Reserve(Long64_t nbins)
 Initialize storage for nbins
Long64_t GetBin(const Double_t* x, Bool_t allocate = kTRUE)
 Get the bin index for the n dimensional tuple x,
 allocate one if it doesn't exist yet and "allocate" is true.
Long64_t GetBin(const char* name[], Bool_t allocate /* = kTRUE */)
 Get the bin index for the n dimensional tuple addressed by "name",
 allocate one if it doesn't exist yet and "allocate" is true.
Long64_t GetBin(const Int_t* idx, Bool_t allocate = kTRUE)
 Get the bin index for the n dimensional coordinates coord,
 allocate one if it doesn't exist yet and "allocate" is true.
Double_t GetBinContent(Long64_t bin, Int_t* idx = 0) const
 Return the content of the filled bin number "idx".
 If coord is non-null, it will contain the bin's coordinates for each axis
 that correspond to the bin.
Double_t GetBinError2(Long64_t linidx) const
 Get square of the error of bin addressed by linidx as

#sum weight^{2}
 If errors are not enabled (via Sumw2() or CalculateErrors())
 return contents.
Long64_t GetBinIndexForCurrentBin(Bool_t allocate)
 Return the index for fCurrentBinIndex.
 If it doesn't exist then return -1, or allocate a new bin if allocate is set
THnSparseCompactBinCoord* GetCompactCoord() const
 Return THnSparseCompactBinCoord object.
Double_t GetSparseFractionBins() const
 Return the amount of filled bins over all bins
Double_t GetSparseFractionMem() const
 Return the amount of used memory over memory that would be used by a
 non-sparse n-dimensional histogram. The value is approximate.
ROOT::THnBaseBinIter* CreateIter(Bool_t respectAxisRange) const
 Create an iterator over all filled bins of a THnSparse.
 Use THnIter instead.
void SetBinContent(Long64_t bin, Double_t v)
 Set content of bin with index "bin" to "v"
void SetBinError2(Long64_t bin, Double_t e2)
 Set error of bin with index "bin" to "e", enable errors if needed
void AddBinError2(Long64_t bin, Double_t e2)
 Add "e" to error of bin with index "bin", enable errors if needed
void Sumw2()
 Enable calculation of errors
void Reset(Option_t* option = "")
 Clear the histogram
THnSparse& operator=(const THnSparse& )
THnSparseArrayChunk* GetChunk(Int_t idx) const
TArray* GenerateArray() const
void FillBin(Long64_t bin, Double_t w)
 Increment the bin content of "bin" by "w",
 return the bin index.
chunk-> AddBinContent(const Int_t* idx, Double_t v = 1.)
THnSparse* CreateSparse(const char* name, const char* title, const TH1* h1, Int_t chunkSize = 1024*16)
THnSparse* CreateSparse(const char* name, const char* title, const THnBase* hn, Int_t chunkSize = 1024*16)
Int_t GetChunkSize() const
{ return fChunkSize; }
Int_t GetNChunks() const
Long64_t GetNbins() const
{ return fFilledBins; }
void SetFilledBins(Long64_t nbins)
{ fFilledBins = nbins; }
Long64_t GetBin(const Int_t* idx) const
{ return const_cast<THnSparse*>(this)->GetBin(idx, kFALSE); }
Long64_t GetBin(const Double_t* x) const
{ return const_cast<THnSparse*>(this)->GetBin(x, kFALSE); }
Long64_t GetBin(const char** name) const
{ return const_cast<THnSparse*>(this)->GetBin(name, kFALSE); }
void SetBinContent(const Int_t* idx, Double_t v)
 Forwards to THnBase::SetBinContent().
 Non-virtual, CINT-compatible replacement of a using declaration.
Double_t GetBinContent(const Int_t* idx) const
 Forwards to THnBase::GetBinContent() overload.
 Non-virtual, CINT-compatible replacement of a using declaration.
TH1D* Projection(Int_t xDim, Option_t* option = "") const
 Forwards to THnBase::Projection().
 Non-virtual, as a CINT-compatible replacement of a using
 declaration.
return Projection(xDim, option)
TH2D* Projection(Int_t yDim, Int_t xDim, Option_t* option = "") const
 Forwards to THnBase::Projection().
 Non-virtual, as a CINT-compatible replacement of a using
 declaration.
TH3D* Projection(Int_t xDim, Int_t yDim, Int_t zDim, Option_t* option = "") const
 Forwards to THnBase::Projection().
 Non-virtual, as a CINT-compatible replacement of a using
 declaration.
THnSparse* Rebin(Int_t group) const
THnSparse* Rebin(const Int_t* group) const