MCMCInterval is a concrete implementation of the RooStats::ConfInterval interface.

It takes as input Markov Chain of data points in the parameter space generated by Monte Carlo using the Metropolis algorithm. From the Markov Chain, the confidence interval can be determined in two ways:

Using a Kernel-Estimated PDF: (not the default method)

A RooNDKeysPdf is constructed from the data set using adaptive kernel width. With this RooNDKeysPdf F, we then integrate over the most likely domain in the parameter space (tallest points in the posterior RooNDKeysPdf) until the target confidence level is reached within an acceptable neighborhood as defined by SetEpsilon(). More specifically: we calculate the following for different cutoff values C until we reach the target confidence level: \(\int_{ F >= C } F d{normset} \). Important note: this is not the default method because of a bug in constructing the RooNDKeysPdf from a weighted data set. Configure to use this method by calling SetUseKeys(true), and the data set will be interpreted without weights.

Using a binned data set: (the default method)

This is the binned analog of the continuous integrative method that uses the kernel-estimated PDF. The points in the Markov Chain are put into a binned data set and the interval is then calculated by adding the heights of the bins in decreasing order until the desired level of confidence has been reached. Note that this means the actual confidence level is >= the confidence level prescribed by the client (unless the user calls SetHistStrict(false)). This method is the default but may not remain as such in future releases, so you may wish to explicitly configure to use this method by calling SetUseKeys(false)

These are not the only ways for the confidence interval to be determined, and other possibilities are being considered being added, especially for the 1-dimensional case.

One can ask an MCMCInterval for the lower and upper limits on a specific parameter of interest in the interval. Note that this works better for some distributions (ones with exactly one local maximum) than others, and sometimes has little value.

Definition at line 33 of file MCMCInterval.h.

Public Types
enum	{ DEFAULT_NUM_BINS = 50 }

enum	IntervalType { kShortest , kTailFraction }

Public Types inherited from TObject
enum	{ kIsOnHeap = 0x01000000 , kNotDeleted = 0x02000000 , kZombie = 0x04000000 , kInconsistent = 0x08000000 , kBitMask = 0x00ffffff }

enum	{ kSingleKey = (1ULL << ( 0 )) , kOverwrite = (1ULL << ( 1 )) , kWriteDelete = (1ULL << ( 2 )) }

enum	EDeprecatedStatusBits { kObjInCanvas = (1ULL << ( 3 )) }

enum	EStatusBits { kCanDelete = (1ULL << ( 0 )) , kMustCleanup = (1ULL << ( 3 )) , kIsReferenced = (1ULL << ( 4 )) , kHasUUID = (1ULL << ( 5 )) , kCannotPick = (1ULL << ( 6 )) , kNoContextMenu = (1ULL << ( 8 )) , kInvalidObject = (1ULL << ( 13 )) }

Public Member Functions
	MCMCInterval (const char *name, const RooArgSet &parameters, MarkovChain &chain)
	constructor from parameter of interest and Markov chain object

	MCMCInterval (const char *name=nullptr)
	default constructor

	~MCMCInterval () override

bool	CheckParameters (const RooArgSet &point) const override
	check if parameters are correct. (dummy implementation to start)

double	ConfidenceLevel () const override
	get the desired confidence level (see GetActualConfidenceLevel())

virtual double	GetActualConfidenceLevel ()
	virtual double GetKeysPdfCutoff() { return fKeysCutoff; }

virtual RooArgList *	GetAxes ()
	return a list of RooRealVars representing the axes you own the returned RooArgList

virtual const MarkovChain *	GetChain ()
	Get the markov chain on which this interval is based You do not own the returned MarkovChain*.

virtual const RooDataSet *	GetChainAsConstDataSet ()
	Get the markov chain on which this interval is based as a RooDataSet.

virtual RooFit::OwningPtr< RooDataHist >	GetChainAsDataHist (RooArgSet *whichVars=nullptr)
	Get a clone of the markov chain on which this interval is based as a RooDataHist.

virtual RooFit::OwningPtr< RooDataSet >	GetChainAsDataSet (RooArgSet *whichVars=nullptr)
	Get a clone of the markov chain on which this interval is based as a RooDataSet.

virtual THnSparse *	GetChainAsSparseHist (RooArgSet *whichVars=nullptr)
	Get a clone of the markov chain on which this interval is based as a THnSparse.

virtual Int_t	GetDimension () const
	Get the number of parameters of interest in this interval.

virtual double	GetHistCutoff ()
	get the cutoff bin height for being considered in the confidence interval

virtual enum IntervalType	GetIntervalType ()
	Return the type of this interval.

double	GetKeysMax ()
	Determine the approximate maximum value of the Keys PDF.

virtual double	GetKeysPdfCutoff ()
	get the cutoff RooNDKeysPdf value for being considered in the confidence interval

virtual RooRealVar *	GetNLLVar () const
	Get a clone of the NLL variable from the markov chain.

virtual Int_t	GetNumBurnInSteps ()
	get the number of steps in the chain to discard as burn-in,

RooArgSet *	GetParameters () const override
	return a set containing the parameters of this interval the caller owns the returned RooArgSet*

virtual TH1 *	GetPosteriorHist ()
	set the number of bins to use (same for all axes, for now) virtual void SetNumBins(Int_t numBins);

virtual RooNDKeysPdf *	GetPosteriorKeysPdf ()
	Get a clone of the keys pdf of the posterior.

virtual RooProduct *	GetPosteriorKeysProduct ()
	Get a clone of the (keyspdf * heaviside) product of the posterior.

virtual bool	GetUseKeys ()
	get whether we used kernel estimation to determine the interval

virtual RooRealVar *	GetWeightVar () const
	Get a clone of the weight variable from the markov chain.

TClass *	IsA () const override

bool	IsInInterval (const RooArgSet &point) const override
	determine whether this point is in the confidence interval

virtual double	LowerLimit (RooRealVar &param)
	get the lowest value of param that is within the confidence interval

virtual double	LowerLimitByDataHist (RooRealVar &param)
	determine lower limit using histogram

virtual double	LowerLimitByHist (RooRealVar &param)
	determine lower limit using histogram

virtual double	LowerLimitByKeys (RooRealVar &param)
	determine lower limit in the shortest interval by using keys pdf

virtual double	LowerLimitBySparseHist (RooRealVar &param)
	determine lower limit using histogram

