Upper limit calculation tool. More...

#include <ctulimit.hpp>

Inheritance diagram for ctulimit:

Public Member Functions
	ctulimit (void)
	Void constructor. More...

	ctulimit (const GObservations &obs)
	Observations constructor. More...

	ctulimit (int argc, char *argv[])
	Command line constructor. More...

	ctulimit (const ctulimit &app)
	Copy constructor. More...

virtual	~ctulimit (void)
	Destructor. More...

ctulimit &	operator= (const ctulimit &app)
	Assignment operator. More...

void	clear (void)
	Clear ctulimit tool. More...

void	process (void)
	Compute upper limit. More...

void	save (void)
	Save upper limits. More...

const double &	diff_ulimit (void) const
	Return differential upper limit. More...

const double &	flux_ulimit (void) const
	Return flux upper limit. More...

const double &	eflux_ulimit (void) const
	return energy flux upper limit More...

Public Member Functions inherited from ctlikelihood
	ctlikelihood (const std::string &name, const std::string &version)
	Name constructor. More...

	ctlikelihood (const std::string &name, const std::string &version, const GApplicationPars &pars)
	Application parameters constructor. More...

	ctlikelihood (const std::string &name, const std::string &version, int argc, char *argv[])
	Command line constructor. More...

	ctlikelihood (const std::string &name, const std::string &version, const GObservations &obs)
	Observations constructor. More...

	ctlikelihood (const ctlikelihood &app)
	Copy constructor. More...

virtual	~ctlikelihood (void)
	Destructor. More...

ctlikelihood &	operator= (const ctlikelihood &app)
	Assignment operator. More...

void	opt (const GOptimizer *opt)
	Set optimizer. More...

const GOptimizer *	opt (void) const
	Return optimizer. More...

Public Member Functions inherited from ctobservation
	ctobservation (const std::string &name, const std::string &version)
	Name constructor. More...

	ctobservation (const std::string &name, const std::string &version, const GApplicationPars &pars)
	Application parameters constructor. More...

	ctobservation (const std::string &name, const std::string &version, int argc, char *argv[])
	Command line constructor. More...

	ctobservation (const std::string &name, const std::string &version, const GObservations &obs)
	Observations constructor. More...

	ctobservation (const ctobservation &app)
	Copy constructor. More...

virtual	~ctobservation (void)
	Destructor. More...

ctobservation &	operator= (const ctobservation &app)
	Assignment operator. More...

void	obs (const GObservations &obs)
	Set observation container. More...

const GObservations &	obs (void) const
	Return observation container. More...

Public Member Functions inherited from ctool
	ctool (const std::string &name, const std::string &version)
	Name constructor. More...

	ctool (const std::string &name, const std::string &version, const GApplicationPars &pars)
	Application parameter constructor. More...

	ctool (const std::string &name, const std::string &version, int argc, char *argv[])
	Command line constructor. More...

	ctool (const ctool &app)
	Copy constructor. More...

virtual	~ctool (void)
	Destructor. More...

ctool &	operator= (const ctool &app)
	Assignment operator. More...

virtual void	run (void)
	Run ctool. More...

virtual void	execute (void)
	Execute ctool. More...

Protected Member Functions
void	init_members (void)
	Initialise class members. More...

void	copy_members (const ctulimit &app)
	Copy class members. More...

void	free_members (void)
	Delete class members. More...

void	get_parameters (void)
	Get application parameters. More...

void	get_model_parameter (void)
	Get model parameter. More...

void	get_parameter_brackets (double &parmin, double &parmax)
	Determine parameter brackets. More...

void	ulimit_bisection (const double &parmin, const double &parmax)
	Calculate upper limit using a bisection method. More...

void	compute_ulimit (void)
	Compute upper limit intensity and fluxes. More...

Protected Member Functions inherited from ctlikelihood
double	evaluate (GModelPar &par, const double &value)
	Evaluates the log-likelihood function. More...

