inj#

Event injectors and randomization methods.

Classes:

`Randomizer`()	Base class for event randomizers.
`RARandomizer`()	Randomize events uniformly in right ascension.
`DecRandomizer`([dec_rand_method, ...])	Randomize events in declination.
`SinDecRandomizer`(sindec_jitter)	Randomize events in sin declination.
`PoleRandomizer`(pole_radius[, shuffle, ...])	Randomize declinations of events near the North and South poles.
`EnergyRandomizer`(sigma_log10)	Randomize event energies.
`MJDShuffleRandomizer`()	Shuffle event times.
`MJDGRLRandomizer`(grl[, presample, rates_by])	Randomize event times according to GRL.
`Selector`()	Base class for event selectors.
`DecBandSelector`(src[, cut_n_sigma])	Select events based on proximity in declination to source(s).
`TimeWindowSelector`(mjd_min, mjd_max)	Select events within a given time window.
`Injector`()	Base class for event injectors.
`DataInjector`(ana, data, keep[, randomizers, ...])	Inject real data events.
`DataOnOffInjector`(ana, time_model, keep[, ...])	Inject off-time events into on-time windows.
`MCBackgroundInjector`(ana, bg_weight_names, keep)	Inject background events using weighted MC events to model the background instead of scrambling data in RA.
`SigInjector`()	Base class for signal injectors.
`PointSourceInjector`(ana, src, flux, keep[, ...])	Inject one or more point-like sources.
`PointSourceTimeDepInjector`(ana, src, flux, keep)	Base class for for time-dependent injection from point-like sources.
`PointSourceTimeWindowInjector`(ana, src, ...)	Inject Gaussian or time box flares.
`PointSourceRedNoiseInjector`(ana, src, flux, ...)	Inject red noise as signal.
`PointSourceBinnedTimeInjector`(ana, src, ...)	Inject events distributed according to a binned lightcurve.
`TransientInjector`(ana, time_model, flux, keep)	Inject events from transient sources.
`TemplateInjector`(ana, template_model, keep)	Inject a highly-extended source according to a spatial template.
`TemplateBGInjector`(ana, template_model, ...)	Inject typical types of background along with a highly-extended source according to a spatial template.
`SpatialPriorInjector`(ana, src, flux, keep, ...)	Injection of one or more point-like sources, whose position is not exactly known, but given in the form of a spatial prior (healpix map).

class csky.inj.Randomizer[source]#

Bases: object

Base class for event randomizers.

Classes which randomize(or scramble) data events should derive from this class.

Methods:

`__init__`()
`__call__`(ev[, seed])	Randomize events in place.

__init__()[source]#

abstract __call__(ev, seed=None)[source]#

Randomize events in place.

Parameters:

ev (utils.Events) – the events
seed (int or numpy.random.RandomState) – seed spec

class csky.inj.RARandomizer[source]#

Bases: Randomizer

Randomize events uniformly in right ascension.

Methods:

`__call__`(ev[, seed])	Randomize events in place.
`__init__`()

__call__(ev, seed=None)[source]#

Randomize events in place.

Parameters:

ev (utils.Events) – the events
seed (int or numpy.random.RandomState) – seed spec

__init__()#

class csky.inj.DecRandomizer(dec_rand_method='gaussian_sigma', dec_rand_kwargs=None, dec_rand_pole_exlusion=None)[source]#

Bases: Randomizer

Randomize events in declination.

This class applies randomization to the event declinations. Multiple randomization methods are available, which need to be specified via the dec_rand_method keyword. Additionally, events near the poles can be excluded from the randomization by setting the pole exclusion radius via the keyword dec_rand_pole_exlusion.

Methods:

`__init__`([dec_rand_method, dec_rand_kwargs, ...])	Construct a DecRandomizer
`__call__`(ev[, seed])	Randomize events

__init__(dec_rand_method='gaussian_sigma', dec_rand_kwargs=None, dec_rand_pole_exlusion=None)[source]#

Construct a DecRandomizer

Parameters:

dec_rand_method (str) –
The randomization method to use. ‘gaussian_sigma’:

Applies Gaussian-distributed noise to the event declinations. The width of the Gaussians is based on the per-event angular uncertainties sigma. Additional kwargs (to be passed via dec_rand_kwargs):

’sigma_scaling’:
Scaling factor that will be applied to the per-event angular uncertainties prior to randomization. This only affects the randomization - event angular uncertainties will not be modified.

’uniform_sigma’:
Applies uniform jitter to the event declinations. The width of the jitter is based on the per-event angular uncertainties sigma. Additional kwargs (to be passed via dec_rand_kwargs):

’sigma_scaling’:
Scaling factor that will be applied to the per-event angular uncertainties prior to randomization. This only affects the randomization - event angular uncertainties will not be modified.

’gaussian_fixed’:
Applies Gaussian-distributed noise to the event declinations. The width of the Gaussians is set to randomization_width. Additional kwargs (to be passed via dec_rand_kwargs):