virtual double	LowerLimitShortest (RooRealVar &param)
	get the lower limit of param in the shortest confidence interval Note that this works better for some distributions (ones with exactly one maximum) than others, and sometimes has little value.

virtual double	LowerLimitTailFraction (RooRealVar &param)
	determine lower limit of the lower confidence interval

virtual void	SetAxes (RooArgList &axes)
	Set which parameters go on which axis.

virtual void	SetChain (MarkovChain &chain)
	Set the MarkovChain that this interval is based on.

void	SetConfidenceLevel (double cl) override
	set the desired confidence level (see GetActualConfidenceLevel()) Note: calling this function triggers the algorithm that determines the interval, so call this after initializing all other aspects of this IntervalCalculator Also, calling this function again with a different confidence level re-triggers the calculation of the interval

virtual void	SetDelta (double delta)
	kbelasco: The inner-workings of the class really should not be exposed like this in a comment, but it seems to be the only way to give the user any control over this process, if they desire it

virtual void	SetEpsilon (double epsilon)
	set the acceptable level or error for Keys interval determination

virtual void	SetHistStrict (bool isHistStrict)
	whether the specified confidence level is a floor for the actual confidence level (strict), or a ceiling (not strict)

virtual void	SetIntervalType (enum IntervalType intervalType)
	Set the type of interval to find.

virtual void	SetLeftSideTailFraction (double a)
	set the left-side tail fraction for a tail-fraction interval

virtual void	SetNumBurnInSteps (Int_t numBurnInSteps)
	set the number of steps in the chain to discard as burn-in, starting from the first

virtual void	SetParameters (const RooArgSet &parameters)
	Set the parameters of interest for this interval and change other internal data members accordingly.

virtual void	SetShortestInterval ()

virtual void	SetUseKeys (bool useKeys)
	set whether to use kernel estimation to determine the interval

virtual void	SetUseSparseHist (bool useSparseHist)
	set whether to use a sparse histogram.

void	Streamer (TBuffer &) override
	Stream an object of class TObject.

void	StreamerNVirtual (TBuffer &ClassDef_StreamerNVirtual_b)

virtual double	UpperLimit (RooRealVar &param)
	get the highest value of param that is within the confidence interval

virtual double	UpperLimitByDataHist (RooRealVar &param)
	determine upper limit using histogram

virtual double	UpperLimitByHist (RooRealVar &param)
	determine upper limit using histogram

virtual double	UpperLimitByKeys (RooRealVar &param)
	determine upper limit in the shortest interval by using keys pdf

virtual double	UpperLimitBySparseHist (RooRealVar &param)
	determine upper limit using histogram

virtual double	UpperLimitShortest (RooRealVar &param)
	get the upper limit of param in the confidence interval Note that this works better for some distributions (ones with exactly one maximum) than others, and sometimes has little value.

virtual double	UpperLimitTailFraction (RooRealVar &param)
	determine upper limit of the lower confidence interval

Public Member Functions inherited from RooStats::ConfInterval
	ConfInterval (const char *name=nullptr)
	constructor given name and title

ConfInterval &	operator= (const ConfInterval &other)
	operator=

void	StreamerNVirtual (TBuffer &ClassDef_StreamerNVirtual_b)

Public Member Functions inherited from TNamed
	TNamed ()

	TNamed (const char name, const char title)

	TNamed (const TNamed &named)
	TNamed copy ctor.

	TNamed (const TString &name, const TString &title)

virtual	~TNamed ()
	TNamed destructor.

void	Clear (Option_t *option="") override
	Set name and title to empty strings ("").

TObject *	Clone (const char *newname="") const override
	Make a clone of an object using the Streamer facility.

Int_t	Compare (const TObject *obj) const override
	Compare two TNamed objects.

void	Copy (TObject &named) const override
	Copy this to obj.

virtual void	FillBuffer (char *&buffer)
	Encode TNamed into output buffer.

const char *	GetName () const override
	Returns name of object.

const char *	GetTitle () const override
	Returns title of object.

ULong_t	Hash () const override
	Return hash value for this object.

TClass *	IsA () const override

Bool_t	IsSortable () const override

void	ls (Option_t *option="") const override
	List TNamed name and title.

TNamed &	operator= (const TNamed &rhs)
	TNamed assignment operator.

void	Print (Option_t *option="") const override
	Print TNamed name and title.

virtual void	SetName (const char *name)
	Set the name of the TNamed.

virtual void	SetNameTitle (const char name, const char title)
	Set all the TNamed parameters (name and title).

virtual void	SetTitle (const char *title="")
	Set the title of the TNamed.

virtual Int_t	Sizeof () const
	Return size of the TNamed part of the TObject.

void	Streamer (TBuffer &) override
	Stream an object of class TObject.

void	StreamerNVirtual (TBuffer &ClassDef_StreamerNVirtual_b)

Public Member Functions inherited from TObject
	TObject ()
	TObject constructor.

	TObject (const TObject &object)
	TObject copy ctor.

virtual	~TObject ()
	TObject destructor.

void	AbstractMethod (const char *method) const
	Use this method to implement an "abstract" method that you don't want to leave purely abstract.

virtual void	AppendPad (Option_t *option="")
	Append graphics object to current pad.

virtual void	Browse (TBrowser *b)
	Browse object. May be overridden for another default action.

ULong_t	CheckedHash ()
	Check and record whether this class has a consistent Hash/RecursiveRemove setup (*) and then return the regular Hash value for this object.

virtual const char *	ClassName () const
	Returns name of class to which the object belongs.

virtual void	Delete (Option_t *option="")
	Delete this object.

virtual Int_t	DistancetoPrimitive (Int_t px, Int_t py)
	Computes distance from point (px,py) to the object.

virtual void	Draw (Option_t *option="")
	Default Draw method for all objects.

virtual void	DrawClass () const
	Draw class inheritance tree of the class to which this object belongs.

virtual TObject *	DrawClone (Option_t *option="") const
	Draw a clone of this object in the current selected pad with: `gROOT->SetSelectedPad(c1)`.

virtual void	Dump () const
	Dump contents of object on stdout.

virtual void	Error (const char method, const char msgfmt,...) const
	Issue error message.

virtual void	Execute (const char method, const char params, Int_t *error=nullptr)
	Execute method on this object with the given parameter string, e.g.

virtual void	Execute (TMethod method, TObjArray params, Int_t *error=nullptr)
	Execute method on this object with parameters stored in the TObjArray.