void	init_members (void)
	Initialise class members. More...

void	copy_members (const ctlikelihood &app)
	Copy class members. More...

void	free_members (void)
	Delete class members. More...

Protected Member Functions inherited from ctobservation
GCTAObservation *	first_unbinned_observation (void)
	Return first unbinned CTA observation. More...

GCTAObservation *	next_unbinned_observation (void)
	Return next unbinned CTA observation. More...

const GCTAObservation *	first_unbinned_observation (void) const
	Return first unbinned CTA observation (const version) More...

const GCTAObservation *	next_unbinned_observation (void) const
	Return next unbinned CTA observation (const version) More...

void	read_ogip_keywords (GFitsHDU *hdu) const
	Read OGIP keywords from FITS HDU. More...

void	write_ogip_keywords (GFitsHDU *hdu) const
	Write OGIP keywords in FITS HDU. More...

void	set_obs_statistic (const std::string &statistic)
	Set fit statistic for CTA observations. More...

void	set_obs_bounds ()
	Set observation boundaries for CTA observations. More...

void	save_events_fits (void)
	Save event list in FITS format. More...

void	save_events_xml (void)
	Save event list(s) in XML format. More...

void	init_members (void)
	Initialise class members. More...

void	copy_members (const ctobservation &app)
	Copy class members. More...

void	free_members (void)
	Delete class members. More...

Protected Member Functions inherited from ctool
void	init_members (void)
	Initialise class members. More...

void	copy_members (const ctool &app)
	Copy class members. More...

void	free_members (void)
	Delete class members. More...

void	sync_pfiles (void)
	Synchronise parameter files. More...

const bool &	read_ahead (void) const
	Signal whether parameters should be read ahead. More...

void	setup_observations (GObservations &obs, const bool &response=true, const bool &list=true, const bool &cube=true)
	Setup observation container. More...

void	setup_models (GObservations &obs, const std::string &name="")
	Setup model container. More...

GEbounds	create_ebounds (void)
	Create energy boundaries from user parameters. More...

GEnergies	create_energies (void)
	Create energies from user parameters. More...

GSkyMap	create_map (const GObservations &obs)
	Create a skymap from user parameters. More...

GCTAEventCube	create_cube (const GObservations &obs)
	Create a CTA event cube from user parameters. More...

GCTAObservation	create_cta_obs (void)
	Create a CTA observation from User parameters. More...

void	require_inobs (const std::string &method)
	Throws exception if inobs parameter is not valid. More...

void	require_inobs_nolist (const std::string &method)

void	require_inobs_nocube (const std::string &method)
	Throws exception if inobs parameter is a counts cube. More...

GCTARoi	get_roi (const GCTAPointing &pnt=GCTAPointing())
	Return RoI from User parameters. More...

GEbounds	get_ebounds (void)
	Return energy boundaries from User parameters. More...

GGti	get_gti (const GTimeReference &ref)
	Return Good Time Intervals from User parameter. More...

GCTAPointing	get_pointing (void)
	Return CTA pointing from User parameters. More...

GSkyDir	get_skydir (void)
	Return sky direction from User parameters. More...

std::string	set_outfile_name (const std::string &filename)
	Set output file name. More...

bool	is_stacked (void)
	Query user parameters for stacked analysis. More...

bool	is_onoff (void)
	Query user parameters for On/Off analysis. More...

void	log_parameters (const GChatter &chatter)
	Log application parameters. More...

void	log_observations (const GChatter &chatter, const GObservations &obs, const std::string &what="Observation")
	Log observation container. More...

void	log_models (const GChatter &chatter, const GModels &models, const std::string &what="Model")
	Log model container. More...

void	set_response (GObservations &obs)
	Set response for all CTA observations in container. More...

std::vector< bool >	set_edisp (GObservations &obs, const bool &edisp) const
	Set energy dispersion to CTA observations. More...