’randomization_width’:
The sigma of the Gaussian.

’uniform_fixed’:
Applies uniform jitter to the event declinations. The width of the Gaussians is set to randomization_width. Additional kwargs (to be passed via dec_rand_kwargs):

’randomization_width’:
The width for the jitter. Events will be randomized to dec +- width.
dec_rand_kwargs (dict) – Additional keyword arguments provided as a dictionary. See dec_rand_method for details on which kwargs are necessary for the specified randomization method.
dec_rand_pole_exlusion (float) – Radius of the polar regions(in radians), which will be ignored. Events with declinations in this pole region will not be randomized. If `None`(default), then all events are randomized.

__call__(ev, seed=None)[source]#: Randomize events

class csky.inj.SinDecRandomizer(sindec_jitter)[source]#

Bases: Randomizer

Randomize events in sin declination.

This class applies a jitter of specified strength to the sin(dec) values. The jitter strength should not be chosen much larger than the sin(dec) bin-widths in the PDFs. Randomization should not change the joint PDFs of the observables, since the background PDF is only created once at initialization (and optionally updated with the injected signal via the update_bg parameter). If binning is performed uniformly in sin(dec), a jitter strength of the order of the bin-width is probably fine as long as there are no big jumps in the PDF between consecutive bins. Otherwise, a smaller jitter value should be chosen.

Because the SinDecRandomizer modifies the sin(dec) values instead of the declination directly, it applies a stronger randomization in terms of modified declination at the poles.

Methods:

`__init__`(sindec_jitter)	Construct a SinDecRandomizer
`__call__`(ev[, seed])	Randomize events in place.

__init__(sindec_jitter)[source]#

Construct a SinDecRandomizer

Parameters:

sindec_jitter (float) –

jitter strength in sin(dec). The sin(dec) values will be modified via:

sin(dec) += uniform(-sindec_jitter, sindec_jitter)

__call__(ev, seed=None)[source]#

Randomize events in place.

Parameters:

ev (utils.Events) – the events
seed (int or numpy.random.RandomState) – seed spec

class csky.inj.PoleRandomizer(pole_radius, shuffle=True, sample_dec=False)[source]#

Bases: Randomizer

Randomize declinations of events near the North and South poles.

This class randomizes the declinations of events near the poles. This is mainly useful for cascade analysis, where it is non-obvious how much of the polar regions should simply be neglected. It may also be useful in track analyses if the user is specifically interested in sources near one or both of the poles.

Methods:

`__init__`(pole_radius[, shuffle, sample_dec])	Construct a PoleRandomizer.
`__call__`(ev[, seed])	Randomize events in place.

__init__(pole_radius, shuffle=True, sample_dec=False)[source]#

Construct a PoleRandomizer.

Parameters:

pole_radius (float) – radius of the polar regions(in radians)
shuffle (bool) – if false, scramble polar events uniformly throughout the poles in which they each actually originated; if true(default), then instead randomize polar events’ declinations by applying a random permutation of these. if sample_dec is set to true, then the declination values are additionally smeared by a Gaussian (see description for sample_dec).
sample_dec (bool) – if true, the event declinations at the poles are additionally randomized by sampling from a Gaussian with the width set to the event sigma. Note that this setting may push events from the poles away towards the equator and therefore modify the joint PDFs! If false(default), only the permutation of event declination across events at the pole is performed. This setting is only relevant if shuffle is set to True.

__call__(ev, seed=None)[source]#

Randomize events in place.

Parameters:

ev (utils.Events) – the events
seed (int or numpy.random.RandomState) – seed spec

class csky.inj.EnergyRandomizer(sigma_log10)[source]#

Bases: Randomizer

Randomize event energies.

This class randomizes log10(E/GeV). This may be useful if some events are causing intense spikes in the background distributions at particular declinations. Note that this feature has not been thoroughly tested, if at all.

Methods:

`__init__`(sigma_log10)	Construct an EnergyRandomizer.
`__call__`(ev[, seed])	Randomize events in place.

__init__(sigma_log10)[source]#

Construct an EnergyRandomizer.

Parameters:: sigma_log10 (float) – width of the Gaussian noise to apply to log10(E/GeV)

__call__(ev, seed=None)[source]#

Randomize events in place.

Parameters:

ev (utils.Events) – the events
seed (int or numpy.random.RandomState) – seed spec

class csky.inj.MJDShuffleRandomizer[source]#

Bases: Randomizer

Shuffle event times.

This class shuffles the arrival times(in MJD) of the events.

Methods:

`__call__`(ev[, seed])	Randomize events in place.
`__init__`()

__call__(ev, seed=None)[source]#

Randomize events in place.

Parameters:

ev (utils.Events) – the events
seed (int or numpy.random.RandomState) – seed spec

__init__()#

