utils

Utility classes and functions.

Classes:

Arrays([init, names, convert, _require_array])	Optimized DataFrame-like data structure.
Events(*a, **kw)	Subclass of Arrays automatically providing certain event properties.
Sources(*a, **kw)	Subclass of Arrays automatically providing certain source properties.

Functions:

sources(ra, dec, **kw)	Convenience wrapper for constructing Sources instances.
ensure_dir(dirname)	Make sure dirname exists and is a directory.
get_pixval(map, ra, dec)	Get the value of a healpix map at specific equatorial coordinates.
get_random([seed])	Get numpy RandomState.
get_pixmask(nside, events[, radius])	Query disc of given radius around selected events.
union_continuous_intervals(intervals)	Calculate the union of a given list of continuous intervals
intersection_time_intervals(intervals_1, ...)	Calculate intersections between two sorted lists containing continuous, non-overlapping intervals
get_frac_during_livetime(ana, t0_arr, dt_arr)	Calculate the fraction of the flare covered by the datasets in the analysis.

class csky.utils.Arrays(init={}, names=None, convert=False, _require_array=True, **kw)

Bases: object

Optimized DataFrame-like data structure.

This is the baseline data structure for all event data in csky. It acts a lot like a pandas DataFrame, and can be converted to one with the .as_dataframe property. Conversion to astropy Table and to numpy structured array are supported by the .as_table and .as_array properties.

Each stored array is treated as a column and can be accessed like, e.g., data['ra'] or data.ra. Assignment of new columns is only available by the [] syntax, e.g. data['something_else'] = some_new_array.

Additional dictionary-like access is possible through the .keys(), .values(), and .items() methods.

When the [] operand is not a string, slicing/masking is performed, e.g. src_0_1_2 = srcs[:3] or north_data = data[data.dec > 0]. Iteration over an Arrays yields per-row instances, that is, new Arrays instances with column lengths of 1.

This class is easier than DataFrames to use for computationally-intense work because it does very little to impose and maintain column alignment. This means it can expose direct references to the underlying numpy arrays rather than routing through some kind of Series objects.

Methods:

__init__([init, names, convert, _require_array])

Construct an Arrays collection.

__init__(init={}, names=None, convert=False, _require_array=True, **kw)

Construct an Arrays collection.

Parameters:

• init (numpy.ndarray or object with keys() or ._dict.keys() method) – the data

• names (list of str) – the column names

• convert (bool) – if True, add references converting from skylab to csky naming convention

class csky.utils.Events(*a, **kw)

Bases: Arrays

Subclass of Arrays automatically providing certain event properties.

Bonus properties include sindec, log10energy, ra_deg, dec_deg, sigma_deg, and (for MC where true values are known) dpsi_deg.

Methods:

__init__(*a, **kw)

Construct an Arrays collection.

__init__(*a, **kw)

Construct an Arrays collection.

Parameters:

• init (numpy.ndarray or object with keys() or ._dict.keys() method) – the data

• names (list of str) – the column names

• convert (bool) – if True, add references converting from skylab to csky naming convention

class csky.utils.Sources(*a, **kw)

Bases: Arrays

Subclass of Arrays automatically providing certain source properties.

Bonus properties include weight (normalization: sum to unity) and extension (zero by default). If deg=True on construction, then (ra,dec,extension) are converted from degrees to radians.

Methods:

__init__(*a, **kw)

Construct an Arrays collection.

__init__(*a, **kw)

Construct an Arrays collection.

Parameters:

• init (numpy.ndarray or object with keys() or ._dict.keys() method) – the data

• names (list of str) – the column names

• convert (bool) – if True, add references converting from skylab to csky naming convention

csky.utils.sources(ra, dec, **kw)

Convenience wrapper for constructing Sources instances.

csky.utils.ensure_dir(dirname)

Make sure dirname exists and is a directory.

csky.utils.get_pixval(map, ra, dec)

Get the value of a healpix map at specific equatorial coordinates.

Parameters:

• map (ndarray) – the healpix map

• ra (float or ndarray) – the right ascension(s)

• dec (float or ndarray) – the declination(s)

Returns:

the value(s)

Return type:

float or ndarray

csky.utils.get_random(seed=None)

Get numpy RandomState.

csky.utils.get_pixmask(nside, events, radius=3)

Query disc of given radius around selected events.

Parameters:

• events (np.ndarray) – Array of data events

• nside (int) – Resolution of the healpix map to use

• radius (float) – Radius around each event which is used to select pixels

Returns:

list of pixels within ‘radius’ of the data events

Return type:

src_pix (np.ndarray)

csky.utils.union_continuous_intervals(intervals)

Calculate the union of a given list of continuous intervals

csky.utils.intersection_time_intervals(intervals_1, intervals_2)

Calculate intersections between two sorted lists containing continuous, non-overlapping intervals

csky.utils.get_frac_during_livetime(ana, t0_arr, dt_arr, cut_n_sigma=5, box_mode=None)

Calculate the fraction of the flare covered by the datasets in the analysis.

Parameters:

• ana (csky.analysis.Analysis) – The analysis object containing any subanalyses and GRLs

• t0_arr (array-like) – An array of the t0 values from each source.

• dt_arr (array-like) – An array of the dt values from each source.

• cut_n_sigma (float) – The number of sigma to use for the calculation bounds when using a Gaussian flare. Value is ignored for box/tophat flares. Default is 5.

• box_mode (str) – If we’re using a box/tophat distribution, this contains a switch defining the times. Default is None (ie, Gaussian flare). Options are - ‘pre’: Time window is [t0-dt, t0] - ‘center’: Time window is [t0-dt/2, t0+dt/2] - Anything else: Time window is [t0, t0+dt]

Returns:

The fraction of each flare covered by the analysis GRLs.

Return type:

fractions (np.array<float>)