void	restore_edisp (GObservations &obs, const std::vector< bool > &edisp) const
	Restore energy dispersion flags of CTA observations. More...

void	set_obs_response (GCTAObservation *obs)
	Set response for CTA observation. More...

GObservations	get_observations (const bool &get_response=true)
	Get observation container. More...

GSkyDir	get_mean_pointing (const GObservations &obs)
	Derives mean pointing from CTA observations. More...

size_t	get_current_rss (void)
	Get current resident set size (physical memory use) in Bytes. More...

std::string	get_obs_header (const GObservation *obs) const
	Return observation header string. More...

GEnergies	insert_energy_boundaries (const GEnergies &energies, const GCTAObservation &obs)
	Insert observation energy boundaries into list of energies. More...

std::vector< bool >	cube_layer_usage (const GEbounds &cube_ebounds, const GEbounds &list_ebounds) const
	Determine the counts cube layer usage. More...

std::string	get_gtiname (const std::string &filename, const std::string &evtname) const
	Get Good Time Intervals extension name. More...

void	save_event_list (const GCTAObservation *obs, const std::string &infile, const std::string &evtname, const std::string &gtiname, const std::string &outfile) const
	Save event list into FITS file. More...

std::string	warn_too_few_energies (const GEnergies &energies) const
	Set warning string if there are too few energies. More...

std::string	warn_xml_suffix (const GFilename &filename) const
	Set warning string if file has no .xml suffix. More...

void	provide_help (void) const
	Dump help text in the console. More...

Protected Attributes
std::string	m_srcname
	Name of source for upper limit computation. More...

std::string	m_parname
	Name of parameter for upper limit computation. More...

double	m_confidence
	Confidence level. More...

double	m_sigma_min
	Starting value minimum (multiple fit errors above fit values) More...

double	m_sigma_max
	Starting value maximum (multiple fit errors above fit values) More...

double	m_eref
	Reference energy for flux limits (TeV) More...

double	m_emin
	Minimum energy for flux limits (TeV) More...

double	m_emax
	Maximum energy for flux limits (TeV) More...

double	m_tol
	Tolerance for limit determination. More...

int	m_max_iter
	Maximum number of iterations. More...

bool	m_apply_edisp
	Apply energy dispersion? More...

GChatter	m_chatter
	Chattiness. More...

double	m_dlogL
	Likelihood difference for upper limit computation. More...

double	m_best_logL
	Best fit log likelihood of given model. More...

double	m_best_value
	Best parameter value factor. More...

double	m_best_error
	Best parameter value error. More...

double	m_diff_ulimit
	Differential upper limit value. More...

double	m_flux_ulimit
	Flux upper limit value. More...

double	m_eflux_ulimit
	Energy flux upper limits. More...

GModelSky *	m_skymodel
	Pointer to sky model. More...

GModelPar *	m_model_par
	Pointer to model parameter. More...

bool	m_is_spatial
	Signal that model parameter is spatial parameter. More...

Protected Attributes inherited from ctlikelihood
GOptimizerLM	m_opt
	Optimizer. More...

Protected Attributes inherited from ctobservation
GObservations	m_obs
	Observation container. More...

Protected Attributes inherited from ctool
bool	m_read_ahead
	Read ahead output parameters. More...

bool	m_use_xml
	Use XML file instead of FITS file for observations. More...

Detailed Description

Upper limit calculation tool.

This class computes and upper limit for a given source.

The class operates on predefined observation containers, an individual event list or an observation definition XML file.

During the computation the likelihood function is inspected to find the best value for the upper limit.

Definition at line 50 of file ctulimit.hpp.

Constructor & Destructor Documentation

ctulimit::ctulimit ( void )

Void constructor.

Constructs an empty ctulimit tool.

Definition at line 58 of file ctulimit.cpp.

References init_members().

ctulimit::ctulimit ( const GObservations & obs )

explicit

Observations constructor.