class csky.inj.MJDGRLRandomizer(grl, presample=0, rates_by='events')[source]#

Bases: Randomizer

Randomize event times according to GRL.

Methods:

`__init__`(grl[, presample, rates_by])
`__call__`(ev[, seed])	Randomize events in place.

__init__(grl, presample=0, rates_by='events')[source]#

__call__(ev, seed=None)[source]#

Randomize events in place.

Parameters:

ev (utils.Events) – the events
seed (int or numpy.random.RandomState) – seed spec

class csky.inj.Selector[source]#

Bases: object

Base class for event selectors.

This is an interface for pre-emptively selecting events prior to [any randomizations as well as] likelihood evaluation. For per-trial masking, see PDFRatioEvaluator.

TODO: actually go and add documentation for masking functionality under PDFRatioEvaluator

Methods:

`mask`(arr)	Get a boolean mask for selected elements of `arr`.
`where`(arr)	Get the indices of selected elements of `arr`.
`__call__`(arr)	Get a downselected copy of `arr`.
`__init__`()

abstract mask(arr)[source]#

Get a boolean mask for selected elements of arr.

Parameters:: arr (utils.Arrays) – the Arrays to mask
Return type:: ndarray of bool
Returns:: the mask

abstract where(arr)[source]#

Get the indices of selected elements of arr.

Parameters:: arr (utils.Arrays) – the Arrays to mask
Return type:: ndarray of bool
Returns:: the indices

abstract __call__(arr)[source]#

Get a downselected copy of arr.

Parameters:: arr (utils.Arrays) – the Arrays to mask
Return type:: same as arr
Returns:: downselected copy(or potentially view) of arr

__init__()#

class csky.inj.DecBandSelector(src, cut_n_sigma=5)[source]#

Bases: Selector

Select events based on proximity in declination to source(s).

This class allows pre-emptive application of the so-called “band” cut(see PointSourceSpacePDFRatioModel for more).

Methods:

`__init__`(src[, cut_n_sigma])	Construct a DecBandSelector.
`mask`(arr)	Get a boolean mask for selected elements of `arr`.
`where`(arr)	Get the indices of selected elements of `arr`.
`__call__`(arr)	Get a downselected copy of `arr`.

__init__(src, cut_n_sigma=5)[source]#

Construct a DecBandSelector.

Parameters:

src (utis.Sources) – the source list. required keys: ra and dec. optional keys: weight, extension
cut_n_sigma (float) – number of sigmas away from a source an event must be within to be included

mask(arr)[source]#

Get a boolean mask for selected elements of arr.

Parameters:: arr (utils.Arrays) – the Arrays to mask
Return type:: ndarray of bool
Returns:: the mask

where(arr)[source]#

Get the indices of selected elements of arr.

Parameters:: arr (utils.Arrays) – the Arrays to mask
Return type:: ndarray of bool
Returns:: the indices

__call__(arr)[source]#

Get a downselected copy of arr.

Parameters:: arr (utils.Arrays) – the Arrays to mask
Return type:: same as arr
Returns:: downselected copy(or potentially view) of arr

class csky.inj.TimeWindowSelector(mjd_min, mjd_max)[source]#

Bases: Selector

Select events within a given time window.

You probably don’t want to use this class; you might be looking for DataOnOffInjector.

Methods:

`__init__`(mjd_min, mjd_max)
`mask`(arr)	Get a boolean mask for selected elements of `arr`.
`where`(arr)	Get the indices of selected elements of `arr`.
`__call__`(arr)	Get a downselected copy of `arr`.

__init__(mjd_min, mjd_max)[source]#

mask(arr)[source]#

Get a boolean mask for selected elements of arr.

Parameters:: arr (utils.Arrays) – the Arrays to mask
Return type:: ndarray of bool
Returns:: the mask

where(arr)[source]#

Get the indices of selected elements of arr.

Parameters:: arr (utils.Arrays) – the Arrays to mask
Return type:: ndarray of bool
Returns:: the indices

__call__(arr)[source]#

Get a downselected copy of arr.

Parameters:: arr (utils.Arrays) – the Arrays to mask
Return type:: same as arr
Returns:: downselected copy(or potentially view) of arr

class csky.inj.Injector[source]#

Bases: object

Base class for event injectors.

Injectors produce event ensembles along with counts of events that could have been injected but were instead pre-emptively excluded using a Selector.

TODO: revisit hierarchy. Background injectors don’t seem to want an n_inj argument at all, in the Injector.inject() method.

Methods:

`inject`(n_inj[, seed])	Get some number of events.
`__init__`()

abstract inject(n_inj, seed=None)[source]#

Get some number of events.

Parameters:

n_inj (int) – number of events to inject
seed (int or numpy.random.RandomState) – seed spec

Return type:

(list of utils.Events, int)

Returns:

(event ensembles, number of pre-emptively excluded events)

__init__()#