virtual void	ExecuteEvent (Int_t event, Int_t px, Int_t py)
	Execute action corresponding to an event at (px,py).

virtual void	Fatal (const char method, const char msgfmt,...) const
	Issue fatal error message.

virtual TObject *	FindObject (const char *name) const
	Must be redefined in derived classes.

virtual TObject *	FindObject (const TObject *obj) const
	Must be redefined in derived classes.

virtual Option_t *	GetDrawOption () const
	Get option used by the graphics system to draw this object.

virtual const char *	GetIconName () const
	Returns mime type name of object.

virtual char *	GetObjectInfo (Int_t px, Int_t py) const
	Returns string containing info about the object at position (px,py).

virtual Option_t *	GetOption () const

virtual UInt_t	GetUniqueID () const
	Return the unique object id.

virtual Bool_t	HandleTimer (TTimer *timer)
	Execute action in response of a timer timing out.

Bool_t	HasInconsistentHash () const
	Return true is the type of this object is known to have an inconsistent setup for Hash and RecursiveRemove (i.e.

virtual void	Info (const char method, const char msgfmt,...) const
	Issue info message.

virtual Bool_t	InheritsFrom (const char *classname) const
	Returns kTRUE if object inherits from class "classname".

virtual Bool_t	InheritsFrom (const TClass *cl) const
	Returns kTRUE if object inherits from TClass cl.

virtual void	Inspect () const
	Dump contents of this object in a graphics canvas.

void	InvertBit (UInt_t f)

Bool_t	IsDestructed () const
	IsDestructed.

virtual Bool_t	IsEqual (const TObject *obj) const
	Default equal comparison (objects are equal if they have the same address in memory).

virtual Bool_t	IsFolder () const
	Returns kTRUE in case object contains browsable objects (like containers or lists of other objects).

R__ALWAYS_INLINE Bool_t	IsOnHeap () const

R__ALWAYS_INLINE Bool_t	IsZombie () const

void	MayNotUse (const char *method) const
	Use this method to signal that a method (defined in a base class) may not be called in a derived class (in principle against good design since a child class should not provide less functionality than its parent, however, sometimes it is necessary).

virtual Bool_t	Notify ()
	This method must be overridden to handle object notification (the base implementation is no-op).

void	Obsolete (const char method, const char asOfVers, const char *removedFromVers) const
	Use this method to declare a method obsolete.

void	operator delete (void *ptr)
	Operator delete.

void	operator delete (void ptr, void vp)
	Only called by placement new when throwing an exception.

void	operator delete[] (void *ptr)
	Operator delete [].

void	operator delete[] (void ptr, void vp)
	Only called by placement new[] when throwing an exception.

void *	operator new (size_t sz)

void *	operator new (size_t sz, void *vp)

void *	operator new[] (size_t sz)

void *	operator new[] (size_t sz, void *vp)

TObject &	operator= (const TObject &rhs)
	TObject assignment operator.

virtual void	Paint (Option_t *option="")
	This method must be overridden if a class wants to paint itself.

virtual void	Pop ()
	Pop on object drawn in a pad to the top of the display list.

virtual Int_t	Read (const char *name)
	Read contents of object with specified name from the current directory.

virtual void	RecursiveRemove (TObject *obj)
	Recursively remove this object from a list.

void	ResetBit (UInt_t f)

virtual void	SaveAs (const char filename="", Option_t option="") const
	Save this object in the file specified by filename.

virtual void	SavePrimitive (std::ostream &out, Option_t *option="")
	Save a primitive as a C++ statement(s) on output stream "out".

void	SetBit (UInt_t f)

void	SetBit (UInt_t f, Bool_t set)
	Set or unset the user status bits as specified in f.

virtual void	SetDrawOption (Option_t *option="")
	Set drawing option for object.

virtual void	SetUniqueID (UInt_t uid)
	Set the unique object id.

void	StreamerNVirtual (TBuffer &ClassDef_StreamerNVirtual_b)

virtual void	SysError (const char method, const char msgfmt,...) const
	Issue system error message.

R__ALWAYS_INLINE Bool_t	TestBit (UInt_t f) const

Int_t	TestBits (UInt_t f) const

virtual void	UseCurrentStyle ()
	Set current style settings in this object This function is called when either TCanvas::UseCurrentStyle or TROOT::ForceStyle have been invoked.

virtual void	Warning (const char method, const char msgfmt,...) const
	Issue warning message.

virtual Int_t	Write (const char *name=nullptr, Int_t option=0, Int_t bufsize=0)
	Write this object to the current directory.

virtual Int_t	Write (const char *name=nullptr, Int_t option=0, Int_t bufsize=0) const
	Write this object to the current directory.

Static Public Member Functions
static TClass *	Class ()

static const char *	Class_Name ()

static constexpr Version_t	Class_Version ()

static const char *	DeclFileName ()

Static Public Member Functions inherited from RooStats::ConfInterval
static TClass *	Class ()

static const char *	Class_Name ()

static constexpr Version_t	Class_Version ()

static const char *	DeclFileName ()

Static Public Member Functions inherited from TNamed
static TClass *	Class ()

static const char *	Class_Name ()

static constexpr Version_t	Class_Version ()

static const char *	DeclFileName ()

Static Public Member Functions inherited from TObject
static TClass *	Class ()

static const char *	Class_Name ()

static constexpr Version_t	Class_Version ()

static const char *	DeclFileName ()

static Longptr_t	GetDtorOnly ()
	Return destructor only flag.

static Bool_t	GetObjectStat ()
	Get status of object stat flag.

static void	SetDtorOnly (void *obj)
	Set destructor only flag.

static void	SetObjectStat (Bool_t stat)
	Turn on/off tracking of objects in the TObjectTable.

Protected Member Functions
virtual double	CalcConfLevel (double cutoff, double full)

virtual void	CreateDataHist ()

virtual void	CreateHist ()

virtual void	CreateKeysDataHist ()

virtual void	CreateKeysPdf ()

virtual void	CreateSparseHist ()

virtual void	CreateVector (RooRealVar *param)

virtual void	DetermineByDataHist ()

virtual void	DetermineByHist ()

virtual void	DetermineByKeys ()

virtual void	DetermineBySparseHist ()

virtual void	DetermineInterval ()

virtual void	DetermineShortestInterval ()

virtual void	DetermineTailFractionInterval ()

Protected Member Functions inherited from TObject
virtual void	DoError (int level, const char location, const char fmt, va_list va) const
	Interface to ErrorHandler (protected).

void	MakeZombie ()

Protected Attributes
RooRealVar **	fAxes = nullptr
	array of pointers to RooRealVars representing the axes of the histogram fAxes[0] represents x-axis, [1] y, [2] z, etc

MarkovChain *	fChain = nullptr
	the markov chain

double	fConfidenceLevel = 0.0
	Requested confidence level (eg. 0.95 for 95% CL)

RooRealVar *	fCutoffVar = nullptr
	cutoff variable to use for integrating keys pdf

RooDataHist *	fDataHist = nullptr
	the binned Markov Chain data

double	fDelta = DEFAULT_DELTA
	topCutoff (a) considered == bottomCutoff (b) iff (std::abs(a - b) < std::abs(fDelta * (a + b)/2)); Theoretically, the Abs is not needed here, but floating-point arithmetic does not always work perfectly, and the Abs doesn't hurt

Int_t	fDimension = 1
	number of variables

double	fEpsilon = DEFAULT_EPSILON
	acceptable error for Keys interval determination

double	fFull = 0.0
	Value of intergral of fProduct.

Heaviside *	fHeaviside = nullptr
	the Heaviside function

TH1 *	fHist = nullptr
	the binned Markov Chain data

double	fHistConfLevel = 0.0
	the actual conf level determined by hist

double	fHistCutoff = -1
	cutoff bin size to be in interval

enum IntervalType	fIntervalType = kShortest

bool	fIsHistStrict = true
	whether the specified confidence level is a floor for the actual confidence level (strict), or a ceiling (not strict) for determination by histogram

double	fKeysConfLevel = 0.0
	the actual conf level determined by keys

double	fKeysCutoff = -1
	cutoff keys pdf value to be in interval

RooDataHist *	fKeysDataHist = nullptr
	data hist representing product

RooNDKeysPdf *	fKeysPdf = nullptr
	the kernel estimation pdf

double	fLeftSideTF = -1
	left side tail-fraction for interval

Int_t	fNumBurnInSteps = 0
	number of steps to discard as burn in, starting from the first

RooArgSet	fParameters
	parameters of interest for this interval

RooProduct *	fProduct = nullptr
	the (keysPdf * heaviside) product

THnSparse *	fSparseHist = nullptr
	the binned Markov Chain data

double	fTFConfLevel = 0.0
	the actual conf level of tail-fraction interval

double	fTFLower
	lower limit of the tail-fraction interval

double	fTFUpper
	upper limit of the tail-fraction interval

bool	fUseKeys = false
	whether to use kernel estimation

bool	fUseSparseHist = false
	whether to use sparse hist (vs. RooDataHist)

std::vector< Int_t >	fVector
	vector containing the Markov chain data

double	fVecWeight = 0
	sum of weights of all entries in fVector

Protected Attributes inherited from TNamed
TString	fName

TString	fTitle

Private Member Functions
bool	AcceptableConfLevel (double confLevel)

bool	WithinDeltaFraction (double a, double b)

Static Private Attributes
static constexpr const double	DEFAULT_DELTA = 10e-6

static constexpr const double	DEFAULT_EPSILON = 0.01

Additional Inherited Members
Protected Types inherited from TObject
enum	{ kOnlyPrepStep = (1ULL << ( 3 )) }

#include <RooStats/MCMCInterval.h>

Inheritance diagram for RooStats::MCMCInterval:

[legend]

Member Enumeration Documentation

◆ anonymous enum

anonymous enum

Enumerator
DEFAULT_NUM_BINS

Definition at line 45 of file MCMCInterval.h.

◆ IntervalType

enum RooStats::MCMCInterval::IntervalType

Enumerator
kShortest
kTailFraction

Definition at line 46 of file MCMCInterval.h.

Constructor & Destructor Documentation

◆ MCMCInterval() [1/2]

MCMCInterval::MCMCInterval ( const char * name = nullptr )

explicit

default constructor

Definition at line 93 of file MCMCInterval.cxx.

◆ MCMCInterval() [2/2]

MCMCInterval::MCMCInterval	(	const char *	name,
		const RooArgSet &	parameters,
		MarkovChain &	chain
	)

constructor from parameter of interest and Markov chain object

Definition at line 101 of file MCMCInterval.cxx.

◆ ~MCMCInterval()

MCMCInterval::~MCMCInterval ( )

override

Definition at line 110 of file MCMCInterval.cxx.

Member Function Documentation

◆ AcceptableConfLevel()

bool MCMCInterval::AcceptableConfLevel ( double confLevel )

inlineprivate

Definition at line 1407 of file MCMCInterval.cxx.

◆ CalcConfLevel()

double MCMCInterval::CalcConfLevel	(	double	cutoff,
		double	full
	)

inlineprotectedvirtual

Definition at line 1329 of file MCMCInterval.cxx.

◆ CheckParameters()

bool MCMCInterval::CheckParameters ( const RooArgSet & point ) const

overridevirtual

check if parameters are correct. (dummy implementation to start)

Implements RooStats::ConfInterval.

Definition at line 1491 of file MCMCInterval.cxx.

◆ Class()

static TClass * RooStats::MCMCInterval::Class ( )

static

Returns: TClass describing this class

◆ Class_Name()

static const char * RooStats::MCMCInterval::Class_Name ( )

static

Returns: Name of this class

◆ Class_Version()

static constexpr Version_t RooStats::MCMCInterval::Class_Version ( )

inlinestaticconstexpr

Returns: Version of this class

Definition at line 347 of file MCMCInterval.h.

◆ ConfidenceLevel()

double RooStats::MCMCInterval::ConfidenceLevel ( ) const

inlineoverridevirtual

get the desired confidence level (see GetActualConfidenceLevel())

Implements RooStats::ConfInterval.

Definition at line 62 of file MCMCInterval.h.

◆ CreateDataHist()

void MCMCInterval::CreateDataHist ( )

protectedvirtual

Definition at line 434 of file MCMCInterval.cxx.

◆ CreateHist()

void MCMCInterval::CreateHist ( )

protectedvirtual

Definition at line 314 of file MCMCInterval.cxx.

◆ CreateKeysDataHist()

void MCMCInterval::CreateKeysDataHist ( )

protectedvirtual

Definition at line 1421 of file MCMCInterval.cxx.

◆ CreateKeysPdf()

void MCMCInterval::CreateKeysPdf ( )

protectedvirtual

Definition at line 272 of file MCMCInterval.cxx.

◆ CreateSparseHist()

void MCMCInterval::CreateSparseHist ( )

protectedvirtual

Definition at line 385 of file MCMCInterval.cxx.

◆ CreateVector()

void MCMCInterval::CreateVector ( RooRealVar * param )

protectedvirtual

Definition at line 458 of file MCMCInterval.cxx.

◆ DeclFileName()

static const char * RooStats::MCMCInterval::DeclFileName ( )

inlinestatic

Returns: Name of the file containing the class declaration

Definition at line 347 of file MCMCInterval.h.

◆ DetermineByDataHist()

void MCMCInterval::DetermineByDataHist ( )

protectedvirtual

Definition at line 845 of file MCMCInterval.cxx.

◆ DetermineByHist()

void MCMCInterval::DetermineByHist ( )

protectedvirtual

Definition at line 761 of file MCMCInterval.cxx.

◆ DetermineByKeys()

void MCMCInterval::DetermineByKeys ( )

protectedvirtual

Definition at line 648 of file MCMCInterval.cxx.

◆ DetermineBySparseHist()

void MCMCInterval::DetermineBySparseHist ( )

protectedvirtual

Definition at line 772 of file MCMCInterval.cxx.

◆ DetermineInterval()

void MCMCInterval::DetermineInterval ( )

protectedvirtual

Definition at line 517 of file MCMCInterval.cxx.

◆ DetermineShortestInterval()

void MCMCInterval::DetermineShortestInterval ( )

protectedvirtual

Definition at line 535 of file MCMCInterval.cxx.

◆ DetermineTailFractionInterval()

void MCMCInterval::DetermineTailFractionInterval ( )

protectedvirtual

Definition at line 546 of file MCMCInterval.cxx.

◆ GetActualConfidenceLevel()

double MCMCInterval::GetActualConfidenceLevel ( )

virtual

virtual double GetKeysPdfCutoff() { return fKeysCutoff; }

get the actual value of the confidence level for this interval.

Definition at line 919 of file MCMCInterval.cxx.

◆ GetAxes()

virtual RooArgList * RooStats::MCMCInterval::GetAxes ( )

inlinevirtual

return a list of RooRealVars representing the axes you own the returned RooArgList

Definition at line 102 of file MCMCInterval.h.

◆ GetChain()

virtual const MarkovChain * RooStats::MCMCInterval::GetChain ( )

inlinevirtual

Get the markov chain on which this interval is based You do not own the returned MarkovChain*.

Definition at line 198 of file MCMCInterval.h.

◆ GetChainAsConstDataSet()

virtual const RooDataSet * RooStats::MCMCInterval::GetChainAsConstDataSet ( )

inlinevirtual

Get the markov chain on which this interval is based as a RooDataSet.

You do not own the returned RooDataSet*

Definition at line 207 of file MCMCInterval.h.

◆ GetChainAsDataHist()

virtual RooFit::OwningPtr< RooDataHist > RooStats::MCMCInterval::GetChainAsDataHist ( RooArgSet * whichVars = nullptr )

inlinevirtual

Get a clone of the markov chain on which this interval is based as a RooDataHist.

You own the returned RooDataHist*

Definition at line 212 of file MCMCInterval.h.

◆ GetChainAsDataSet()

virtual RooFit::OwningPtr< RooDataSet > RooStats::MCMCInterval::GetChainAsDataSet ( RooArgSet * whichVars = nullptr )

inlinevirtual

Get a clone of the markov chain on which this interval is based as a RooDataSet.

You own the returned RooDataSet*

Definition at line 202 of file MCMCInterval.h.

◆ GetChainAsSparseHist()

virtual THnSparse * RooStats::MCMCInterval::GetChainAsSparseHist ( RooArgSet * whichVars = nullptr )

inlinevirtual

Get a clone of the markov chain on which this interval is based as a THnSparse.

You own the returned THnSparse*

Definition at line 217 of file MCMCInterval.h.

◆ GetDimension()

virtual Int_t RooStats::MCMCInterval::GetDimension ( ) const

inlinevirtual

Get the number of parameters of interest in this interval.

Definition at line 194 of file MCMCInterval.h.

◆ GetHistCutoff()

double MCMCInterval::GetHistCutoff ( )

virtual

get the cutoff bin height for being considered in the confidence interval

Definition at line 1305 of file MCMCInterval.cxx.

◆ GetIntervalType()

virtual enum IntervalType RooStats::MCMCInterval::GetIntervalType ( )

inlinevirtual

Return the type of this interval.

Definition at line 248 of file MCMCInterval.h.

◆ GetKeysMax()

double MCMCInterval::GetKeysMax ( )

Determine the approximate maximum value of the Keys PDF.

Definition at line 1273 of file MCMCInterval.cxx.

◆ GetKeysPdfCutoff()

double MCMCInterval::GetKeysPdfCutoff ( )

virtual

get the cutoff RooNDKeysPdf value for being considered in the confidence interval

Definition at line 1315 of file MCMCInterval.cxx.

◆ GetNLLVar()

virtual RooRealVar * RooStats::MCMCInterval::GetNLLVar ( ) const

inlinevirtual

Get a clone of the NLL variable from the markov chain.

Definition at line 221 of file MCMCInterval.h.

◆ GetNumBurnInSteps()

virtual Int_t RooStats::MCMCInterval::GetNumBurnInSteps ( )

inlinevirtual

get the number of steps in the chain to discard as burn-in,

get the number of steps in the chain to discard as burn-in, starting from the first

Definition at line 179 of file MCMCInterval.h.

◆ GetParameters()

RooArgSet * MCMCInterval::GetParameters ( ) const

overridevirtual

return a set containing the parameters of this interval the caller owns the returned RooArgSet*

Implements RooStats::ConfInterval.

Definition at line 1399 of file MCMCInterval.cxx.

◆ GetPosteriorHist()

TH1 * MCMCInterval::GetPosteriorHist ( )

virtual

set the number of bins to use (same for all axes, for now) virtual void SetNumBins(Int_t numBins);

Get a clone of the histogram of the posterior

Definition at line 1340 of file MCMCInterval.cxx.

◆ GetPosteriorKeysPdf()

RooNDKeysPdf * MCMCInterval::GetPosteriorKeysPdf ( )

virtual

Get a clone of the keys pdf of the posterior.

Definition at line 1359 of file MCMCInterval.cxx.

◆ GetPosteriorKeysProduct()

RooProduct * MCMCInterval::GetPosteriorKeysProduct ( )

virtual

Get a clone of the (keyspdf * heaviside) product of the posterior.

Definition at line 1378 of file MCMCInterval.cxx.

◆ GetUseKeys()

virtual bool RooStats::MCMCInterval::GetUseKeys ( )

inlinevirtual

get whether we used kernel estimation to determine the interval

Definition at line 173 of file MCMCInterval.h.

◆ GetWeightVar()

virtual RooRealVar * RooStats::MCMCInterval::GetWeightVar ( ) const

inlinevirtual

Get a clone of the weight variable from the markov chain.

Definition at line 225 of file MCMCInterval.h.

◆ IsA()

TClass * RooStats::MCMCInterval::IsA ( ) const

inlineoverridevirtual

Returns: TClass describing current object

Reimplemented from RooStats::ConfInterval.

Definition at line 347 of file MCMCInterval.h.

◆ IsInInterval()

bool MCMCInterval::IsInInterval ( const RooArgSet & point ) const

overridevirtual

determine whether this point is in the confidence interval

kbelasco: for this method, consider running DetermineInterval() if fKeysPdf==nullptr, fSparseHist==nullptr, fDataHist==nullptr, or fVector.empty() rather than just returning false.

Though this should not be an issue because nobody should be able to get an MCMCInterval that has their interval or posterior representation nullptr/empty since they should only get this through the MCMCCalculator

Implements RooStats::ConfInterval.

Definition at line 168 of file MCMCInterval.cxx.

◆ LowerLimit()

double MCMCInterval::LowerLimit ( RooRealVar & param )

virtual

get the lowest value of param that is within the confidence interval

Definition at line 938 of file MCMCInterval.cxx.

◆ LowerLimitByDataHist()

double MCMCInterval::LowerLimitByDataHist ( RooRealVar & param )

virtual

determine lower limit using histogram

Determine the lower limit for param on this interval using the binned data set.

Definition at line 1081 of file MCMCInterval.cxx.

◆ LowerLimitByHist()

double MCMCInterval::LowerLimitByHist ( RooRealVar & param )

virtual

determine lower limit using histogram

Determine the lower limit for param on this interval using the binned data set.

Definition at line 1014 of file MCMCInterval.cxx.

◆ LowerLimitByKeys()

double MCMCInterval::LowerLimitByKeys ( RooRealVar & param )

virtual

determine lower limit in the shortest interval by using keys pdf

Determine the lower limit for param on this interval using the keys pdf.

Definition at line 1194 of file MCMCInterval.cxx.

◆ LowerLimitBySparseHist()

double MCMCInterval::LowerLimitBySparseHist ( RooRealVar & param )

virtual

determine lower limit using histogram

Determine the lower limit for param on this interval using the binned data set.

Definition at line 1040 of file MCMCInterval.cxx.

◆ LowerLimitShortest()

double MCMCInterval::LowerLimitShortest ( RooRealVar & param )

virtual

get the lower limit of param in the shortest confidence interval Note that this works better for some distributions (ones with exactly one maximum) than others, and sometimes has little value.

Definition at line 990 of file MCMCInterval.cxx.

◆ LowerLimitTailFraction()

double MCMCInterval::LowerLimitTailFraction ( RooRealVar & param )

virtual

determine lower limit of the lower confidence interval

Definition at line 970 of file MCMCInterval.cxx.

◆ SetAxes()

void MCMCInterval::SetAxes ( RooArgList & axes )

virtual

Set which parameters go on which axis.

The first list element goes on the x axis, second (if it exists) on y, third (if it exists) on z, etc

Definition at line 256 of file MCMCInterval.cxx.

◆ SetChain()

virtual void RooStats::MCMCInterval::SetChain ( MarkovChain & chain )

inlinevirtual

Set the MarkovChain that this interval is based on.

Definition at line 93 of file MCMCInterval.h.

◆ SetConfidenceLevel()

void MCMCInterval::SetConfidenceLevel ( double cl )

overridevirtual

set the desired confidence level (see GetActualConfidenceLevel()) Note: calling this function triggers the algorithm that determines the interval, so call this after initializing all other aspects of this IntervalCalculator Also, calling this function again with a different confidence level re-triggers the calculation of the interval

Implements RooStats::ConfInterval.

Definition at line 226 of file MCMCInterval.cxx.

◆ SetDelta()

virtual void RooStats::MCMCInterval::SetDelta ( double delta )

inlinevirtual

kbelasco: The inner-workings of the class really should not be exposed like this in a comment, but it seems to be the only way to give the user any control over this process, if they desire it

Set the fraction delta such that topCutoff (a) is considered == bottomCutoff (b) iff (std::abs(a - b) < std::abs(fDelta * (a + b)/2)) when determining the confidence interval by Keys

Definition at line 264 of file MCMCInterval.h.

◆ SetEpsilon()

virtual void RooStats::MCMCInterval::SetEpsilon ( double epsilon )

inlinevirtual

set the acceptable level or error for Keys interval determination

Definition at line 229 of file MCMCInterval.h.

◆ SetHistStrict()

virtual void RooStats::MCMCInterval::SetHistStrict ( bool isHistStrict )

inlinevirtual

whether the specified confidence level is a floor for the actual confidence level (strict), or a ceiling (not strict)

Definition at line 82 of file MCMCInterval.h.

◆ SetIntervalType()

virtual void RooStats::MCMCInterval::SetIntervalType ( enum IntervalType intervalType )

inlinevirtual

Set the type of interval to find.

This will only have an effect for 1-D intervals. If is more than 1 parameter of interest, then a "shortest" interval will always be used, since it generalizes directly to N dimensions

Definition at line 243 of file MCMCInterval.h.

◆ SetLeftSideTailFraction()

virtual void RooStats::MCMCInterval::SetLeftSideTailFraction ( double a )

inlinevirtual

set the left-side tail fraction for a tail-fraction interval

Definition at line 251 of file MCMCInterval.h.

◆ SetNumBurnInSteps()

virtual void RooStats::MCMCInterval::SetNumBurnInSteps ( Int_t numBurnInSteps )

inlinevirtual

set the number of steps in the chain to discard as burn-in, starting from the first

Definition at line 161 of file MCMCInterval.h.

◆ SetParameters()

void MCMCInterval::SetParameters ( const RooArgSet & parameters )

virtual

Set the parameters of interest for this interval and change other internal data members accordingly.

Definition at line 495 of file MCMCInterval.cxx.

◆ SetShortestInterval()

virtual void RooStats::MCMCInterval::SetShortestInterval ( )

inlinevirtual

Definition at line 245 of file MCMCInterval.h.

◆ SetUseKeys()

virtual void RooStats::MCMCInterval::SetUseKeys ( bool useKeys )

inlinevirtual

set whether to use kernel estimation to determine the interval

Definition at line 165 of file MCMCInterval.h.

◆ SetUseSparseHist()

virtual void RooStats::MCMCInterval::SetUseSparseHist ( bool useSparseHist )

inlinevirtual

set whether to use a sparse histogram.

you MUST also call SetUseKeys(false) to use a histogram.

Definition at line 169 of file MCMCInterval.h.

◆ Streamer()

void RooStats::MCMCInterval::Streamer ( TBuffer & R__b )

overridevirtual

Stream an object of class TObject.

Reimplemented from RooStats::ConfInterval.

◆ StreamerNVirtual()

void RooStats::MCMCInterval::StreamerNVirtual ( TBuffer & ClassDef_StreamerNVirtual_b )

inline

Definition at line 347 of file MCMCInterval.h.

◆ UpperLimit()

double MCMCInterval::UpperLimit ( RooRealVar & param )

virtual

get the highest value of param that is within the confidence interval

Definition at line 954 of file MCMCInterval.cxx.

◆ UpperLimitByDataHist()

double MCMCInterval::UpperLimitByDataHist ( RooRealVar & param )

virtual

determine upper limit using histogram

Determine the upper limit for param on this interval using the binned data set.

Definition at line 1158 of file MCMCInterval.cxx.

◆ UpperLimitByHist()

double MCMCInterval::UpperLimitByHist ( RooRealVar & param )

virtual

determine upper limit using histogram

Determine the upper limit for param on this interval using the binned data set.

Definition at line 1027 of file MCMCInterval.cxx.

◆ UpperLimitByKeys()

double MCMCInterval::UpperLimitByKeys ( RooRealVar & param )

virtual

determine upper limit in the shortest interval by using keys pdf

Determine the upper limit for param on this interval using the keys pdf.

Definition at line 1234 of file MCMCInterval.cxx.

◆ UpperLimitBySparseHist()

double MCMCInterval::UpperLimitBySparseHist ( RooRealVar & param )

virtual

determine upper limit using histogram

Determine the upper limit for param on this interval using the binned data set.

Definition at line 1117 of file MCMCInterval.cxx.

◆ UpperLimitShortest()

double MCMCInterval::UpperLimitShortest ( RooRealVar & param )

virtual

get the upper limit of param in the confidence interval Note that this works better for some distributions (ones with exactly one maximum) than others, and sometimes has little value.

Definition at line 1001 of file MCMCInterval.cxx.

◆ UpperLimitTailFraction()

double MCMCInterval::UpperLimitTailFraction ( RooRealVar & param )

virtual

determine upper limit of the lower confidence interval

Definition at line 980 of file MCMCInterval.cxx.

◆ WithinDeltaFraction()

bool MCMCInterval::WithinDeltaFraction	(	double	a,
		double	b
	)

inlineprivate

Definition at line 1414 of file MCMCInterval.cxx.

Member Data Documentation

◆ DEFAULT_DELTA

constexpr const double RooStats::MCMCInterval::DEFAULT_DELTA = 10e-6

staticconstexprprivate

Definition at line 279 of file MCMCInterval.h.

◆ DEFAULT_EPSILON

constexpr const double RooStats::MCMCInterval::DEFAULT_EPSILON = 0.01

staticconstexprprivate

Definition at line 278 of file MCMCInterval.h.

◆ fAxes

RooRealVar** RooStats::MCMCInterval::fAxes = nullptr

protected

array of pointers to RooRealVars representing the axes of the histogram fAxes[0] represents x-axis, [1] y, [2] z, etc

Definition at line 318 of file MCMCInterval.h.

◆ fChain

MarkovChain* RooStats::MCMCInterval::fChain = nullptr

protected

the markov chain

Definition at line 283 of file MCMCInterval.h.

◆ fConfidenceLevel

double RooStats::MCMCInterval::fConfidenceLevel = 0.0

protected

Requested confidence level (eg. 0.95 for 95% CL)

Definition at line 284 of file MCMCInterval.h.

◆ fCutoffVar

RooRealVar* RooStats::MCMCInterval::fCutoffVar = nullptr

protected

cutoff variable to use for integrating keys pdf

Definition at line 295 of file MCMCInterval.h.

◆ fDataHist

RooDataHist* RooStats::MCMCInterval::fDataHist = nullptr

protected

the binned Markov Chain data

Definition at line 286 of file MCMCInterval.h.

◆ fDelta

double RooStats::MCMCInterval::fDelta = DEFAULT_DELTA

protected

topCutoff (a) considered == bottomCutoff (b) iff (std::abs(a - b) < std::abs(fDelta * (a + b)/2)); Theoretically, the Abs is not needed here, but floating-point arithmetic does not always work perfectly, and the Abs doesn't hurt

Definition at line 324 of file MCMCInterval.h.

◆ fDimension

Int_t RooStats::MCMCInterval::fDimension = 1

protected

number of variables

Definition at line 315 of file MCMCInterval.h.

◆ fEpsilon

double RooStats::MCMCInterval::fEpsilon = DEFAULT_EPSILON

protected

acceptable error for Keys interval determination

Definition at line 322 of file MCMCInterval.h.

◆ fFull

double RooStats::MCMCInterval::fFull = 0.0

protected

Value of intergral of fProduct.

Definition at line 298 of file MCMCInterval.h.

◆ fHeaviside

Heaviside* RooStats::MCMCInterval::fHeaviside = nullptr

protected

the Heaviside function

Definition at line 293 of file MCMCInterval.h.

◆ fHist

TH1* RooStats::MCMCInterval::fHist = nullptr

protected

the binned Markov Chain data

Definition at line 307 of file MCMCInterval.h.

◆ fHistConfLevel

double RooStats::MCMCInterval::fHistConfLevel = 0.0

protected

the actual conf level determined by hist

Definition at line 288 of file MCMCInterval.h.

◆ fHistCutoff

double RooStats::MCMCInterval::fHistCutoff = -1

protected

cutoff bin size to be in interval

Definition at line 289 of file MCMCInterval.h.

◆ fIntervalType

enum IntervalType RooStats::MCMCInterval::fIntervalType = kShortest

protected

Definition at line 329 of file MCMCInterval.h.

◆ fIsHistStrict

bool RooStats::MCMCInterval::fIsHistStrict = true

protected

whether the specified confidence level is a floor for the actual confidence level (strict), or a ceiling (not strict) for determination by histogram

Definition at line 311 of file MCMCInterval.h.

◆ fKeysConfLevel

double RooStats::MCMCInterval::fKeysConfLevel = 0.0

protected

the actual conf level determined by keys

Definition at line 296 of file MCMCInterval.h.

◆ fKeysCutoff

double RooStats::MCMCInterval::fKeysCutoff = -1

protected

cutoff keys pdf value to be in interval

Definition at line 297 of file MCMCInterval.h.

◆ fKeysDataHist

RooDataHist* RooStats::MCMCInterval::fKeysDataHist = nullptr

protected

data hist representing product

Definition at line 294 of file MCMCInterval.h.

◆ fKeysPdf

RooNDKeysPdf* RooStats::MCMCInterval::fKeysPdf = nullptr

protected

the kernel estimation pdf

Definition at line 291 of file MCMCInterval.h.

◆ fLeftSideTF

double RooStats::MCMCInterval::fLeftSideTF = -1

protected

left side tail-fraction for interval

Definition at line 300 of file MCMCInterval.h.

◆ fNumBurnInSteps

Int_t RooStats::MCMCInterval::fNumBurnInSteps = 0

protected

number of steps to discard as burn in, starting from the first

Definition at line 316 of file MCMCInterval.h.

◆ fParameters

RooArgSet RooStats::MCMCInterval::fParameters

protected

parameters of interest for this interval

Definition at line 282 of file MCMCInterval.h.

◆ fProduct

RooProduct* RooStats::MCMCInterval::fProduct = nullptr

protected

the (keysPdf * heaviside) product

Definition at line 292 of file MCMCInterval.h.

◆ fSparseHist

THnSparse* RooStats::MCMCInterval::fSparseHist = nullptr

protected

the binned Markov Chain data

Definition at line 287 of file MCMCInterval.h.

◆ fTFConfLevel

double RooStats::MCMCInterval::fTFConfLevel = 0.0

protected

the actual conf level of tail-fraction interval

Definition at line 301 of file MCMCInterval.h.

◆ fTFLower

double RooStats::MCMCInterval::fTFLower

protected

lower limit of the tail-fraction interval

Definition at line 304 of file MCMCInterval.h.

◆ fTFUpper

double RooStats::MCMCInterval::fTFUpper

protected

upper limit of the tail-fraction interval

Definition at line 305 of file MCMCInterval.h.

◆ fUseKeys

bool RooStats::MCMCInterval::fUseKeys = false

protected

whether to use kernel estimation

Definition at line 309 of file MCMCInterval.h.

◆ fUseSparseHist

bool RooStats::MCMCInterval::fUseSparseHist = false

protected

whether to use sparse hist (vs. RooDataHist)

Definition at line 310 of file MCMCInterval.h.

◆ fVector

std::vector<Int_t> RooStats::MCMCInterval::fVector

protected

vector containing the Markov chain data

Definition at line 302 of file MCMCInterval.h.

◆ fVecWeight

double RooStats::MCMCInterval::fVecWeight = 0

protected

sum of weights of all entries in fVector

Definition at line 303 of file MCMCInterval.h.

Libraries for RooStats::MCMCInterval:

[legend]

The documentation for this class was generated from the following files:

roofit/roostats/inc/RooStats/MCMCInterval.h
roofit/roostats/src/MCMCInterval.cxx

Using a Kernel-Estimated PDF: (not the default method)

Using a binned data set: (the default method)

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Private Member Functions

Static Private Attributes

Additional Inherited Members

Member Enumeration Documentation

◆ anonymous enum

◆ IntervalType

Constructor & Destructor Documentation

◆ MCMCInterval() [1/2]

◆ MCMCInterval() [2/2]

◆ ~MCMCInterval()

Member Function Documentation

◆ AcceptableConfLevel()

◆ CalcConfLevel()

◆ CheckParameters()

◆ Class()

◆ Class_Name()

◆ Class_Version()

◆ ConfidenceLevel()

◆ CreateDataHist()

◆ CreateHist()

◆ CreateKeysDataHist()

◆ CreateKeysPdf()

◆ CreateSparseHist()

◆ CreateVector()

◆ DeclFileName()

◆ DetermineByDataHist()

◆ DetermineByHist()

◆ DetermineByKeys()

◆ DetermineBySparseHist()

◆ DetermineInterval()

◆ DetermineShortestInterval()

◆ DetermineTailFractionInterval()

◆ GetActualConfidenceLevel()

◆ GetAxes()

◆ GetChain()

◆ GetChainAsConstDataSet()

◆ GetChainAsDataHist()

◆ GetChainAsDataSet()

◆ GetChainAsSparseHist()

◆ GetDimension()

◆ GetHistCutoff()

◆ GetIntervalType()

◆ GetKeysMax()

◆ GetKeysPdfCutoff()

◆ GetNLLVar()

◆ GetNumBurnInSteps()

◆ GetParameters()

◆ GetPosteriorHist()

◆ GetPosteriorKeysPdf()

◆ GetPosteriorKeysProduct()

◆ GetUseKeys()

◆ GetWeightVar()

◆ IsA()

◆ IsInInterval()

◆ LowerLimit()

◆ LowerLimitByDataHist()

◆ LowerLimitByHist()

◆ LowerLimitByKeys()

◆ LowerLimitBySparseHist()

◆ LowerLimitShortest()

◆ LowerLimitTailFraction()

◆ SetAxes()

◆ SetChain()

◆ SetConfidenceLevel()

◆ SetDelta()

◆ SetEpsilon()

◆ SetHistStrict()

◆ SetIntervalType()

◆ SetLeftSideTailFraction()

◆ SetNumBurnInSteps()

◆ SetParameters()

◆ SetShortestInterval()

◆ SetUseKeys()