param[in] obs Observation container.

Constructs ctulimit tool from an observations container.

Definition at line 75 of file ctulimit.cpp.

References init_members().

ctulimit::ctulimit	(	int	argc,
		char *	argv[]
	)

Command line constructor.

Parameters

[in]	argc	Number of arguments in command line.
[in]	argv	Array of command line arguments.

Constructs an instance of the ctulimit tool that will parse user parameters that are provided as command line arguments.

Definition at line 96 of file ctulimit.cpp.

References init_members().

ctulimit::ctulimit ( const ctulimit & app )

Copy constructor.

Parameters

[in] app Application.

Constructs an instance of the ctulimit tool by copying information from another ctulimit tool.

Definition at line 115 of file ctulimit.cpp.

References copy_members(), and init_members().

ctulimit::~ctulimit ( void )

virtual

Destructor.

Destructs the ctulimit tool.

Definition at line 133 of file ctulimit.cpp.

References free_members().

Member Function Documentation

void ctulimit::clear ( void )

virtual

Clear ctulimit tool.

Resets the ctulimit tool to a clean initial state.

Implements ctlikelihood.

Definition at line 192 of file ctulimit.cpp.

References free_members(), ctlikelihood::free_members(), ctool::free_members(), ctobservation::free_members(), init_members(), ctlikelihood::init_members(), ctool::init_members(), and ctobservation::init_members().

void ctulimit::compute_ulimit ( void )

protected

Compute upper limit intensity and fluxes.

Compute upper limit intensity and fluxes, including a correct computation for the diffuse map cube models.

Definition at line 834 of file ctulimit.cpp.

References m_diff_ulimit, m_eflux_ulimit, m_emax, m_emin, m_eref, m_flux_ulimit, and m_skymodel.

Referenced by process().

void ctulimit::copy_members ( const ctulimit & app )

protected

Copy class members.

Parameters

[in] app Application.

Definition at line 398 of file ctulimit.cpp.

References get_model_parameter(), m_apply_edisp, m_best_error, m_best_logL, m_best_value, m_chatter, m_confidence, m_diff_ulimit, m_dlogL, m_eflux_ulimit, m_emax, m_emin, m_eref, m_flux_ulimit, m_max_iter, m_parname, m_sigma_max, m_sigma_min, m_srcname, and m_tol.

Referenced by ctulimit(), and operator=().

const double & ctulimit::diff_ulimit ( void ) const

inline

Return differential upper limit.

Returns: Differential upper flux limit.

Definition at line 116 of file ctulimit.hpp.

References m_diff_ulimit.

const double & ctulimit::eflux_ulimit ( void ) const

inline

return energy flux upper limit

Returns: Upper energy flux limit.

Definition at line 140 of file ctulimit.hpp.

References m_eflux_ulimit.

const double & ctulimit::flux_ulimit ( void ) const

inline

Return flux upper limit.

Returns: Upper flux limit.

Definition at line 128 of file ctulimit.hpp.

References m_flux_ulimit.

void ctulimit::free_members ( void )

protected

Delete class members.

Definition at line 434 of file ctulimit.cpp.

Referenced by clear(), operator=(), and ~ctulimit().

void ctulimit::get_model_parameter ( void )

protected

Get model parameter.

Exceptions

GException::invalid_value Did not find a valid model or model parameter

Extracts a pointer to the sky model (m_skymodel) and a pointer to the model parameter (m_model_par) that should be varied for the upper limit determination from the model container.

Definition at line 510 of file ctulimit.cpp.

References G_GET_MODEL_PARAMETER, m_is_spatial, m_model_par, ctobservation::m_obs, m_parname, m_skymodel, and m_srcname.

Referenced by copy_members(), and get_parameters().

void ctulimit::get_parameter_brackets	(	double &	parmin,
		double &	parmax
	)

protected

Determine parameter brackets.

Parameters