class csky.inj.DataInjector(ana, data, keep, randomizers=None, bg_replace=False)[source]#

Bases: Injector

Inject real data events.

This class injects real events from the data, possibly(in fact, almost always) with one or more randomizations applied.

Methods:

`__init__`(ana, data, keep[, randomizers, ...])	Construct a DataInjector.
`inject`([seed])	Get some number of events.

__init__(ana, data, keep, randomizers=None, bg_replace=False)[source]#

Construct a DataInjector.

Parameters:

ana (analysis.SubAnalysis) – the sub analysis
data (utils.Events) – the data events to inject
keep (list of str) – names of event features to keep
randomizers (list of Randomizer) – the randomizers to apply; if not given, RARandomizer is used.
bg_replace (bool) – If true, sampling with replacement will be used.

inject(seed=None)[source]#

Get some number of events.

Parameters:

n_inj (int) – number of events to inject
seed (int or numpy.random.RandomState) – seed spec

Return type:

(list of utils.Events, int)

Returns:

(event ensembles, number of pre-emptively excluded events)

class csky.inj.DataOnOffInjector(ana, time_model, keep, randomizers=None, cut_n_sigma=5, full_sky=False, bg_replace=True)[source]#

Bases: Injector

Inject off-time events into on-time windows.

This class performs the sort of background injection typically used in transient analyses, where the background is taken from off-time data while the analysis is performed in specific on-time windows.

Methods:

`__init__`(ana, time_model, keep[, ...])	Construct a DataOnOffInjector.
`inject`([seed])	Get some number of events.

__init__(ana, time_model, keep, randomizers=None, cut_n_sigma=5, full_sky=False, bg_replace=True)[source]#

Construct a DataOnOffInjector.

Parameters:

ana (analysis.SubAnalysis) – the sub analysis
time_model (pdf.TimePDFRatioModel) – the time PDF ratio model
keep (list of str) – names of event features to keep
randomizers (list of Randomizer) – the randomizers to apply. you probably don’t want to apply any(TODO: reconsider, why exactly is this argument here?)
cut_n_sigma (float) – number of sigmas away from a source an event must be within to be included
bg_replace (bool) – If true, sampling with replacement will be used.

inject(seed=None)[source]#

Get some number of events.

Parameters:

n_inj (int) – number of events to inject
seed (int or numpy.random.RandomState) – seed spec

Return type:

(list of utils.Events, int)

Returns:

(event ensembles, number of pre-emptively excluded events)

class csky.inj.MCBackgroundInjector(ana, bg_weight_names, keep, randomizers=None)[source]#

Bases: Injector

Inject background events using weighted MC events to model the background instead of scrambling data in RA.

This class injects simulated events from the monte carlo, possibly(in fact, almost always) with one or

more randomizations applied.

Methods:

`__init__`(ana, bg_weight_names, keep[, ...])	Construct a PointSourceInjector.
`inject`([replace, seed])	Get some number of events.

__init__(ana, bg_weight_names, keep, randomizers=None)[source]#

Construct a PointSourceInjector.

Parameters:

ana (analysis.SubAnalysis) – the sub analysis
mc (utils.Events) – the monte carlo events to inject
bg_weight_names (list of str) – names of the monte carlo weights saved in the signal events. Weights should be in Hz and already have flux incorporated.
keep (list of str) – names of event features to keep
randomizers (list of Randomizer) – the randomizers to apply to the monte carlo events

inject(replace=False, seed=None)[source]#

Get some number of events.

Parameters:

n_inj (int) – number of events to inject
seed (int or numpy.random.RandomState) – seed spec

Return type:

(list of utils.Events, int)

Returns:

(event ensembles, number of pre-emptively excluded events)

class csky.inj.SigInjector[source]#

Bases: Injector

Base class for signal injectors.

Signal injectors, unlike background injectors, must also be able to provide their total acceptance. This class enforces that requirement using SigInjector.acc_total().

Attributes:

acc_total

Total signal acceptance.

Methods:

`__init__`()
`inject`(n_inj[, seed])	Get some number of events.

abstract property acc_total#

Total signal acceptance.

This is similar to LLHEvaluatorBase.get_acc_total(), but evaluated in light of all specified signal injection details and typically in terms of the actual simulated signal events that will be used.

__init__()#

abstract inject(n_inj, seed=None)#

Get some number of events.

Parameters:

n_inj (int) – number of events to inject
seed (int or numpy.random.RandomState) – seed spec

Return type:

(list of utils.Events, int)

Returns:

(event ensembles, number of pre-emptively excluded events)

class csky.inj.PointSourceInjector(ana, src, flux, keep, sindec_bandwidth=0.03490658503988659)[source]#

Bases: SigInjector

Inject one or more point-like sources.

This class implements the signal injection for classic time-integrated analyses. It transparently supports stacking of multiple sources as well as per-source Gaussian spatial extension.

Methods:

`__init__`(ana, src, flux, keep[, ...])	Construct a PointSourceInjector.
`inject`(n_inj[, seed])	Get some number of events.

Attributes:

acc_total

Total signal acceptance.

__init__(ana, src, flux, keep, sindec_bandwidth=0.03490658503988659)[source]#

Construct a PointSourceInjector.

Parameters:

ana (analysis.SubAnalysis) – the sub analysis
src (utis.Sources) – the source list. required keys: ra and dec. optional keys: weight, extension
flux (hyp.Flux) – the signal spectrum
keep (list of str) – names of event features to keep
sindec_bandwidth (float) – width(not half-width) of the sin(dec) bands from which to draw simulated signal events

property acc_total#

Total signal acceptance.

This is similar to LLHEvaluatorBase.get_acc_total(), but evaluated in light of all specified signal injection details and typically in terms of the actual simulated signal events that will be used.

inject(n_inj, seed=None)[source]#

Get some number of events.

Parameters:

n_inj (int) – number of events to inject
seed (int or numpy.random.RandomState) – seed spec

Return type:

(list of utils.Events, int)

Returns:

(event ensembles, number of pre-emptively excluded events)

class csky.inj.PointSourceTimeDepInjector(ana, src, flux, keep, sindec_bandwidth=0.03490658503988659, spatial_prior=False)[source]#

Bases: SigInjector

Base class for for time-dependent injection from point-like sources.

This is an abstract base class for time-dependent injection from point-like sources. Most of the injection work is done in terms of per-source instances of PointSourceInjector; time-dependence is handled by derived classes’ implementations of the abstract methods PointSourceTimeDepInjector.get_time_model(), PointSourceTimeDepInjector.get_frac_during_livetime(), and PointSourceTimeDepInjector.sample_mjd().

Methods:

`__init__`(ana, src, flux, keep[, ...])	Construct a PointSourceTimeDepInjector.
`get_time_model`()	Get the time PDF ratio model.
`get_frac_during_livetime`()	Get the fraction of the total lightcurve covered by a given dataset.
`sample_mjd`(src_n_injs[, seed])	Get per-source `mjd` arrays.
`inject`(n_inj[, seed])	Get some number of events.

Attributes:

acc_total

Total signal acceptance.

__init__(ana, src, flux, keep, sindec_bandwidth=0.03490658503988659, spatial_prior=False)[source]#

Construct a PointSourceTimeDepInjector.

Parameters:

ana (analysis.SubAnalysis) – the sub analysis
src (utis.Sources) – the source list. required keys: ra and dec. optional keys: weight, extension
flux (hyp.Flux) – the signal spectrum
keep (list of str) – names of event features to keep
sindec_bandwidth (float) – width(not half-width) of the sin(dec) bands from which to draw simulated signal events
spatial_prior (bool) – option to use a spatial prior healpix map for source localisations

abstract get_time_model()[source]#

Get the time PDF ratio model.

Return type:: pdf.TimePDFRatioModel

abstract get_frac_during_livetime()[source]#

Get the fraction of the total lightcurve covered by a given dataset.

See pdf.TimePDFRatioModel.get_frac_during_livetime().

abstract sample_mjd(src_n_injs, seed=None)[source]#

Get per-source mjd arrays.

Parameters:

src_n_injs (ndarray of int) – per-source number of events to inject
seed (int or numpy.random.RandomState) – seed spec

property acc_total#

Total signal acceptance.

This is similar to LLHEvaluatorBase.get_acc_total(), but evaluated in light of all specified signal injection details and typically in terms of the actual simulated signal events that will be used.

inject(n_inj, seed=None)[source]#

Get some number of events.

Parameters:

n_inj (int) – number of events to inject
seed (int or numpy.random.RandomState) – seed spec

Return type:

(list of utils.Events, int)

Returns:

(event ensembles, number of pre-emptively excluded events)

class csky.inj.PointSourceTimeWindowInjector(ana, src, flux, keep, t0, dt, box=False, box_mode='center', endpoints=False, sindec_bandwidth=0.03490658503988659)[source]#

Bases: PointSourceTimeDepInjector

Inject Gaussian or time box flares.

This class implements Gaussian or top-hat time window flare injection for one or more(possibly spatially-extended) sources.

Methods:

`__init__`(ana, src, flux, keep, t0, dt[, ...])	Construct a PointSourceTimeInjector.
`get_time_model`()	Get the time PDF ratio model.
`get_frac_during_livetime`()	Get the fraction of the total lightcurve covered by a given dataset.
`sample_mjd`(src_n_injs[, seed])	Get per-source `mjd` arrays.
`inject`(n_inj[, seed])	Get some number of events.

Attributes:

acc_total

Total signal acceptance.

__init__(ana, src, flux, keep, t0, dt, box=False, box_mode='center', endpoints=False, sindec_bandwidth=0.03490658503988659)[source]#

Construct a PointSourceTimeInjector.

Parameters:

ana (analysis.SubAnalysis) – the sub analysis
src (utis.Sources) – the source list. required keys: ra and dec. optional keys: weight, extension
flux (hyp.Flux) – the signal spectrum
keep (list of str) – names of event features to keep
t0 (ndarray of float) – per-source anchor time-of-flare
dt (ndarray of float) – per-source width of flare(in days)
box (bool) – whether to use box rather than Gaussian flare
box_mode (str) – one of ‘center’, ‘pre’, or ‘post’
endpoints (bool) – injects and flare start and stop times, rather than throughout flare
sindec_bandwidth (float) – width(not half-width) of the sin(dec) bands from which to draw simulated signal events

get_time_model()[source]#

Get the time PDF ratio model.

Return type:: pdf.TimePDFRatioModel

get_frac_during_livetime()[source]#

Get the fraction of the total lightcurve covered by a given dataset.

See pdf.TimePDFRatioModel.get_frac_during_livetime().

sample_mjd(src_n_injs, seed=None)[source]#

Get per-source mjd arrays.

Parameters:

src_n_injs (ndarray of int) – per-source number of events to inject
seed (int or numpy.random.RandomState) – seed spec

property acc_total#

Total signal acceptance.

This is similar to LLHEvaluatorBase.get_acc_total(), but evaluated in light of all specified signal injection details and typically in terms of the actual simulated signal events that will be used.

inject(n_inj, seed=None)#

Get some number of events.

Parameters:

n_inj (int) – number of events to inject
seed (int or numpy.random.RandomState) – seed spec

Return type:

(list of utils.Events, int)

Returns:

(event ensembles, number of pre-emptively excluded events)

class csky.inj.PointSourceRedNoiseInjector(ana, src, flux, keep, dt, beta=2, sindec_bandwidth=0.03490658503988659)[source]#

Bases: PointSourceTimeDepInjector

Inject red noise as signal.

This class implements white/pink/red/black noise injector as a signal light-curve for one source.

Methods:

`__init__`(ana, src, flux, keep, dt[, beta, ...])	Construct a PointSourceRedNoiseInjector.
`get_time_model`()	Get the time PDF ratio model.
`get_frac_during_livetime`()	Get the fraction of the total lightcurve covered by a given dataset.
`sample_mjd`(src_n_injs[, seed])	Get per-source `mjd` arrays.
`generate_rednoise`(N, dt, beta, random[, ...])	Generate a power-law lightcurve This uses the method from Timmer & Koenig [1]
`inject`(n_inj[, seed])	Get some number of events.

Attributes:

acc_total

Total signal acceptance.

__init__(ana, src, flux, keep, dt, beta=2, sindec_bandwidth=0.03490658503988659)[source]#

Construct a PointSourceRedNoiseInjector.

Parameters:

ana (analysis.SubAnalysis) – the sub analysis
src (utils.Sources) – the source list. required keys: ra and dec. optional keys: weight, extension
flux (hyp.Flux) – the signal spectrum
keep (list of str) – names of event features to keep
dt (float (single number)) – spacing between time-steps/noise-curve in units of days (recommended < 50 days)
beta (integer (single number)) – power-law index of noise (default=2 for red noise)
sindec_bandwidth (float) – width(not half-width) of the sin(dec) bands from which to draw simulated signal events

get_time_model()[source]#

Get the time PDF ratio model.

Return type:: pdf.TimePDFRatioModel

get_frac_during_livetime()[source]#

Get the fraction of the total lightcurve covered by a given dataset.

See pdf.TimePDFRatioModel.get_frac_during_livetime().

sample_mjd(src_n_injs, seed=None)[source]#

Get per-source mjd arrays.

Parameters:

src_n_injs (ndarray of int) – per-source number of events to inject
seed (int or numpy.random.RandomState) – seed spec

generate_rednoise(N, dt, beta, random, generate_complex=False)[source]#

Generate a power-law lightcurve This uses the method from Timmer & Koenig [1]

:type N : integer :param N : number of equal-spaced time steps to generate :type dt : float :param dt : spacing between time-steps :type beta : float :param beta : power-law index, the spectrum will be (1 / f)^beta

white noise is beta=0 pink noise is beta=1 red noise is beta=2 black noise is beta>2

:type generate_complex : boolean (optional) :param generate_complex : if True, generate a complex time series rather

than a real time series

References

[1] Timmer, J. & Koenig, M. On Generating Power Law Noise. A&A 300:707

property acc_total#

Total signal acceptance.

This is similar to LLHEvaluatorBase.get_acc_total(), but evaluated in light of all specified signal injection details and typically in terms of the actual simulated signal events that will be used.

inject(n_inj, seed=None)#

Get some number of events.

Parameters:

n_inj (int) – number of events to inject
seed (int or numpy.random.RandomState) – seed spec

Return type:

(list of utils.Events, int)