[out]	parmin	Minimum parameter value.
[out]	parmax	Maximum parameter value.

Exceptions

GException::invalid_value Exceeded maximum number of iterations in the bracket search.

Determines the brackets for the parameter of interest.

Definition at line 620 of file ctulimit.cpp.

References ctlikelihood::evaluate(), G_GET_PARAMETER_BRACKETS, m_best_error, m_best_logL, m_best_value, m_dlogL, m_is_spatial, m_max_iter, m_model_par, ctobservation::m_obs, m_sigma_max, m_sigma_min, and m_srcname.

Referenced by process().

void ctulimit::get_parameters ( void )

protected

Get application parameters.

Get all task parameters from parameter file.

Definition at line 446 of file ctulimit.cpp.

References get_model_parameter(), ctool::log_parameters(), m_apply_edisp, m_chatter, m_confidence, m_dlogL, m_emax, m_emin, m_eref, m_max_iter, ctobservation::m_obs, ctlikelihood::m_opt, m_parname, m_sigma_max, m_sigma_min, m_srcname, m_tol, ctobservation::set_obs_statistic(), ctool::setup_models(), and ctool::setup_observations().

Referenced by process().

void ctulimit::init_members ( void )

protected

Initialise class members.

Definition at line 360 of file ctulimit.cpp.

References m_apply_edisp, m_best_error, m_best_logL, m_best_value, m_chatter, m_confidence, m_diff_ulimit, m_dlogL, m_eflux_ulimit, m_emax, m_emin, m_eref, m_flux_ulimit, m_is_spatial, m_max_iter, m_model_par, m_parname, m_sigma_max, m_sigma_min, m_skymodel, m_srcname, and m_tol.

Referenced by clear(), ctulimit(), and operator=().

ctulimit & ctulimit::operator= ( const ctulimit & app )

Assignment operator.

Parameters

[in] app Application.

Returns: Application.

Assigns a ctulimit tool.

Definition at line 157 of file ctulimit.cpp.

References copy_members(), free_members(), init_members(), and ctlikelihood::operator=().

void ctulimit::process ( void )

virtual

Compute upper limit.

Computes the upper limit depending on the given algorithm

Implements ctlikelihood.

Definition at line 222 of file ctulimit.cpp.

References compute_ulimit(), get_parameter_brackets(), get_parameters(), ctool::log_observations(), m_apply_edisp, m_best_logL, m_best_value, m_chatter, m_confidence, m_diff_ulimit, m_dlogL, m_eflux_ulimit, m_emax, m_emin, m_eref, m_flux_ulimit, m_model_par, ctobservation::m_obs, ctlikelihood::m_opt, m_skymodel, ctool::restore_edisp(), ctool::set_edisp(), and ulimit_bisection().

void ctulimit::save ( void )

virtual

Save upper limits.

Saves the upper limit to an ASCII file in comma-separated value format.

Todo:: No yet implemented as we have no clear use case yet for saving the result.

Implements ctlikelihood.

Definition at line 344 of file ctulimit.cpp.

void ctulimit::ulimit_bisection	(	const double &	parmin,
		const double &	parmax
	)

protected

Calculate upper limit using a bisection method.

Parameters

[in]	parmin	Minimum parameter value
[in]	parmax	Maximum parameter value

Exceptions

GException::invalid_value Exceeded maximum number of iterations in the upper limit search.

Calculates the upper limit using a bisection method. The bisection is stopped if the log-likelihood value is within the tolerance of the target value. The bisection is also stopped putting a warning in the log file if the parameter interval becomes smaller than a tolerance of 1.0e-6. The method stops with an exception if the maximum number of iterations is exhausted.

Definition at line 709 of file ctulimit.cpp.

References ctlikelihood::evaluate(), G_UL_BISECTION, m_best_logL, m_best_value, m_dlogL, m_is_spatial, m_max_iter, m_model_par, ctobservation::m_obs, m_srcname, and m_tol.