Returns:

(event ensembles, number of pre-emptively excluded events)

class csky.inj.PointSourceBinnedTimeInjector(ana, src, flux, keep, lcs, threshs=None, lags=None, sindec_bandwidth=0.03490658503988659)[source]#

Bases: PointSourceTimeDepInjector

Inject events distributed according to a binned lightcurve.

Methods:

`__init__`(ana, src, flux, keep, lcs[, ...])	Construct a PointSourceBinnedTimeInjector.
`get_time_model`()	Get the time PDF ratio model.
`get_frac_during_livetime`()	Get the fraction of the total lightcurve covered by a given dataset.
`sample_mjd`(src_n_injs[, seed])	Get per-source `mjd` arrays.
`inject`(n_inj[, seed])	Get some number of events.

Attributes:

acc_total

Total signal acceptance.

__init__(ana, src, flux, keep, lcs, threshs=None, lags=None, sindec_bandwidth=0.03490658503988659)[source]#

Construct a PointSourceBinnedTimeInjector.

Parameters:

ana (analysis.SubAnalysis) – the sub analysis
src (utis.Sources) – the source list. required keys: ra and dec. optional keys: weight, extension
flux (hyp.Flux) – the signal spectrum
keep (list of str) – names of event features to keep
lcs (list of histlite.Hist) – the per-source lightcurves(see pdf.BinnedTimePDFRatioModel)
threshs (ndarray of float) – per-source thresholds
sindec_bandwidth (float) – width(not half-width) of the sin(dec) bands from which to draw simulated signal events

get_time_model()[source]#

Get the time PDF ratio model.

Return type:: pdf.TimePDFRatioModel

get_frac_during_livetime()[source]#

Get the fraction of the total lightcurve covered by a given dataset.

See pdf.TimePDFRatioModel.get_frac_during_livetime().

sample_mjd(src_n_injs, seed=None)[source]#

Get per-source mjd arrays.

Parameters:

src_n_injs (ndarray of int) – per-source number of events to inject
seed (int or numpy.random.RandomState) – seed spec

property acc_total#

Total signal acceptance.

This is similar to LLHEvaluatorBase.get_acc_total(), but evaluated in light of all specified signal injection details and typically in terms of the actual simulated signal events that will be used.

inject(n_inj, seed=None)#

Get some number of events.

Parameters:

n_inj (int) – number of events to inject
seed (int or numpy.random.RandomState) – seed spec

Return type:

(list of utils.Events, int)

Returns:

(event ensembles, number of pre-emptively excluded events)

class csky.inj.TransientInjector(ana, time_model, flux, keep, sindec_bandwidth=0.03490658503988659, spatial_prior=False)[source]#

Bases: PointSourceTimeDepInjector

Inject events from transient sources.

Methods:

`__init__`(ana, time_model, flux, keep[, ...])	Construct a TransientInjector.
`get_time_model`()	Get the time PDF ratio model.
`get_frac_during_livetime`()	Get the fraction of the total lightcurve covered by a given dataset.
`sample_mjd`(src_n_injs[, seed])	Get per-source `mjd` arrays.
`inject`(n_inj[, seed])	Get some number of events.

Attributes:

acc_total

Total signal acceptance.

__init__(ana, time_model, flux, keep, sindec_bandwidth=0.03490658503988659, spatial_prior=False)[source]#

Construct a TransientInjector.

Parameters:

ana (analysis.SubAnalysis) – the sub analysis
time_model (pdf.TimePDFRatioModel) – the time PDF ratio model
flux (hyp.Flux) – the signal spectrum
keep (list of str) – names of event features to keep
sindec_bandwidth (float) – width(not half-width) of the sin(dec) bands from which to draw simulated signal events
spatial_prior (bool) – option to use a spatial prior healpix map for source localisations

get_time_model()[source]#

Get the time PDF ratio model.

Return type:: pdf.TimePDFRatioModel

get_frac_during_livetime()[source]#

Get the fraction of the total lightcurve covered by a given dataset.

See pdf.TimePDFRatioModel.get_frac_during_livetime().

sample_mjd(src_n_injs, seed=None)[source]#

Get per-source mjd arrays.

Parameters:

src_n_injs (ndarray of int) – per-source number of events to inject
seed (int or numpy.random.RandomState) – seed spec

property acc_total#

Total signal acceptance.

This is similar to LLHEvaluatorBase.get_acc_total(), but evaluated in light of all specified signal injection details and typically in terms of the actual simulated signal events that will be used.

inject(n_inj, seed=None)#

Get some number of events.

Parameters:

n_inj (int) – number of events to inject
seed (int or numpy.random.RandomState) – seed spec

Return type:

(list of utils.Events, int)

Returns:

(event ensembles, number of pre-emptively excluded events)

class csky.inj.TemplateInjector(ana, template_model, keep, flux=None, sig_replace=True)[source]#

Bases: SigInjector

Inject a highly-extended source according to a spatial template.

This class implements injection according to an all-sky source template(such as for the Galactic “plane”). If per-pixel energy-binned spectra are available then they are used, in line with the principle that “you can do whatever you want in your likelihood but you’d better use everything you’ve got for signal injection”, despite the fact that this is relatively slow computationally.

Methods:

`__init__`(ana, template_model, keep[, flux, ...])	Construct a TemplateInjector.
`set_flux`([flux])	Sets the weight of the injector according to flux.
`inject`(n_inj[, seed])	Get some number of events.

Attributes:

acc_total

Total signal acceptance.

__init__(ana, template_model, keep, flux=None, sig_replace=True)[source]#

Construct a TemplateInjector.

Parameters:

ana (analysis.SubAnalysis) – the sub analysis
template_model (pdf.TemplateSpacePDFRatioModel) – the template space PDF ratio model
keep (list of str) – names of event features to keep
flux (hyp.Flux) – if given, the signal spectrum. otherwise, inject according to per-pixel spectra if available, or use template_model.flux
sig_replace (bool) – If true, sampling with replacement will be used, means an element can be reused multiple times.

set_flux(flux=None)[source]#

Sets the weight of the injector according to flux.

Parameters:: flux (None or hyp.Flux) – If given, the signal spectrum. Otherwise, inject according to per-pixel spectra if available, or use template_model.flux.

property acc_total#

Total signal acceptance.

This is similar to LLHEvaluatorBase.get_acc_total(), but evaluated in light of all specified signal injection details and typically in terms of the actual simulated signal events that will be used.

inject(n_inj, seed=None)[source]#

Get some number of events.

Parameters:

n_inj (int) – number of events to inject
seed (int or numpy.random.RandomState) – seed spec

Return type:

(list of utils.Events, int)

Returns:

(event ensembles, number of pre-emptively excluded events)

class csky.inj.TemplateBGInjector(ana, template_model, keep, bg_weight_names, flux=None, sig_replace=True, randomizers=None, mcbg=False)[source]#

Bases: Injector

Inject typical types of background along with a highly-extended source according to a spatial template.

This class implements addition injection to the typical background (scrambled or MC) according to an all-sky source template(such as for the Galactic “plane”). If per-pixel energy-binned spectra are available then they are used.

Methods:

`__init__`(ana, template_model, keep, ...[, ...])	Construct a TemplateInjector.
`inject`(gp_norm[, n_inj, seed, replace, ...])	Get some number of events.

__init__(ana, template_model, keep, bg_weight_names, flux=None, sig_replace=True, randomizers=None, mcbg=False)[source]#

Construct a TemplateInjector.

Parameters:

ana (analysis.SubAnalysis) – the sub analysis
template_model (pdf.TemplateSpacePDFRatioModel) – the template space PDF ratio model
keep (list of str) – names of event features to keep
flux (hyp.Flux) – if given, the signal spectrum. otherwise, inject according to per-pixel spectra if available, or use template_model.flux
sig_replace (bool) – If true, sampling with replacement will be used, means an element can be reused multiple times.

inject(gp_norm, n_inj=None, seed=None, replace=False, truth=False, debug=False)[source]#

Get some number of events.

Parameters:

n_inj (int) – number of events to inject
seed (int or numpy.random.RandomState) – seed spec

Return type:

(list of utils.Events, int)

Returns:

(event ensembles, number of pre-emptively excluded events)

class csky.inj.SpatialPriorInjector(ana, src, flux, keep, hp_idx, sindec_bandwidth=0.03490658503988659)[source]#

Bases: SigInjector

Injection of one or more point-like sources, whose position is not exactly known, but given in the form of a spatial prior (healpix map).

Methods:

`__init__`(ana, src, flux, keep, hp_idx[, ...])	Construct a SpatialPriorInjector.
`inject`(n_inj[, seed, ra, dec])	Get some number of events.

Attributes:

acc_total

Total signal acceptance.

__init__(ana, src, flux, keep, hp_idx, sindec_bandwidth=0.03490658503988659)[source]#

Construct a SpatialPriorInjector.

Parameters:

ana (analysis.SubAnalysis) – the sub analysis
src (utis.Sources) – the source list. required keys: ra, dec, prior. optional keys: weight, extension
flux (hyp.Flux) – the signal spectrum
keep (list of str) – names of event features to keep

property acc_total#

Total signal acceptance.

This is similar to LLHEvaluatorBase.get_acc_total(), but evaluated in light of all specified signal injection details and typically in terms of the actual simulated signal events that will be used.

inject(n_inj, seed=None, ra=None, dec=None)[source]#

Get some number of events.

Parameters:

n_inj (int) – number of events to inject
seed (int or numpy.random.RandomState) – seed spec

Return type:

(list of utils.Events, int)

Returns:

(event ensembles, number of pre-emptively excluded events)