BurstCube Documentation Documentation

BurstCube DocumentationDocumentation

Release 1.0.0

Noah Kasmanoff

Jan 21, 2022

Contents

1 Introduction 11.1 Getting Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11.2 Documentation Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

Python Module Index 57

Index 59

i

CHAPTER 1

Introduction

This is the BurstCube’s documentation page. For more information about the misson, please refer to the BurstCubeWebsite.

BurstCube’s documentation is built with a series of different functions and modules that allow the following:

• Creating different geometry files to allow for new arrangements of BurstCube to be subject to testing.

• Creating source files of ranging sky locations and energies.

• Quick manipulation of the MEGAlib Cosima function to permit quick simulations.

• Packages such as bcSim and plotSim that grant fast and effective data processing.

BurstCube uses a configuration-file driven workflow in which the analysis parameters (data selection, IRFs, and ROImodel) are defined in a YAML configuration file. Analysis is executed through a python script.

1.1 Getting Help

If you have questions about using this please open a GitLab Issue

1.2 Documentation Contents

1.2.1 Installation

Install the code via

$ python setup.py install --user

1

https://asd.gsfc.nasa.gov/burstcube/

https://asd.gsfc.nasa.gov/burstcube/

https://gitlab.com/groups/burstcube/-/issues

BurstCube Documentation Documentation, Release 1.0.0

Requirements

• MEGAlib

• gbm-data-tools (not yet public, will be released soon)

• ephem

• numpy

• pytest

• PyYAML

See ci.Dockerfile for an example on how to install them.

Docker

Docker containers are available at https://hub.docker.com/u/burstcube

1.2.2 Tutorials

Tutorial for various components of the bc-tools library. These are Python notebooks that you can execute interactively.

Create and inspect a detector response for one burst

A detector response matrix codifies two sets of quantities:

1. The effective area as a function of energy. That is, the equivalent collection area a perfect detector would havethat will result in the same number of counts for a given flux.

2. The probability of a photon of energy 𝐸 to be assigned to a channel energy 𝐸′

These allow us to reconstruct physical quantities —e.g. spectrum and localization— out of simple counts.

The detector response matrix is then a 2D matrix of “real” photon energy versus assigned channel energy. Each entryis the effective area of the corresponding photon energy bin, times the fraction of events in the photon energy bin thatland in the corresponding channel energy.

This matrix is generated based on particle-by-particle simulations using the app bc-rsp. The basic usage is

$ bc-rsp config_file working_dir --ntriggers NTRIGGERS --direction ZENITH AZIMUTH

You can see other optional arguments by using the --help flag or by looking at the “Scripts” documentation.

The config_file argument is the path to the YAML configuration file. An example is provided with this library.You can find the path to it either using the following command line executable:

$ bc-config-example-path

or using the API:

[1]: from BurstCube.config import Configurator

Configurator.config_example_path()

[1]: PosixPath('/Users/imartin5/BurstCube/software/bc-tools/BurstCube/config/bc_config.yaml→˓')

2 Chapter 1. Introduction

https://hub.docker.com/u/burstcube


bc-rsp uses the parameters in the simulations and detector section of the config file. Worth mentioning arethe parameters from simulations:detector_effects. These codify the results from calibration and indicateshow to simulate effects from a realistic detector, such as energy resolution and efficiency.

The final output of bc-rsp is a GBM RSP file for each detector. There are also complementary files with the suffix_peak.rsp, which corresponse to the detector response including only events from the photopeak, that is, thosephotons which deposited all of their energy in a given detector.

You can open these files directly using the gbm library, e.g.

[2]: from gbm.data import RSP

# Test dataimport BurstCube.data as data

# Response from zenith (of the whole instrument, not a single detector)rsp = RSP.open(data.path / "sims/SQD0_zenith.rsp")rsp_peak = RSP.open(data.path / "sims/SQD0_zenith_peak.rsp")

you can then plot it

[3]: from gbm.plot import ResponseMatrix

rsp_plot = ResponseMatrix()rsp_plot.set_response(rsp, color="plasma")

The projection onto the x-axis is the effective area

[4]: from gbm.plot import PhotonEffectiveArea

import matplotlib.pyplot as plt

(continues on next page)

1.2. Documentation Contents 3


(continued from previous page)

fig,ax = plt.subplots(dpi=150)

effarea_energy = PhotonEffectiveArea(data=rsp, axis=ax)effarea_energy._data.color = 'orange' #Workaround

effarea_energy_peak = PhotonEffectiveArea(data=rsp_peak, axis=ax)

ax.legend([effarea_energy._data._artists[0],effarea_energy_peak._data._artists[0]],[→˓"Total", "Photopeak"]); #Workaround

<Figure size 770x470 with 0 Axes>

<Figure size 770x470 with 0 Axes>

This is the typical reponse for a gamma-ray detector using scintillator, such as BurstCube, GBM or BATSE. At lowenergies there is a cutoff since the photons are not energetic enough to reach the scintillator and get a measurement.At high energies, pair-production dominates the total effective area. Although the gamma-rays do interact with thedetector and produce a count, only a small fraction of the energiy is deposited. This cutoff can be seen in photopeakresponse, where we only considered those events that were fully absorbed due to either the photoelectric effect or incombination with other effects such as Compton scattering.

Having the full detector response allows us to account for the energy resolution and contamination by these partially-absorbed events. In practice, GRBs and other sources typically have a falling spectrum with an index of & −1.5, sosimulating up to ~10 MeV is sufficient.

You can also open an .rsp file directly using the bc-tools library:

[5]: from BurstCube.sims import DRM

drm = DRM.from_gbm_rsp_file(data.path / "sims/SQD0_zenith.rsp")



[6]: import matplotlib.pyplot as plt

Note that you can go back and forth between GBM’s RSP and the native DRM with DRM.from_rsp() and DRM.to_rsp().

As an example on how to use a DRM let’s plot the expected measured counts per second from a monoenergetic source.Say our source is 137Cs (peak energy at 662 keV), has an activity of 1 𝜇Ci and is located at 1 m from the center of thedetector.

[7]: # We used the BurstCube's units module to keep track of units.# These are just constants, with the value of 1 assigned to base units (keV, s, cm).from BurstCube.util import units as u

energy = 662 * u.keVactivity = 3.7e4 / u.s # 1 uCidistance = 1 * u.meterflux = activity / (4*u.pi*distance**2) # Photons per area

# drm.energy_channels gives you an Axis object describing the binning of the energy→˓channels# from which you can get the centers, edges, lower_bounds, upper_bounds, or the→˓number of channels (nbins)energy_channels = drm.energy_channels

# We can get the total expected counts using:tot_rate = flux * drm.effective_area(energy)

print("Total rate = {:.2} Hz".format(tot_rate * u.s))

# However, due to a finite energy resolution and other instrumental effects, there is→˓an energy spreadchannel_rate = flux * drm.channel_effective_area(energy, range(energy_channels.nbins))

# Plot itfig,ax = plt.subplots(dpi=150)

ax.plot(energy_channels.lower_bounds,channel_rate,drawstyle = 'steps-post')

ax.set_xscale('log')

ax.set_ylabel("Expected count rates [Hz]")ax.set_xlabel("Channel energy [MeV]");

Total rate = 9.2 Hz



In this case we assumed that the source is sufficiently far away to model it with a detector response with a sourceat infinity (the default). Furthermore, this assumes that there are no nearby sources of scattering or attenuation.An improvement of this would be to generate a detector response with the command line option --distance inbc-rsp. This would mimic more accurately, for example, what happens during calibration.

Working with a full instrument response

In the last tutorial we saw how to use an RSP file, which contains the response for a single detector and a singlecoordinate. If you don’t provide bc-rsp with the --direction flag, it will generate an HDF5 file containningthe detector response matrices (DRMs) for all detectors and multiple directions covering the full sky (in a HEALPixgrid). If you want to use the GBM software, a convenient way to get an RSP file from a full DRM is to use the scriptbc-rsp-extractor.

You can also get information directy from the DRM. The class to access this file is BurstCube.io.DRM. For exam-ple, let’s get the effective area at 100 keV as a function of the angle with respect to to the normal of the first SingleQuarter Detector:

[1]: import BurstCube.data as datafrom BurstCube.io import InstrumentResponsefrom BurstCube.util.coords import SpacecraftCoordsimport BurstCube.util.units as u

import matplotlib.pyplot as pltimport numpy as np

theta = np.linspace(0,360, 360)*u.deg(continues on next page)




energy = 100 * u.keV

# The best way to work with them is to use them as context manager# The alternative to using context manager is to remember to call close() when you→˓are done with the file.with InstrumentResponse(data.path/'sims/drm.h5') as irf:

# You can get a list of the detector IDsprint("Detectors: {}".format(irf.detectors))

# SQD0 zenith is pointing at 45d,45d in the spacecraft coordinateseff_area = []

for angle in theta:

coords = SpacecraftCoords(45*u.deg + angle, 45*u.deg)

drm = irf.get_drm("SQD0", coords = coords)

eff_area += [drm.effective_area(energy)]

fig,ax = plt.subplots()

ax.plot(theta/u.deg, eff_area);

ax.set_xlim(0,360)

ax.set_xlabel("SQD0 zenith angle [deg]")ax.set_ylabel("Effective area [cm$^2$]");

Detectors: ['SQD0', 'SQD1', 'SQD2', 'SQD3']

The effective area is not symmetric around 180∘ because the shadowing effect from the other simulated componentsis taken into account.

This plot is not very smooth because the underlying DRM used for this example has low resolution. You can see thiswith



[2]: with InstrumentResponse(data.path/'sims/drm.h5') as irf:

nside = irf.nside

print("Underlying HEALPix NSIDE = {}".format(nside))print("This means only {} directions were simulated".format(12*nside*nside))

Underlying HEALPix NSIDE = 2This means only 48 directions were simulated

Localization

In this tutorial we’ll estimate the localization of a source based on a classical maximum likelihood estimate (MLE)method.

The key class is TSMap which generates a test statistics map based on one or more objects of the LocLike class.All derived classes of LocLike provide the likelihood for a given coordinate through the get_log_like method.This allows multiple instruments to participate in a joint fit by creating an appropiate LocLike subclass.

For this example we’ll use the simple NormLocLike subclass, which defines the Poisson likelihood for a photon-counting experiment as

logℒ(𝑁) =∑︁𝑖

log𝑃 (𝜆 = 𝑏𝑖 + 𝑁𝑒𝑖; 𝑑𝑖) =∑︁𝑖

log𝜆𝑑𝑖𝑒𝜆

𝑑𝑖!,

where

• 𝑑𝑖 are the set of counts detected by each detector

• 𝑏𝑖 are the estimated background counts

• 𝑒𝑖 are the estimated excess counts for a given hypothesis

• 𝑁 , the only free parameter, is the overall normalization.

We proceed to use a full instrument response file to compute the estimated excess counts e_i based on a fiducial 1sburst with an index -2 power law spectrum:

[3]: import BurstCube.data as datafrom BurstCube.io import InstrumentResponsefrom BurstCube.loc import LocalLocTablefrom BurstCube.spectra.spectrum import PowerLaw

# Convolve an full instrument response with a hypothetical spectrumirf_path = data.path/'sims/drm.h5'

with InstrumentResponse(irf_path) as irf:

# Hypothetical spectrum# This normalization corresponds to 1 ph/cm2/s between 50-300 keVspectrum = PowerLaw(60, 2)

# In this case we integrate the rate from all energy channels.# You can subdivide the data into multiple energy channel groupslocal_loctable = LocalLocTable.from_irf(irf, spectrum)

# The local_loctable contains the expected rates in spacecraft coordinates# We now need to use this to estimate the total expected counts in sky coordinate for





# the full duration of an event.# In this case we simply have a 1 second event and specifying the attitude by a→˓quaternion# ([0,0,0,1] corresponds to the identity rotation). You can have multiple attitude-→˓duration# pairs to correctly model long duration events.sky_loctable = local_loctable.to_skyloctable(attitude = [0,0,0,1], duration = 1)

Here’s how the look-up tables in norm_likelihood look. Note that we’re using a low-resolution instrument re-sponse. Although these tables are bilinearly interpolated, you typically need a resolution comparable to the localizationuncertainty you expect.

[2]: print(f"Look-up tables: {sky_loctable.labels}")

sky_loctable.get_expectation_map('SQD0').plot();

Look-up tables: ['SQD0' 'SQD1' 'SQD2' 'SQD3']

Now that we have the expected excessthe remaining ingredients are the actual measured counts and their correspondingestimated background counts. For real event these come from data. In this case we’ll simulate a background rate of 1kHz per detector and a source of 2 ph/cm2/s at (RA = 60deg, Dec = 45deg)

[4]: from astropy.coordinates import SkyCoordimport astropy.units as u

# 1 kHz per detector (we're simulating a 1s burst)bkg = [1000, 1000, 1000, 1000]sky_loctable.set_background(bkg)





# Injected source locationcoord = SkyCoord(ra = 60*u.deg, dec = 45*u.deg)

# 2 ph/cm2/s between 50-300 keV (our hypothetital source was 1 ph/cm2/s)signal = 2*sky_loctable.get_expectation(coord)

sky_loctable.set_data(bkg + signal)

With all the ingredients in place, we can now compute a test-statistics map:

[5]: from BurstCube.loc import TSMap, NormLocLike

# NormLocLike is a subclass of LocLike and computes# a Poisson likelihood for counting instruments. The# overall normalization is the only free parameternorm_likelihood = NormLocLike(sky_loctable)

# Define a map of nside = 32. Note that this is a finer resolution# that the underlying look-up table, which will be interpolatedts = TSMap(nside = 32)

# Compute the TS map from one or more LocLikelihoodts.compute(norm_likelihood)

These are the results:

[6]: import numpy as npprint(f"Maximum sqrt(TS) = {np.sqrt(np.max(ts)):.2f}")print(f"Best estimate: RA = {ts.best_loc().ra:.2f} Dec= {ts.best_loc().dec:.2f}")print(f"Error area (90% cont.): {ts.error_area(cont = .9).to(u.deg**2):.2f}")print(f"Equivalent error radius (90% cont.): {np.sqrt(ts.error_area(cont = .9)/np.pi).→˓to(u.deg):.2f}")

img,ax = ts.plot()ax.grid(alpha = .5)

# Actual location of simulated sourceax.scatter(coord.ra.to(u.deg).value, coord.dec.to(u.deg).value,

color = 'red', transform = ax.get_transform('world'), s = 2);

Maximum sqrt(TS) = 12.55Best estimate: RA = 61.50 deg Dec= 44.99 degError area (90% cont.): 1937.09 deg2Equivalent error radius (90% cont.): 24.83 deg



[ ]:

1.2.3 Scripts

The scripts are easy ways to call certain functions of the library from the command line. While you could perform thesame tasks using Python code, it is usually easier to just call an executable that is in your path.

Most of the parameters needed by the scripts are defined in a yaml configuration file. An exam-ple of this file comes with bc-tools, within the config module. You can get the path to it either us-ing BurstCube.config.Configurator.config_example_path() or from the command line callingbc-config-example-path. Sometime though it is impractical to change the configuration file for every run.In these situations you can override any parameter using the --override command-line option, which accepts pairskeys and values, separated by ‘=’. For example:

$ bc-script --override parameter1=5 'group:subgroup:parameter2 = ["example", 5, True]'

is equivalent to have a configuration file with:

parameter1: 5

group:subgroup:parameter2: ["example", 5, True]

Note that the groups/subgroups are separated by :, and that you need to use quotes such that each overriding statementis passed as single argument to the exceutable (spaces are trimmed). The value will by parsed by yaml in the samewas as if it were in the configuration file.



The following is an overview of the available scripts. Use -h/--help for more details and other options.

bc-config-example-path

Prints the path in your system to the BurstCube configuration file example. e.g.:

$ bc-config-example-path/path/to/bc-tools/BurstCube/config/bc_config.yaml

This is an entry point for BurstCube.config.Configurator.config_example_path()

bc-rsp

Generate BurstCube detector reponse files.

Basic usage:

bc-rsp config_file working_dir --ntriggers NTRIGGERS

where NTRIGGERS is the stopping conditions, the number of thrown events that resulted in an interaction with asensitive component (per simulated direction).

By default, it generates an HDF5 file containing the detector response matrices for multiple directions, specifically thecenter of the pixels in a HEALPix grid (the pixelization is controlled by simulations:nside). This can then be openedby BurstCube.io.DRM which can interpolate in between to obtain a full 4pi response. The user can specify a specificdirection to simulate with –direction, in which case a GBM RSP will be output for each detector.

The program performs the following steps for each simulated directions:

1. Creates a working directory.

2. Generates a Cosima .source file.

3. Runs Cosima, resulting in a .sim file.

4. Using this output, it generates a detector response matrix which is saved as GBM RSP files. There is one foreach detector labeled detector_id.rsp. The file called detector_id_photopeak.rsp includes onlythe events corresponding to the photopeak.

If --direction was not set, then at the end all detector response matrices are combined in working_dir/drm[_peak].h5.

If the program detects that the subproduct of any of these steps already exists in the working directory, the step isskipped.

Warning: If a subproduct is already available, the configurations parameters or command-line arguments neededfor the step will be ignored. For example, if the Cosima mc.source file already exists, it will be used withoutchecking that the spectrum corresponds to the one input by the user during the current run.

Generating a full detector response can be CPU intensive. There are two ways to parallelize and speed this process:

1. Using --nthreads N: the program launches a subprocess for each pixel, where N is the maximum subpro-cesses running at a given time

2. Using --part PART NPARTS: in this case, the program will divide the number of pixels into NPARTSnumber of jobs, and will only run number PART (zero indexed). Note that in this case the DRMs will not becombined into a single HDF5 at the end. A separate job without this flag needs to be run at the end.



Both ways can be combined.

Note: You need to have MEGAlib installed and loaded.

This is an entry point for the BurstCube.sims.rsp_gen module.

bc-rsp-extractor

For convenience, when you generate a full detector response with bc-rsp, you can extract a particular direction withbc-rsp-extractor.

Basic usage:

bc-rsp-extractor input_hdf5 --spacecraft_coords RA(deg) DEC(deg)

This will output a .rsp file per detector, prefixed with the detector name.

1.2.4 API

Input/Output

Cosima

CosimaSim

class BurstCube.io.CosimaSimBases: object

Contains info associated with a Cosima output file (.sim)

Attributes

• tstart (float) – Start of simulated time

• tstop (float) – Stop of simulated time

• nthrown (int) – Total number of simulated particles

• ntriggers (int) – Total number of triggered events

• events (list of SimEvent) – Collection of all events, which contain hits. These might notbe loaded

static event_iter(filename, detector)Loops through the event section in a .sim file and yields a SimEvent object for each one. This avoidsloading a large file into memory. e.g.:

for hit in CosimaSim.event_iter("/path/to/file.sim", detector):

do_something(hit)

Parameters

• filename (Path) – Path to .sim file.

• detector (BurstCube.containers.Detector) – Detector locations/names


http://megalibtoolkit.com/


Returns Yields SimEvent objects

merge(sim2, shift=0)Combine CosimaSim object with a shift. Hits will be time sorted

Parameters

• sim2 (CosimaSim) – Hits to be merged

• shift (float, optional) – Apply a time shift to obj2

classmethod open(filename, detector=None, load_events=True)

Parameters

• filename (Path) – Path to .sim file.

• detector_dict (dict) – Convert from a string of x,y location to a given detector ID.Use x and y value exactly as they appear in the input file

• detector (BurstCube.containers.Detector) – Detector with loca-tions/names. Only needed if loading events

• load_events (bool) – If false, only load the header information of the file but do notstore the events

Returns CosimaSim object

Warning: Concatenating files with NF and IN keywords is not supported

time_shift(shift)Shift time of events

Parameters shift (float) – duration of shift

to_TTE(energy_channel_edges, *args, **kwargs)Convert the hits into a mocked Time-Tagged Event object

Parameters

• energy_channel_edges (list) – Energy channel definition for discreatization

• *args – passed to TTE.from_data()

• **kwargs – passed to TTE.from_data()

Returns One TTE for each detector

Return type list of gbm.data.phaii.TTE

CosimaSource

class BurstCube.io.CosimaSource(geometry=None, ntriggers=None)Bases: object

Class to read/write .source Cosima files

Parameters

• geometry (Path) – Path to Geomega geometry file

• ntriggers (int) – Stop simulation when this number of triggers was reached



Note: Besides the parameters initialized during consutruction, note that ou still need to call set_point_source

Attributes

• avail_spec_help (str) – List of available spectral shapes

• spectrum (Spectrum) – Parsed Cosima spectrum and flux

• geometry (Path) – Path to Geomega geometry file

• ntriggers (str) – Stop simulation when this number of triggers was reached

• location (SpacecraftCoords) – Source location. Distance might be infinity

• source_path (Path) – Path to .source Cosima file

• sim_path (Path) – Path to Cosima’s results .sim file

Warning: Reading general .source files not written by this class is not guaranteed to work

classmethod open(source_path)Read file from disk

Parameters source_path (Path) – Path to .source file

Warning: Reading general .source files not written by this class is not guaranteed to work

run(log_path=None, seed=None)Run the simulations

Parameters

• log_path (Path) – Path to output Cosima log. To stdout by default.

• seed (int or None) – Random seed for Cosima (must be > 0). Use None

• a "random" random seed. (for) –

set_point_source(spectrum, location)Indicate that a point source will be simulated

Parameters

• spectrum (Spectrum) – Spectrum to simulate

• location (SpacecraftCoords) – Source location

write(source_path, sim_path)Write file

Parameters

• source_path (Path) – .source file output path

• sim_path (Path) – .sim file output path prefix when this .source file is run..inc1.id1.sim will be appended, .inc2.id1.sim if it already exists, and so on.



Note: sim_path is relative to the current directory, not to source_path

Instrument Response File

class BurstCube.io.InstrumentResponse(filename, nside=None, scheme=’ring’)Bases: mhealpy.containers.healpix_base.HealpixBase

Input/output access of HDF5 files containing Detector Response Matrices (DRMs) for all detectors and multiplepoints in the sky.

There is one DRM (photon energy vs energy channel) per detector per pixel in a HEALPix grid.

Please be aware that you need to call close() when you are done. Or even better, use it as a context manager,e.g.:

with InstrumentResponse("irf.h5") as irf:

coord = SpacecraftCoords(0, 0)

drm = irf.get_drm("detector1", coords = coord)

# Do something with drm

This automatically closes the file, even if an exception occurred.

Parameters

• filename (Path) – Path to HDF5 containing DRMs

• nside (int or None) – It not None, a new file will be created with this Healpix nside.

• scheme (str) – RING or NESTED Healpix ordering scheme

classmethod adaptive_moc_mesh(max_nside, split_fun)Return a MOC mesh with an adaptive resolution determined by an arbitrary function.

Parameters

• max_nside (int) – Maximum HEALPix nside to consider

• split_fun (function) – This method should return True if a pixel

• be split into pixel of a higher order, and False otherwise.(should) –

• takes two integers, start (It) –

• correspond to a single pixel in nested rangeset format fora (which) –

• of nside max_nside. (map) –

Returns HealpixBase

ang2pix(theta, phi)Get the pixel (as used in []) that contains a given coordinate

Parameters

• theta (float or array) – Zenith angle

• phi (float or arrray) – Azimuth angle



Returns int or array

boundaries(pix, step=1)Returns an array containing vectors to the boundary of the nominated pixel.

The returned array has shape (3, 4*step), the elements of which are the x,y,z positions on the unit sphereof the pixel boundary. In order to get vector positions for just the corners, specify step=1.

close()Close the HDF5 file containing the DRMs

conformable(other)For single-resolution maps, return True if both maps have the same nside and scheme.

For MOC maps, return True if both maps have the same list of UNIQ pixels (including the ordering)

detectorsList of detector IDs

energy_channels(detector)Returns the axis corresponding to the energy channels

Parameters detector (str) – Detector ID

Returns Labeled ‘channels’

Return type Axis

filenamePath to on-disk file containing DRMs

Returns Path

classmethod from_rsps(rsp_dict, filename, scheme=’ring’)Create an InstrumentResponse from a list of GBM RSP files

Parameters

• rsp_dict (dict of list of RSP) – Lists of .rsp files, one list per detector. Usedetector name as dict key. The lists contain one entry per pixel in a HEALPix grid.

• filename (Path) – Path to HDF5 output file to store the DRM

• nest (bool) – True for NESTED scheme. False for RING

get_all_neighbours(theta, phi=None)Return the 8 nearest pixels. For MOC maps, these might repeat, as this is equivalent to raterizing the mapsto the highest order, getting the neighbohrs, and then finding the pixels tha contain them.

Parameters

• theta (float or int or array) – Zenith angle (rad). If phi is None, these areassummed to be pixels numbers. For MOC maps, these are assumed to be pixel numbersin NESTED scheme for the equivalent single-resolution map of the highest order.

• phi (float or array or None) – Azimuth angle (rad)

Returns

pixel number of the SW, W, NW, N, NE, E, SE and S neighbours, shape is (8,) if input isscalar, otherwise shape is (8, N) if input is of length N. If a neighbor does not exist (it canbe the case for W, N, E and S) the corresponding pixel number will be -1.

Return type array



get_drm(detector, pix=None, coords=None, interp=True)Return a single DRM (2D) corresponding to the input pixel or coordinate.

If interp is true, the output will be a bilinear interpolation from the 4 closest pixels to the coordinate.Otherwise, the center of the pixel the input coordinate corresponds to will be used.

Parameters

• detector (str) – Detector ID

• pix (int) – HEALPix pixel

• coords (SpacecraftCoords) – Local coordinate

• interp (bool) – whether or not to interpolate

Returns

Photon energies axis is called “energy”, energy channels axis is called “channels”

Return type Histogram

get_interp_weights(theta, phi)Return the 4 closest pixels on the two rings above and below the location and corresponding weights.Weights are provided for bilinear interpolation along latitude and longitude

Parameters

• theta (float or array) – Zenith angle (rad)

• phi (float or array) – Azimuth angle (rad)

Returns

(pixels, weights), each with of (4,) if the input is scalar, if (4,N) where N is size of thetaand phi. For MOC maps, these pixel numbers might repeate.

Return type tuple

is_mesh_valid()Return True is the map pixelization is valid. For single resolution this simply checks that the size is avalid NSIDE value. For MOC maps, it checks that every point in the sphere is covered by one and onlyone pixel.

Returns True

is_mocReturn true if this is a Multi-Dimensional Coverage (MOC) map (multi-resolution)

Returns bool

is_nestedReturn true if scheme is NESTED or NUNIQ

Return bool

is_ringReturn true if scheme is RING

Return bool

classmethod moc_from_pixels(nside, pixels, nest=False)Return a MOC mesh where a list of pixels are kept at a given nside, and every other pixel is appropiatelydownsampled.

Also see the more generic adaptive_moc() and adaptive_moc_mesh().



Parameters

• nside (int) – Maximum healpix NSIDE (that is, the NSIDE for the pixel list)

• pixels (array) – Pixels that must be kept at the finest pixelation

• nest (bool) – Whether the pixels are a ‘NESTED’ or ‘RING’ scheme

moc_sort()Sort the uniq pixels composing a MOC map based on its rangeset representation

nest2pix(pix)Get the corresponding pixel in the current grid for a pixel in NESTED scheme. For MOC map, return thepixel that contains it.

Parameters pix (int or array) – Pixel number in NESTED scheme. Must correspond toa map of the same order as the current.


npixGet number of pixels.

For multi-resolutions maps, this corresponds to the number of utilized UNIQ pixels.

Returns int

nsideGet map NSIDE

Returns int

orderGet map order

Returns int

photon_energies(detector)Returns the axis corresponding to the MC truth photon energies.

Parameters detector (str) – Detector ID

Returns Labeled ‘energy’

Return type Axis

pix2ang(pix)Return the coordinates of the center of a pixel

Parameters pix (int or array) –

Returns (float or array, float or array)

pix2range(nside, pix)Get the equivalent range of child pixels in nested scheme for a map of equal or higher nside

Parameters

• nside (int) – Nside of output range sets

• pix (int or array) – Pixel numbers

Returns

Start pixel (inclusive) and stop pixel (exclusive)

Return type (int or array, int or array)



pix2uniq(pix)Get the UNIQ representation of a given pixel index.

Parameters pix (int) – Pixel number in the current scheme (as used for [])

pix2vec(pix)Return a vector corresponding to the center of a pixel

Parameters pix (int or array) –

Returns Size (3,N)

Return type array

pix_order_list()Get a list of lists containing all pixels sorted by order

Returns

(pix_per_order, nest_pix_per_order) Each list has a size equal to the map order.Each element is a list of all pixels whose order matches the index of the list position. Thefirst output contains the index of the pixels, while the second contains their corespondingpixel number in a nested scheme.

Return type (list, list)

pix_rangesets(nside=None)Get the equivalent range of child pixels in nested scheme for a map of equal or higher nside

Parameters nside (int or None) – Nside of output range sets. If None, the map nside willbe used

Returns

With columns named ‘start’ (inclusive) and ’stop’ (exclusive)

Return type recarray

pixarea(pix=0)Return area of pixel in steradians

Parameters pix (int or array) – Pixel number. Only relevant for MOC maps

Returns float or array

plot_grid(ax=’mollview’, ax_kw={}, step=32, coord=’C’, **kwargs)Plot the pixel boundaries of a Healpix grid

Parameters

• ax (WCSAxes or str) – Astropy’s WCSAxes to plot the map. Either an existing in-stance or the name of a registered projection.

• ax_kw (dict) – Extra arguments if a new axes needs to be created.

• step (int) – How many points per pixel side

• coord (str) – Instrinsic coordinates of the map. Either ‘G’ (Galactic), ‘E’ (Ecliptic) ,‘C’ (Celestial = Equatorial) or any other coordinate frame recognized by astropy.

• **kwargs – Passed to matplotlib.pyplot.plot()

Returns

The first return value corresponds to the output pyplot.plot() for one of the pixels.The second is the astropy WCSAxes object used.



Return type matplotlib.lines.Line2D list, WCSAxes

query_disc(vec, radius, inclusive=False, fact=4)

Parameters

• vec (float, sequence of 3 elements) – The coordinates of unit vector defin-ing the disk center.

• radius (float) – The radius (in radians) of the disk

• inclusive (bool) – f False, return the exact set of pixels whose pixels centers liewithin the region; if True, return all pixels that overlap with the region.

• fact (int) – Only used when inclusive=True. The overlapping test will be done at theresolution fact*nside. For NESTED ordering, fact must be a power of 2, less than 2**30,else it can be any positive integer. Default: 4.

Returns The pixels which lie within the given disc.

Return type int array

query_polygon(vertices, inclusive=False, fact=4)Returns the pixels whose centers lie within the convex polygon defined by the vertices array (if inclusiveis False), or which overlap with this polygon (if inclusive is True).

Parameters

• vertices (float) – Vertex array containing the vertices of the polygon, shape (N, 3).


• fact (int) – Only used when inclusive=True. The overlapping test will be done at theresolution fact*nside. For NESTED ordering, fact must be a power of 2, less than 2**30,else it can be any positive integer. Default: 4.

Returns The pixels which lie within the given polygon.


query_strip(theta1, theta2, inclusive=False)Returns pixels whose centers lie within the colatitude range defined by theta1 and theta2 (if inclusive isFalse), or which overlap with this region (if inclusive is True). If theta1<theta2, the region between bothangles is considered, otherwise the regions 0<theta<theta2 and theta1<theta<pi.

Parameters

• theta (float) – First colatitude (radians)

• phi (float) – Second colatitude (radians)


Returns The pixels which lie within the given strip.


schemeReturn HEALPix scheme

Returns Either ‘NESTED’, ‘RING’ or ‘NUNIQ’

Return type str



uniqGet an array with the NUNIQ numbers for all pixels

vec2pix(x, y, z)Get the pixel (as used in []) that contains a given coordinate

Parameters

• theta (float or array) – Zenith angle

• phi (float or arrray) – Azimuth angle


Containers

Simulations

Hit

class BurstCube.containers.Hit(detector, time, energy)Bases: object

Single interaction with a SiPM

Attributes

• time (float) – Time of the hits

• detector (str) – Detector ID

• energy (float) – Deposited energy

SimEvent

class BurstCube.containers.SimEvent(particle, direction, energy, energy_escaped, en-ergy_absorbed, time, hits=[])

Bases: object

Simulation event, with MC truth and possibly some triggered hits

Parameters

• particle (int) – Incoming particle type ID (see Cosima manual)

• direction (list of float) – [x,y,z] direction of incoming particle

• energy (float) – kinetic energy of incoming partigle

• time (float) – Time of the event. Hit times are relative to this

• hits (list of Hit) – Triggered hits.

Attributes

• particle (int) – Incoming particle type ID (see Cosima manual)

• direction (list of float) – [x,y,z] direction of incoming particle

• energy (float) – kinetic energy of incoming partigle

• time (float) – Time of the event. Hit times are relative to this



• hits (list of Hit) – Triggered hits.

add_hit(hit)Add a hit to the event

Parameters hit (Hit) – triggered hit (detector, time and energy)

is_fully_defined()Returns True if no attribute is None

Returns bool

Detector

Detector

class BurstCube.containers.Detector(config)Bases: object

Contains the detector configuration

Parameters config (Configurator) – Configurator with detector characteristics

Attributes

• energy_channel_edges (array) – Definition of energy channels

• detectors (list) – Detector IDs

detectorsDetector list

max_energyUpper bound of last energy channepl

min_energyLower bound of first energy channel

sim_loc_to_detector(x, y, z)Get the detector ID from the position of the hit reported by Cosima

Parameters

• x (str) – x position

• y (str) – y position

• z (str) – z position

Returns Detector ID

Return type str

Histogram

Histogram

class BurstCube.containers.Histogram(edges, contents=None, sumw2=None, labels=None,scale=None)

Bases: object

This is a wrapper of a numpy array with axes and a fill method.



Like an array, the histogram can have an arbitrary number of dimensions.

Standard numpy array indexing is supported to get the contents –i.e. h[:], h[4], h[[1,3,4]], h[:,5:50:2]], etc.–. However, the meaning of the -1 index is different. Instead of counting from the end, -1corresponds to the underflow bin. Similarly, an index equal to the number of bins corresponds to the overflowbin.

You can however give relative position with respect to h.NBINS –e.g. h[0:h.NBINS] result in all regularbins, h[-1:h.NBINS+1] includes also the underflow/overflow bins and h[h.NBINS] gives you the contentsof the overflow bin.

You can also use an Ellipsis object (. . . ) at the end to specify that the contents from the rest of the dimensionare to have the under and overflow bins included. e.g. for a 3D histogram h[1,-1:h.NBINS+1,-1:h.NBINS+1] = h[1,...]. h[:] returns all contents without under/overflow bins and h[. . . ] returns everything,including those special bins.

Additionally, you can specify with a dictionary the indices for specific axes, with all the rest being the default.e.g. h[:,:,1:,:,6] <==> h[{2:slice(1,None), 4:6}]. If you also use the axes id if you labeledthem, e.g. h[{'x':slice(0,h.NBINS+1)}]

If sumw2 is not None, then the histogram will keep track of the sum of the weights squared –i.e. you better usethis if you are using weighted data and are concern about error bars–

You can use the *= operator to weight by a number or an array of weights with the shape of h.nbins+2 (toinclude under/overflow bins).

The operators +, -, += and -= are available. Both operands need to be histograms. An exception will be raisedif the axes are not the same. Note that h += h0 is more efficient than h = h + h0 since latter involves theinstantiation of a new histogram.

Parameters

• edges (Axes or array) – Definition of bin edges, Anything that can be processes byAxes. Lower edge value is included in the bin, upper edge value is excluded.

• contents (array) – Initialization of histogram contents. Might or might not includeunder/overflow bins. Initialize to 0 by default.

• sumw2 (None, bool or array) – If True, it will keep track of the sum of the weightssquared. You can also initialize them with an array

• labels (array of str) – Optionally label the axes for easier indexing

• scale (str or array) – Bin center mode e.g. “linear” or “log”. See Axis.scale(). Not to be confused with the Histogram`'s `method ``scale(),which scales the bin contents, rather than defining what the scale mode of an axis is.

Attributes sumw2 (Histogram) – An auxiliary histogram whose contents are the sum of the squareof the weight that were used to fill this histogram

axesUnderlaying axes object

axisEquivalent to self.axes[0], but fails if ndim > 1

clear()Set all counts to 0

classmethod concatenate(edges, histograms, label=None)Generate a Histogram from a list os histograms. The axes of all input histograms must be equal, and thenew histogram will have one more dimension than the input. The new axis has index 0.



Parameters

• edges (Axes or array) – Definition of bin edges of the new dimension

• histograms (list of Histogram) – List of histogram to fill contents. Might ormight not include under/overflow bins.

• labels (str) – Label the new dimension

Returns Histogram

fill(*values, weight=1)And an entry to the histogram. Can be weighted.

Follow same convention as find_bin()

Parameters

• values (float or array) – Value of entry

• weight (float) – Value weight in histogram.

Note: Note that weight needs to be specified explicitely by key, otherwise it will be considered a value ana IndexError will be thrown.

find_bin(*values, axis=None)Return one or more indices corresponding to the bin this value or set of values correspond to.

You can pass either an array, or specified the values as different arguments. i.e. h.find_bin(x,y,z)= h.find_bin([x,y,z])

Parameters

• values (float or array) – Vaule or list of values

• axis (int or str or list) – If set, values correspond to the subset of axes listedhere

Returns Bin index

Return type int or tuple

interp(*values)Get a linearly interpolated content for a given set of values along each axes. The bin contents are assignedto the center of the bin.

Parameters values (float or array) – Coordinates within the axes to interpolate. Musthave the same size as ndims. Input values as (1,2,3) or ([1,2,3])

Returns float

project(*axis)Return a histogram consisting on a projection of the current one

Parameters axis (int or str or list) – axis or axes onto which the histogram will beprojected –i.e. will sum up over the other dimensiones–. The axes of the new histogram willhave the same order –i.e. you can transpose axes–

Returns Projected histogram




scale(weight, indices=Ellipsis, axis=None)Scale the histogram contents.

By default, h.scale(weight) <==> h *= weight

The parameter indices can be used to specify the slice that will be multiplied by the weights. Followthe same index convention as in [].

If axis is specified, then weights and indices correspond to a single axis.

Parameters

• weights (array-like) – Weights

• indices (int or tuple) – Bin indices

• axis (int or str) – Axis index

shapeTuple with number of bins along each dimensions

slice(axis, start=None, stop=None, underflow=True, overflow=True)Return a histogram which is a slice of the current one, along a given dimension.

Follows same indexing convention as [] operator

Parameters

• axis (int or str) – Dimension that will be sliced

• start (None or int) – Start bin (inclusive)

• stop (None or int) – Stop bin (exclusive). Must be greater than start

• underflow (bool) – If True, the contents before the start bin will be summed up andkept in the underflow bins, otherwise they’ll be discarded

• overflow (overflow) – same as underflow

Returns Sliced histogram


Axis

class BurstCube.containers.histogram.Axis(edges, label=None, scale=None)Bases: object

Bin edges. Optionally labeled

Parameters

• edges (array-like) – Bin edges

• label (str) – Label for axis. If edges is an Axis object, this will override its label

• scale (str) – Bin center mode e.g. “linear” or “log”. See scale(). If edges is an Axisobject, this will override its mode

Attributes

• edges (array-like) – Bin edges

• label (str) – Label for axis



boundsStart of [lower_bound, upper_bound] values for each bin.

centersCenter of each bin.

find_bin(value)Return the bin value corresponds to.

Returns Bin number. -1 for underflow, nbins for overflow

Return type int

interp_weights(value)Get the two closest bins to value, together with the weights to linearly interpolate between them. The bincontents are assigned to the center of the bin.

Values in the edges beyond the center of the first/last bin will result in no interpolation.

Returns Bins [float, float]: Weights

Return type [int, int]

lower_boundsLower bound of each bin

maxOverall upper bound of histogram

minOverall lower bound

nbinsNumber of elements along each axis. Either an int (1D histogram) or an array

scale(mode=None)Control what is considered the center of the bin. This affects centers() and interpolations.

Parameters mode (str or None) –

• linear (default): The center is the midpoint between the bin edges

• symmetric: same as linear, except for the first center, which will correspond to the loweredge. This is, for example, useful when the histogram is filled with the absolute value of avariable.

• log: The center is the logarithmic (or geometrical) midpoint between the bin edges.

Returns The new mode (or current if mode is None).

Return type str

upper_boundsUpper bound of each bin

widthsWidth each bin.

Axes

class BurstCube.containers.histogram.Axes(edges, labels=None, scale=None)Bases: object

Holds a list of axes.



The operator Axes[key] return a subset of these. Key can be either the index or the label. If the key is a singleindex, a single Axis object will be returned

Parameters

• edges (array or list of arrays or Axis) – Definition of bin edges.

• labels (array of str) – Optionally label the axes for easier indexing. Will overridethe labels of edges, if they are Axis objects

• scale (str or array) – Bin center mode e.g. “linear” or “log”. See Axis.scale. Ifnot an array, all axes will have this mode.

interp_weights(*values)Get the bins and weights to linearly interpolate between bins. The bin contents are assigned to the centerof the bin.

Parameters values (float or array) – Coordinates within the axes to interpolate. Musthave the same size as ndims. Input values as (1,2,3) or ([1,2,3]).

Returns Bins and weights to use. Size=2^ndim. Each bin is specified by a tuple containing ndimintegers

Return type array of tuples of int, array of floats

key_to_index(key)Turn a key or list of keys, either indices or labels, into indices

Parameters key (int or str) – Index or label

Returns Index

Return type int

labelsLabel of axes.

Returns Either a string or a tuple of string. None if they are not defined

ndimNumber of axes

Spectra

Spectrum

A collection of spectrum functions.

Translate from/to MEGAlib’s format

class BurstCube.spectra.spectrum.Mono(flux, energy)Mono energetic beam

Parameters

• flux (float) – Flux

• energy (float) – Energy

eval(energy)Evaluate the spectrum F(E)

Parameters energy (iterable) – energy 𝐸 values



Returns flux 𝐹 values

Return type array

integrate(bounds)Evaluate the integral between two energy bounds

Parameters bound (array) – Energy bounds. Either an array with 2 elements or 2D arraywith 2 columns

Returns Integral flux between bounds

Return type float or array

normalize(flux)Update the flux

Parameters flux (float) – new flux

to_megalib()Return equivalent parameters of MEGAlib’s Source.Spectrum and Source.Flux

Returns Spectrum type and parameteters for Source.Spectrum (i.e. PowerLaw min_energymax_energy photon_index) str: Parameter for Source.Flux

Return type list of str

class BurstCube.spectra.spectrum.PowerLaw(norm, index)𝐹 (𝐸) = 𝐴

(︀𝐸

1keV

)︀−𝛼

Parameters

• norm (float) – normalization 𝐴

• index (float) – spectral index 𝛼

Attributes

• norm (float) – normalization 𝐴

• index (float) – spectral index 𝛼

• min_energy (float) – 𝐹 = 0 if 𝐸 < min_energy

• max_energy (float) – 𝐹 = 0 if 𝐸 > max_energy



Returns flux 𝐹 values. F = 0 outside of the min/max_energy bounds

Return type array

fluxTotal integrated flux between energy bounds

integrate(bounds)Evaluate the integral between two energy bounds.

Note that the spectrum evaluates to 0 out of the overall min/max_energy bounds.






normalize(flux, min_energy=None, max_energy=None)Change norm based on the total emission between min_enegy and max_energy

Parameters

• flux (float) – new integral flux between min_energy and max_energy

• min_energy (float) – Lower integration bound. Defaults to self.min_energy

• max_energy (float) – Upper integration bound. Defaults to self.max_energy


Returns Spectrum type and parameteters for Source.Spectrum (i.e. PowerLaw min_energymax_energy photon_index) str: Parameter for Source.Flux


class BurstCube.spectra.spectrum.SpectrumAbstract class representing an spectral model

Child classes need to implement eval(), integrate(), _from_megalib(), to_megalib(), __str__(), __eq__() andnormalize() and property flux



Returns flux 𝐹 values

Return type array

fluxTotal integrated flux between energy bounds

classmethod from_megalib(params, flux)Get object from MEGAlibs format.

Parameters

• params (list) – List of paramters. See str_megalib_format

• flux (str) – Flux value (In MEGAlib the spectrum refers only to the shape)

classmethod from_name(name, *args, **kwargs)Instantiate a spectrum from the subclass name. e.g.: Spectrum.from_name('PowerLaw',

*args, **kwargs) <==> PowerLaw(*args, **kwargs)

integrate(bounds)Evaluate the integral between two energy bounds




normalize(flux, *args, **kwargs)Change normalization parameters based on an integrated flux.



set_elims(min_energy=None, max_energy=None)Set energy limits. Function evaluates to 0 outside of these bounds

Limits stay the same if not specified

Parameters

• min_energy (float) – lower energy bound

• max_energy (float) – uppper energy bound


Returns Spectrum type and parameteters for Source.Spectrum str: Parameter for Source.Flux


Fitting

Fast Norm Fit

class BurstCube.fitting.FastNormFit(max_iter=1000, conv_frac_tol=0.001, zero_ts_tol=1e-05, allow_negative=False)

Bases: object

Perform a fast poisson maximum likelihood ratio fit of the normalization of a source over background.

The likelihood ratio as a function of the norm is computed as follow

𝑇𝑆(𝑁) = 2∑︁𝑖

(︂log𝑃 (𝑑𝑖; 𝑏𝑖 + 𝑁𝑒𝑖)

log𝑃 (𝑑𝑖; 𝑏𝑖)

)︂where 𝑃 (𝑑;𝜆) is the Poisson probability of obtaining 𝑑 count where 𝜆 is expected on average; 𝑏 is the esti-mated number of background counts; 𝑁 is the normalization; and 𝑒 is the expected excess -i.e. signal- pernormalization unit -i.e. the number of excess counts equals 𝑁 .

It can be shown that 𝑇𝑆(𝑁) has analytic derivative of arbitrary order and that the Newton’s method is guaranteedto converge if initialized at 𝑁 = 0.

Note: The background is not allowed to float. It is assumed the error on the estimation of the background issmall compared to the fluctuation of the background itself (i.e. 𝑁𝐵/𝑁𝑜𝑓𝑓 ≪ 1).

Note: Because of the Poisson probability, 𝑇𝑆(𝑁) is only well-defined for 𝑁 ≥ 1. By default, underfluctuationsare set to 𝑇𝑆(𝑁 = 0) = 0. For cases when there is benefit in letting the normalization float to negative values,you can use allow_negative, but in that case the results are only valid in the Gaussian regime.

Parameters

• max_iter (int) – Maximum number of iteration

• conv_frac_tol (float) – Convergence stopping condition, expressed as the ratio be-tween the size of the last step and the current norm value.

• zero_ts_tol (float) – If zero_ts_tol < TS < 0, then TS is set to 0 without failed flagstatus (analytically, TS < 0 should never happen)



• allow_negative (bool) – Allow the normalization to float toward negative values

static dts(data, bkg, unit_excess, norm, order=1)Get the derivative of TS with respecto to the normalization, at given normalization.

Parameters

• data (array) – Observed counts

• bkg (array) – Background estimation. Same size as data. Every element should be >0

• unit_excess (array) – Expected excess per normalization unit. Same size as data.

• norm (float or array) – Normalization value

• order (int) – Derivative order

Returns d^n TS / dN^n, same shape as norm


solve(data, bkg, unit_excess)Get the maximum TS, fitted normalization and normalization error (∆𝑇𝑆 = 1)

Note: The normalization error is obtained from approximating the TS function as as parabola (i.e. validin the Gaussian regime). TS and norm are indeed valid in the Poisson regime.

Parameters




Returns ts, norm, norm error and status (0 = good)

Return type (float, float, float, bool)

static ts(data, bkg, unit_excess, norm)Get TS for a given normalization.

Parameters




• norm (float or array) – Normalization value

Returns TS, same shape as norm


Simulations

Detector effects

Classes that modify a hit in order to reproduce detector effects seen in calibration



class BurstCube.sims.detector_effects.SimDetectorEffectAbstract detector effect class. Derived classes must implement the apply() method, which modify a Hit object

apply(hit)Take a Hit output a new Hit that takes into account a detector effect

Parameters hit (Hit or None) – Hit input object

Returns Hit or None

classmethod from_config(config)Return a detector effects object that will apply all effects in ‘simulations:detector_effects’

Parameters config (Configurator) – Configurator object

Returns SimDetectorEffect

classmethod from_name(name, *args, **kwargs)Instantiate a detector effect from the subclass name. e.g.: SimDetectorEffect.from_name('SimEnergyResolutionFromFit', *args, **kwargs) is equivalent toSimEnergyResolutionFromFit(*args, **kwargs)

class BurstCube.sims.detector_effects.SimDetectorEffects(detector_effects)Apply a collection of detector effects

Parameters detector_effects (list of SimDetectorEffect) – Detector effecto tobe applied, in order

apply(hit)Apply all detector effects

Parameters hit (Hit or None) – Input hit

Returns Output hit

Return type Hit or None

class BurstCube.sims.detector_effects.SimEfficiencyFromPoints(energy, effi-ciency)

Randomly drop a hit based on a arbitrary efficiency vs. energy.

The class takes a set points and interpolates between them. The efficiency of an energy before/after the first/lastpoint will be the eficciency of the first/last point.

Parameters

• energy (array) – List of energy point

• efficiency (array) – efficiency at each of the energy points

apply(hit)Returns None is the hit is dropped, and the same input hits otherwise. On average, it’ll let pass a fractionof hits equal to the efficiency

Parameters hit (Hit or None) – Input hit

Returns None or same as hit

class BurstCube.sims.detector_effects.SimEnergyResolutionFromFit(coeffs)Simulates the energy resolution of the instrument from a fit to various calibrating sources.

This detector effect replaces the energy of the hist with a random value obtained from for the energy from anormal distribution centered at the input energy and a width equal to ∆𝐸/2.35482 where ∆𝐸 is the full widthat half maximum.



The value of ∆𝐸 depends on energy, and comes from a fit of the form

∆𝐸

𝐸=

√︁𝑐20 + 𝑐21(𝐸/keV)−1 + 𝑐22(𝐸/keV)−2 + ...

Note that ∆𝐸/𝐸 ∼ 1/√𝐸 if the energy resolution is only determined by the statistical error on the number of

photoelectrons produces.

Parameters coeffs (array, dict) – List with coefficients [𝑐0, 𝑐1, 𝑐2, . . . ]. Higher ordercoefficients are assummed zero. If a dictionary, the keys correspond to the detectos IDs.

apply(hit)Replaces hit energy

Parameters hit (Hit or list) – Hit to be modified

Response generator

Code for bc-rsp app.

See also: BurstCube.io.CosimaSource and BurstCube.io.CosimaSim

BurstCube.sims.rsp_gen.counts_to_rsp(hist, source, sim, filename)Scale a counts to create a detector response matrix and save it as a GBM RSP file

Parameters

• hist (Histogram) – Histogram with counts (must have an axis labeled “energy”)

• source (CosimaSource) – Cosima source object containing the spectrum and beaminformation

• sim (CosimaSim) – Cosima sim object containing the total duration of the simulation.

• filename (Path) – Location in disk to save the RSP file

BurstCube.sims.rsp_gen.main(argv=None)This method will become the entry point (e.g. executable) for user to generate a response file from the comman-dline

BurstCube.sims.rsp_gen.rsp_gen(working_dir, config, ntriggers=None, nthreads=1, nparts=1,part=1, distance=inf)

Generate an all-sky detector response.

rsp_gen_direction() is called for each of the directions in a HEALPix grid.

Parameters

• working_dir (Path) – Path to working directory

• config (Configurator) – Global configuration object

• ntriggers (int) – Stopping condition

• location (SpacecraftCoords) – Locations of the source

• nthreads (int) – Number of threads. One thread handles one direction at a time

• distance (float) – Distance to source. Far field by default

BurstCube.sims.rsp_gen.rsp_gen_direction(working_dir, config, ntriggers=None, loca-tion=None)

Generate a detector response for a single direction.

If the product from a given step is already available in the working dir, that step will be skept. This is why mostparameters are optional.



Parameters

• working_dir (Path) – Path to working directory

• config (Configurator) – Global configuration object

• ntriggers (int) – Stopping condition

• location (SpacecraftCoords) – Locations of the source

Detector response matrix

class BurstCube.sims.DRM(photon_energies, energy_channels, matrix)Bases: object

Holds a 2D matrix of photon energy (MC truth) vs energy channels (estimated energy).

Parameters

• photon_energies (array or Axis) – MC truth energy edges

• energy_channels (array or Axis) – Estimated energy edges (last bin is overflow)

• matrix (array) – Axis 0 corresponds to photon energy, axis 1 to energy channels

axesReturn photon energy and energy channels axes

Returns Axes

channel_effective_area(energy, channel)Get the effective area at a given photon energy taking into account only the events assigned to a givenenergy channel.

Parameters

• energy (float or array) – Photon energy

• channel (int or array) – Energy channel


effective_area(energy)Get the total (interpolated) effective energy for a given energy

Parameters energy (float or array) – Photon energy


energy_channelsReturns the axis corresponding to the measured energy channels

Returns Labeled ‘channels’

Return type Axis

fold_spectrum(spectrum)Return the expected count rate for a given spectrum for each energy channel

Parameters spectrum (Spectrum) – Flux (keV^-1 cm^-2 s^-1)

Returns Counts per second for each energy channel

Return type array



classmethod from_gbm_rsp(rsp, index=0)Create a detector response matrix using the contents of a gbm.data.RSP

Parameters

• rsp (gbm.data.RSP) – GBM RSP object

• index (int) – The DRM index if the RSP contained matrices for multiple times

Returns DRM

classmethod from_gbm_rsp_file(filename, index=0)Equivalent to from_gbm_rsp(RSP.open(filename), index)

Parameters

• filename (Path) – Path to .rsp(2) file

• index (int) – The DRM index if the RSP contains matrices for multiple times

photon_energiesReturns the axis corresponding to the MC truth photon energies.

Returns Labeled ‘energy’

Return type Axis

to_gbm_rsp()Convert to GBM RSP object

Returns gbm.data.RSP

to_gbm_rsp_file(filename)Save to GBM RSP format

Parameters filename (Path) – Output path

Localization

Localization tables

LocTable

class BurstCube.loc.LocTableBases: abc.ABC

Class prototype to store the neccessary numbers to estimate the localization from a series of counting detectors

get_background()Get estimated background counts. One per measurement

Returns array

get_data()Get measured data.

Returns array

get_expectation(coord)The expected exccess given a normalized spectral hypothesis

Parameters coord (SkyCoord) – Sky coordinate

Returns One per labeled measurement



Return type array

labelsLabels for each measurement. e.g. detector number or name

Returns array

nmeasurementsTotal number of measurements

HealpixLocTable

class BurstCube.loc.HealpixLocTable(base, labels, expectation, data=None, back-ground=None, frame=’icrs’)

Bases: BurstCube.loc.loctable.LocTable, mhealpy.containers.healpix_base.HealpixBase

Localization table based on a HEALPix grid. Can be stored in HDF5 format.

Parameters

• base (HealpixBase) – Defines the healpix geometry

• labels (array) – Label each measurements

• expectation (array) – Expected excess for a normalized spectral hypothesis

• data (array) – Measured counts. Optional.

• background (array) – Estimated background the data. Optional.

• frame (BaseCoordinateFrame or str) – Coordinate frame object or name.NOTE: use only names of built in frames if you need to save the table to disc.

frameCoordinate frame

Returns BaseCoordinateFrame or str

get_background()Get estimated background counts. One per measurement

Returns array

get_data()Set measured counts.

Returns array

get_expectation(coords)The expected exccess given a normalized spectral hypothesis

Parameters coord (SkyCoord) – Sky coordinate

Returns One per labeled measurement

Return type array

labelsLabels for each measurement. e.g. detector number or name

Returns array

classmethod open(filename, name=’LocTable’)Load table from HDF5 file.



Parameters

• filename (str) – Path to file

• name (str) – Group name inside file

set_background(background)Set estimated background counts. One per measurement

Returns array

set_data(data)Set measured counts.

Returns array

write(filename, name=’LocTable’, overwrite=False)Write table to HDF5 file.

Parameters

• filename (str) – Path to file

• name (str) – Group name inside file

• overwrite (bool) – Overwrite group is already exists

Localization likelihood

LocLike

class BurstCube.loc.LocLikeBases: abc.ABC

get_log_like(coords)Return the log-likelihood for a given coordinate under the source hypothesis


get_null_log_like(coords)Return the lg-likelihood for a given coordinate under a background-only hypothesis


NormLocLike

class BurstCube.loc.NormLocLike(*loctable)Bases: BurstCube.loc.loclike.LocLike

Compute the likelihood from a series of observed counts (𝑑𝑖), the estimated background counts (𝑏𝑖) and theexpected excess (𝑒𝑖) given a model hypothesis:

logℒ(𝑁) =∑︁𝑖

log𝑃 (𝜆 = 𝑏𝑖 + 𝑁𝑒𝑖; 𝑑𝑖)

𝑃 (𝜆; 𝑑) = log𝜆𝑑𝑒𝜆

𝑑

The likelihood is maximized against the normalization (𝑁 ). It is the only free (nuisance) parameter.

Parameters loctable (LocTable) – One or more localization tables



get_background()List of background counts estimate for each measurement.

Returns array

get_data()List of measured counts

Returns array

get_expectation(coords)List of expected excess.

Returns array

get_log_like(coords)Return the log-likelihood for a given sky coordinate. The likelihood is maximize against the normalization.

Parameters coords (SkyCoord) – Sky coordinates

Returns array

get_null_log_like(coords)Get the log likelihood for N=0. This is a constant, there are no free parameters

Parameters coords (SkyCoord) – Sky coordinates

labelsLabel for each measurement entry.

Returns array

Maps

TSMap

class BurstCube.loc.TSMap(*args, frame=’icrs’, **kwargs)Bases: mhealpy.containers.healpix_map.HealpixMap

Test statistic map.

Parameters

• frame (str) – Name of astropy coordinate frame of the map

• **kwargs (*args,) – Passed to mhealpy.HealpixMap

best_loc()Coordinate of best estimate

Returns SkyCoord

compute(*loclikes)Compute the TS at each pixel based on a series of LocLike plugins.

error_area(cont=0.9)Area of the confidence region at a given confidence level.

Parameters cont (float) – Containment fraction

Returns astropy.Quantity

frameAstropy coordinate frame



plot(*args, cont=0.9, **kwargs)Plot map.

Parameters

• cont (float) – Set the minimum of the colorbar to show only this fraction containments.Will be overridden by vmin

• **kwargs (*args,) – Passed to mhealpy.HealpixMap

Returns Same as mhealpy.HealpixMap

Utilities

Coordinates

Classes to interact with gbm.coords

class BurstCube.util.coords.Attitude(quat)Spacecract attitude

Parameters quat (array) – Quaternion. Array with 4 elements

quaternionGet attitude in the form of a quaternion (4 element array)

Returns 4 elements

Return type array

class BurstCube.util.coords.CartesianCoords(x, y, z)Cartesian coordinates

Attribute: x (float): Distance along x-axis y (float): Distance along y-axis z (float): Distance along z-axis

spherical

class BurstCube.util.coords.SkyCoords(ra, dec, distance=1)Celestial coordinates.

J2000 unless otherwise noticed.

decDeclination

distance

raRight ascension

to_spacecraftcoords(attitude)Convert to local coordinates

Note: The output distance is the same, only the direction is converted. This is planned to change in thefuture.

Parameters attitude (Attitude) – Spacecraft attitude

Returns SpacecraftCoords



class BurstCube.util.coords.SpacecraftCoords(zenith, azimuth, distance=1)Local spacecraft coordinates

Arg: zenith (float): Zenith angle. azimuth (float): Azimuth angle. Anti-clockwise from x-axis distance (float):Distance to point

azimuth

distance

classmethod from_megalib(params)Construct location from a source.Beam argument in a MEGAlib source file

Parameters params (list) – List of parameter. Either [‘FarFieldPointSource’, zenith, az-imuth] or [‘(Restricted)PointSource’, x, y, z]

to_megalib()Return the location in a format that can be use in MEGAlib in the source.Beam argument of a source file

Returns

Paramters for either a FarFieldPointSource or a RestrictedPointSource

Return type list

to_skycoords(attitude)Convert from local to celestial coordinates.

Note: The output distance is the same, only the direction is converted. This is planned to change in thefuture.

Parameters attitude (Attitude) – Spacecraft attitude

Returns Skycoords

zenith

class BurstCube.util.coords.SphericalCoords(theta, phi, radius)Spherical polar coordinate using Physics convention

Arg: theta (float): Zenith angle phi (float): Azimuth angle. Anti-clockwise from x-axis radius (float): Distanceto point

Attributes

• theta (float) – Zenith angle

• phi (float) – Azimuth angle. Anti-clockwise from x-axis

• radius (float) – Distance to point

cartesianConvert to cartesian coordinates

Units

Base and auxiliary units and constants used througout the library

This help keep track of the units we are usings and makes it easier to interact with other libraries or with the user (readin and display).



Usage example:

>>> from BurstCube.util import units as u>>> energy = 500 * u.keV>>> print("{} MeV".format(energy/u.MeV))0.5 MeV

BurstCube.util.units.GeV = 1000000.0

BurstCube.util.units.MeV = 1000.0

BurstCube.util.units.TeV = 1000000000.0

BurstCube.util.units.cm = 1Base distance unit

BurstCube.util.units.cm2 = 1

BurstCube.util.units.deg = 0.017453292519943295

BurstCube.util.units.eV = 0.001

BurstCube.util.units.halfpi = 1.5707963267948966

BurstCube.util.units.inf = inf

BurstCube.util.units.keV = 1Base energy units

BurstCube.util.units.m = 100

BurstCube.util.units.meter = 100

BurstCube.util.units.pi = 3.141592653589793

BurstCube.util.units.rad = 1

BurstCube.util.units.radian = 1Base angle unit

BurstCube.util.units.s = 1

BurstCube.util.units.second = 1Base time unit

BurstCube.util.units.twopi = 6.283185307179586

Configuration

This defines the properties of the detector. An example configuration file is provided with the library.

Configurator

class BurstCube.config.Configurator(config_path)Bases: object

Access to configuration parameters.

The parameters are organized in nested dictionarys. They set values can be a number, a string or a list. They canbe accessed as e.g. config['group:subgroup:subsubgroup:parameter']

Parameters config_path (Path) – Path to yaml configuration file.



absolute_path(path)Turn a path relative to the location of the config file absolute

Parameters path (Path) – relative path

Returns absolute path

Return type Path

static config_example_path()Get path to the example configuration file

dump(*args, **kwargs)Dump the configuration contents to a file or a string.

All arguments are passed to yaml.dump(). By default it returns as string. You can specify a file or streamto dump it into in the first argument.

override(*args)Override one or more parameter by parsings strings of the form 'group:subgroup:parameter =value'. Value is parsed the same way as yaml would do it, so if it is a string use quotes.

The foreseen use case scenario is to let the uses override parameters from command line e.g.--override "group:parameter = new_value". Note that the values can be override directlyin code by using config['group:parameter'] = new_value".

Parameters args (string or array) – String to parse and override parameters.

static print_config_example_path(argv=None)Get path to the example configuration file

Miscellaneous

Exceptions

Custom exceptions

exception BurstCube.exceptions.CommandLineErrorRaise for a missing or incompatible commanline argument. This is usually caught by the main function and useas input for ArgParser.error()

exception BurstCube.exceptions.ConfigErrorRaise when there is a problem with the configuration

exception BurstCube.exceptions.InternalLogicErrorRaise when the program wanders into an option if shouldn’t.

exception BurstCube.exceptions.NotSupportedUse when the user tries to access a functionality that is not implemented. Unlike NotYetImplemented, thisindicates a feature that is not planned to be implemented in the near future.

exception BurstCube.exceptions.NotYetImplementedRaise to indicate that a given feature has not been implemented yet. Only use as a temporary placeholder.

exception BurstCube.exceptions.ParsingErrorRaise when there as a problem parsing a file

exception BurstCube.exceptions.UserErrorRaise to blame the user!



1.2.5 v0 Documentation

This is the documentation for a the initial Simulations software.

We plan to replace these by a library fully compatible with the new version of gbm-data-tool.

This will be documented here while we make sure all the features are ported

Tutorial

The steps to quickly and efficiently generate source files that are used to simulate a GRB on a given BurstCubearrangement with a given strength and sky position are split into the following steps:

1. Creating source files

config.yaml allows you to select the desired geometry, desired energy range, and desired source position respectively.

Using python, this yaml file is read in using the configurator, which is contained in the simGenerator module. Formore information about each module, please see the code section.

The simGenerator module, along with the rest of the modules required for this process are located within the bin. If itis the case where these functions need to be done in a new or different directory, make sure to export them.

Next, create an object with the configurator by pointing to the yaml file like this:

conf = configurator(‘~/config.yaml’)

and now with this object, run the function conf.createSourceFiles(), which outputs all of the source files into thedesired directory.

2. Running simulations

runSims.py is a function which runs the source files and outputs the .sim files to be further analyzed.

In order to activate runSim.py, simply type into your path

python <location>/runsims.py –runCosima TRUE –sourcepath ./ x where x is the desired amount of source files to runin parallel.

After runSims has completed its operation, the sim files will be outputted in the designated directory for furtheranalysis.

3. Analyzing results

With the sim files generated, these can be plotted using python.

Once uploading the sim files to python, they can be plotted using the module plotSim, which provides many optionsas to how the various simulated detector responses can be analyzed.

BurstCube

simGenerator module

class BurstCube.simGenerator.configurator(*args)



azbinsCreates increments of azimuth angle to be sampled by individual source files.

createSourceFiles(dir=”)Creates a source file from a configurator object with a specific angle and energy

Parameters

• dir (string) –

• desired directory of the output (the) –

Returns

• In your directory all of the source files with specific angles

• and energies.

ebinsCreates increments of energy (keV) to be sampled by individual source files.

loadConfig(path)

saveConfig(path)

zebinsCreates increments of zenith angle to be sampled by individual source files.

BurstCube.simGenerator.createSourceString(config, energy, ze, az)Creates a source file from a configurator object with a specific angle and energy

Parameters config (string) – The .yaml file the imposes the conditions for the source filesdesired.

Returns srcstr – A sring which can be used to create a source file for cosima.

Return type string

bcSim module

class BurstCube.bcSim.simFile(simFile, sourceFile, logFile=”)

ED_res

azimuth

calculateAeff(useEres=False, width=0.0)Calculates effective area of sim file.

Parameters

• useEres (Boolean) – Switch to either use the energy resolution in the calculation ornot. If you don’t use this it assumes all of the events are good.

• width (Float) – The energy width that is used to reject events in the selection.

Returns Aeff – The effective area.

Return type Float

energy

fileToDict(filename, commentString=’#’, termString=None)

getEresFromFile(filename, commentString=’//’)



getHits(detID=4)Get the hit details of all of the events in the sim file. Ignores the a,b,and c details.

Parameters detID (int) – Detector ID (usually 4)

Returns hits – Five column Structured array. Columns are all floats and are x_pos, y_pos, z_pos,E, and tobs.

Return type numpy structured array

getTriggerProbability(num_det=4, test=False)Takes a single simFile (from bcSim.simFiles(config.yaml)) and returns the probability of hitting in eachdetector

Parameters

• num_det (integer) – Number of detectors to get triggers for.

• test (boolean) – Run a quick test over a limited number of events (20)

Returns prob_det_info – Array is (energy, az, ze, error, prob1, prob2, . . . )

Return type numpy array

logToDict(filename)Reads a gzipped log file and populates a dictionary with information about the events. Returns this dictio-nary.

Parameters filename (string or byte like object) – Name of log file to read.

Returns

• eventDict (dictionary)

• Dictionary with the key being the trigger number (int). Each

• value is a tuple of the event number (int) and the detector

• (str) that was hit.

passEres(alpha=2.57, escape=30.0)Calculates the fraction of events that are good (fully absorbed) and those that escape. The default escapephoton energy is for CsI (30.0 keV). An alpha of 2.57 is based on 10% energy resolution at 662 keV with1/sqrt(E) scaling. Sigma is calculated as the FWHM or eres diveded by 2.35.

Returns

• frac (float)

• mod_frac (float)

printDetails()Prints the general information about specific sim files.

zenith

class BurstCube.bcSim.simFiles(config_file)

applyEres()Applies the energy resolution to the deposited energy in each sim file and returns a flattened array forplotting.

Returns

• null (numpy array)



• numpy array that contains all of the events with eres applied.

calculateAeff(useEres=False, sigma=2.0)Calculates effective area from the information contained within the .sim files.

Parameters

• self (null) –

• useEres (boolean) – Switch to use the energy resolution in the calculation.

• sigma (float) – Width of energy cut in sigma. Default is 2.0.

Returns aeffs – Numpy array containing effective area of detector.

Return type array

getAllTriggerProbability(num_detectors=4, test=False)Returns the probabability of hitting each detector in each simulation.

Parameters

• num_detectors (int) – Number of detectors in the simulation

• test (boolean) – run a quick test over a limited number of files (20)

Returns det_prob – Contains information from all the files about the energy, angles and proba-bility of hitting a given detector


loadFiles()

Parameters self (null) –

Returns sfs – numpy array containing information about each sim file.

Return type array

plotSim module

BurstCube.plotSim.getGBMdata(gbmfile=”)Reads the GBM NaI effective area file and returns a numpy array with two columns energy and aeff.

Parameters gbmfile (string) – Name of file that contains the GBM data. If not given, willlook in the installed location.

Returns

• gbmdata (array)

• numpy array with two columns energy and aeff

BurstCube.plotSim.plotAeff(simFiles, useEres=False, plotGBM=False)Plots the GBM NaI effective area against the changing parts of the simulation

Parameters simFiles (list) – Simulation files generated by MEGAlib.

Returns

Return type a bunch of plots!

BurstCube.plotSim.plotAeffComparison(sims, names, useEres=False, compareTo=’GBM’,axis=’ze’, elim=(1, 100000.0))

Makes Aeff comparison plots of two or more simulations.

Parameters



• sims (list) – List of simulation objects that need to be compared.

• names (list) – List of strings used to label the plots. Should be the same length as thesims list.

• compareTo (string) – The curve to make the comparison to in the percent difference.Default is GBM. You can pick any of the other curves in the names list.

• axis (string) – Either ze or az for the angle axis to plot against.

Returns

Return type Nothing

BurstCube.plotSim.plotAeffvsEnergy(energy, aeff, aeff_eres, aeff_eres_modfrac, az=0, ze=0,plotGBM=False)

Plots the GBM NaI effective area against the energy of that source.

Parameters

• energy (array) – numpy array of energy in units of keV of the sources.

• aeff (array) – numpy array with GBM NaI effective area.

• aeff_eres (array) – I’ll look up energy resulution later

• aeff_eres_modfrac (array) – plus escape?

Returns

Return type a plot of the effective area vs. energy.

BurstCube.plotSim.plotAeffvsPhi(azimuth, aeff, aeff_eres, aeff_eres_modfrac)Plots the GBM NaI effective area against the polar angle phi used to generate that source.

Parameters

• azimuth (array) – numpy array of the angle in deg of the source.




Returns

Return type a plot!

BurstCube.plotSim.plotAeffvsTheta(theta, aeff, aeff_eres, aeff_eres_modfrac, energy=100.0,paren=”)

Plots the GBM NaI effective area against the polar angle theta used to generate that source.

Parameters

• theta (array) – numpy array of the angle in deg of the source.




Returns

Return type a plot!



BurstCube.plotSim.plotAngleComparison(sims, names, axis=’ze’, compareTo=”,useEres=False, energyRange=(99, 101), an-gleRange=(0, 360))

Makes Theta comparison plots of two or more simulations.

Parameters

• sims (list) – List of simulation objects that need to be compared.

• names (list) – List of strings used to label the plots. Should be the same length as thesims list.

• axis (string ('ze' or 'az')) – Axis to plot (either ‘ze’ for zenith or ‘az’ forazimuth.

• compareTo (string) – The curve to make the comparison to in the percent difference.Default is the first in the list. You can pick any of the other curves in the names list.

• usEres (bool) – Use the energy resolution in the effective area calculation.

• energyRang (list) – The energy range (in keV) to plot as (emin, emax).

• angleRange (list) – The angular range (in keV) to plot as (degmin, degmax). This willonly plot curves that fall into this range for the axis that you are not plotting against (i.e. it’llbe ‘az’ if you selected ‘ze’ for axis above.

Returns

Return type Nothing

utils module

BurstCube.utils.getAllTriggerProbability(filelist, num_detectors=4, test=False)Takes a bunch of simFiles (from bcSim.simFiles(config.yaml)) and returns the probability of hitting in eachdetector

Parameters

• self (simFiles) –

• test (run a quick test over a limited number of files (20)) –

Returns det_prob – Contains information from all the files about the energy, angles and probabilityof hitting a given detector


BurstCube.utils.getDetailsFromFilename(filename)Function to get the energy and angle from a filename. Really should be meta data.

This function will be deprecated at some point since the energy and angle are in the simFile object now.

BurstCube.utils.getFilenameFromDetails(details)Takes a dictionary of details and makes a machine readible filename out of it. Angle comes in radians.

BurstCube.utils.getTriggerProbability(htsimfile, num_det=4, test=False)Takes a single simFile (from bcSim.simFiles(config.yaml)) and returns the probability of hitting in each detector

Parameters

• self (simFile) –

• test (run a quick test over a limited number of events (20)) –

Returns



• prob_det_info (1x6 numpy array containing information about the)

• energy, angles and probability of hitting a given detector

BurstCube.utils.setPath(desiredPath=”, desiredPathName=’BURSTCUBE’)Checks for desiredPathName path. Returns 0 if ok, 1 if bad.

LocSim

Detector module

class BurstCube.LocSim.Detector.Detector(name=’det’, azimuth_angle=’0:0:0’,zenith_angle=’0:0:0’, noise=True,background_rate=10.0, window=2.0,lat=’37:56:24.7’, lon=’75:27:59’,elev=550000.0)

altitude

cart2polar(x, y, z)

exposure(ra, dec, FoV=False, alt=-10.0, index=0.77, horizon=90.0)This function takes an ra and a dec and reports the exposure at that point. If you declare FoV to be true,it’ll assume the exposure is uniform across the field of view. Otherwise, it will return an effective areasscaled by a cosine dependance up to the horizon.

Parameters

• ra (the right ascension of the test point) –

• dec (the declination of the test point) –

• FoV (If True, assumes a flat exposure. If false, assumes acosine dependance.) –

• alt (The location of the Earth's limb. No exposure belowthis point (degrees)) –

• index (the scaling of the cosine dependance.) –

• horizon (A cut on the field of view of a detector. Noexposure below this point (degrees)) –

Returns float

Return type the exposure at the test point

get_separation(grb)

polar2cart(theta, phi)

sign_time

sign_times

throw_grb(grb)

trigger_time

triggered_counts

triggered_counts_error



GRB module

class BurstCube.LocSim.GRB.GRB(ra, dec, amplitude=10000.0, decay=2.0, T0=0.0, binz=1.0,real=False, filename=”)

loadFRED()

loadReal(filename, nbins=20000.0, sub=True)

Spacecraft module

class BurstCube.LocSim.Spacecraft.Spacecraft(pointings={’01’: (’0:0:0’, ’5:0:0’), ’02’:(’30:0:0’, ’20:0:0’), ’03’: (’60:0:0’,’35:0:0’), ’04’: (’90:0:0’, ’10:0:0’), ’05’:(’120:0:0’, ’25:0:0’), ’06’: (’150:0:0’,’40:0:0’), ’07’: (’180:0:0’, ’15:0:0’),’08’: (’210:0:0’, ’30:0:0’), ’09’:(’240:0:0’, ’45:0:0’), ’10’: (’270:0:0’,’20:0:0’), ’11’: (’300:0:0’, ’35:0:0’), ’12’:(’330:0:0’, ’50:0:0’)}, lat=’37:56:24.7’,lon=’75:27:59’, elev=550000.0, win-dow=4.0, background_rate=10.0,noise=True)

The pointings are just key,item pairs of the pointing directions of the detectors on the spacecraft (respect to 0,0at zenith). The default are 12 detectors pointing every 30 degrees in azimuth and 15 degrees in zenith (offset abit).

detnum

throw_grb(grb)

throw_grbs(grbs, scaled=False, save=False, filename=’grbs.pkl’)

Stats module

BurstCube.LocSim.Stats.addErrors(real_counts, training_counts)Adds all of the errors together in quadrature

Parameters

• real_counts (the array of real grb counts in each detector) –

• training_counts (the arrary of traning counts in eachdetector) –

Returns null – numpy array of the errors

Return type array

BurstCube.LocSim.Stats.calcNorms(real_counts, training_counts)Calculates the norm between the vectors in two numpy arrays.

Parameters

• real_counts (the array of real grb counts in each detector) –

• training_counts (the arrary of traning counts in eachdetector) –



Returns null – numpy array of the norm between all of the vectors

Return type array

BurstCube.LocSim.Stats.calcNormsWithError(real_counts, training_counts,real_counts_with_error)

Utils module

BurstCube.LocSim.Utils.deg2DMS(DEC)Borrowed from Sylvain Baumont http://supernovae.in2p3.fr/~baumont/

BurstCube.LocSim.Utils.deg2HMS(RA)Borrowed from Sylvain Baumont http://supernovae.in2p3.fr/~baumont/

NoahSim

GRBgenerator module

class BurstCube.NoahSim.GRBgenerator.Sky(NSIDE, strength)Generates an array of GRB’s given certains strength at different sky positions.

Output should be an array.

fastcube module

The following cell contains the “FastCube” class. This is the simulation I hope to use emulate the results of state ofthe art simulations on GRB localization, and use these results to characterize the burstcube spacecraft.

For questions/comments please contact me, Noah Kasmanoff, at [email protected] or https://github.com/nkasmanoff

class BurstCube.NoahSim.fastcube.FastCube(background, dettilt, alternating=False)

detABurstCube is composed of 4 separate scintillators to detect and localize events. In this software package,they are labelled A through D.

detBBurstCube is composed of 4 separate scintillators to detect and localize events. In this software package,they are labelled A through D.

detCBurstCube is composed of 4 separate scintillators to detect and localize events. In this software package,they are labelled A through D.

detDBurstCube is composed of 4 separate scintillators to detect and localize events. In this software package,they are labelled A through D.

dets

normA

normB

normC


http://supernovae.in2p3.fr/~baumont/

http://supernovae.in2p3.fr/~baumont/

mailto:[email protected]

https://github.com/nkasmanoff

https://github.com/nkasmanoff


normD

response2GRB(GRB, samples, test=True, talk=False)Using x, respond2GRB will determine the sky position of an array of GRB sources assuming some inherentbackground noise within detectors, along with fluctuations of either Gaussian or Poissonian nature.

Parameters

• GRB (object) – An instance of the separately defined “GRBs” class that contains anumber of evenly spaced sky positions of a given strength.

• test (boolean) – For sanity purposes, if the simulation seems to give unrealistic re-sults, switching to test mode allows for much quicker sampling, allowing it easier to spotpotential errors.

talk [boolean] If desired, prints position by position results.

Returns

• localizationerrors (array) – numpy array that contains the average localization uncer-tainty at each sky position.

• Additionally, response2GRB will print the sky position it is currently sampling, along withthe average offset of localizations at that spot.

response2oneGRB(sourcetheta, sourcephi, sourcestrength)If you wish, will allow you to examine the localization uncertainty of one sampled GRB of somegiven strenth at some point in the sky. For a full/complete simulation just use the function below, “re-sponse2GRB”.

Parameters

• sourcetheta (float) – The displacement in degrees in the zenithal direction.

• sourcephi (float) – The displacement in degrees in the azimuthal direction.

• sourcestrength (float) – The stength in counts of the simulated GRB.

Returns recpos – The reconstructed position of the GRB based on the detectors’ response.

Return type float

burstutils module

BurstCube.NoahSim.burstutils.angle(v1, v2)” Finds the angle between 2 vectors

Parameters

• v1 (array) –

• v2 (array) – The arrays representing the vectors who’s angle is to be calculated.

Returns ang – Angle between the 2 vectors.

Return type float

BurstCube.NoahSim.burstutils.chiresponse(A, x)Deprecated, just use normal “response” function above!

The response function used in the chi squared fitting portion of the simulation. Meant to imitate the actualresponse of a scintillator. Inputs 2 vectors, and responds with a cos^x dependence.



Parameters A (float) – The angle between the two vectors who’s response is meant to be imitated.

Returns A – The cosine dependence based on the angle, includes a mask so that terms correspondingto angular separations beyond pi/2 are 0, imitating what would happen if a GRB didn’t strikethe face of a detector. Further simulations of this effect are neccessary in a different softwarepackage to confirm this assumption, but its okay for now.

Return type float

BurstCube.NoahSim.burstutils.findAngles(v1s, v2s)

BurstCube.NoahSim.burstutils.indexer(chisquareds, bottheta, toptheta, botphi, topphi, botA,topA, ntheta, nphi, nA)

After obtaining an array of all the possible chi squared values, this uses an equation I tediously discovered whichcan backtrack to what term in each array corresponds to the minimim chi squared.

Parameters

• chisquareds (array) – numpy array of all possible chi squared values

• bottheta (float) – Minimum polar angle to be tested.

• toptheta (float) – Maximum polar angle to be tested.

• botphi (float) – Minimum azimuthal angle to be tested.

• topphi (float) – Maximum azimuthal angle to be tested.

• botA (float) – Minimum signal strength to be tested.

• topA (float) – Maximum signal strength to be tested.

• ntheta (int) – Number of sample points between bottheta and toptheta.

• nphi (int) – Number of sample points between botphi and topphi.

• nA (int) – Number of sample points between botA and topA.

Returns

• thetaloc (float) – The reconstructed polar angle of the source.

• philoc (float) – The reconstructeed azimuthal angle of the source.

• Aoguess (float) – The reconstructed strength of the source.

BurstCube.NoahSim.burstutils.length(v)Finds the length of a vector

Parameters v (array) – numpy array representative of the vector you want to find the magnitudeof.

Returns magv – magnitude of v.

Return type float

BurstCube.NoahSim.burstutils.look_up_A(detnorm, source, array=False)The look up table for detector A. Currently for all these functions the coordinates are relative to the top of thespacecraft, not indivudial detectors. To tranform just rotate by this specific detnorm.

Parameters

• detnorm (array) – The vector normal to detector A.

• source (array) – The vector pointing to where in the sky the GRB came from.

Returns x – The exponent of dependence for the detector’s response.

Return type float



BurstCube.NoahSim.burstutils.look_up_B(detnorm, source, array=False)The look up table for detector B. Currently for all these functions the coordinates are relative to the top of thespacecraft, not indivudial detectors. To tranform just rotate by this specific detnorm.

Parameters

• detnorm (array) – The vector normal to detector B.



Return type float

BurstCube.NoahSim.burstutils.look_up_C(detnorm, source, array=False)The look up table for detector C.

Parameters

• detnorm (array) – The vector normal to detector C.


Returns

• x (float) – The exponent of dependence for the detector’s response.

• Example

• Let’s say for this detector, past 30 degrees and for azimuths of

• 60 - 180, it’s blocked. This is what it would look like

• R = 0.76*np.ones(shape=np.shape(X)) – R[30:,60:180] = 0

BurstCube.NoahSim.burstutils.look_up_D(detnorm, source, array=False)The look up table for detector D.

Parameters

• detnorm (array) – The vector normal to detector D.



Return type float

BurstCube.NoahSim.burstutils.quad_solver(detval, detnorm, bottheta, toptheta, botphi, top-phi, botA, topA, ntheta, nphi, nA, background,A=False, B=False, C=False, D=False)

Generates an array of all possible chi terms for a given detector and the number of counts induced in it by somesource. Named quad since BurstCube is composed of 4 detectors, and this generates 1/4 of the terms.

Parameters

• detsvals (array) – Numpy array containing the relative counts in a BurstCube detector.

• detnorms (array) – Numpy array containing the normal vector of a BurstCube detector.

• bottheta (float) – Minimum polar angle to be tested.

• toptheta (float) – Maximum polar angle to be tested.

• botphi (float) – Minimum azimuthal angle to be tested.

• topphi (float) – Maximum azimuthal angle to be tested.

• botA (float) – Minimum signal strength to be tested.



• topA (float) – Maximum signal strength to be tested.

• ntheta (int) – Number of sample points between bottheta and toptheta.

• nphi (int) – Number of sample points between botphi and topphi.

• bgrd (float) – # of background counts inherent to each detector.

• nA (int) – Number of sample points between botA and topA.

Returns chiterm – Numpy array containing all the chisquared terms for one BurstCube detector.

Return type array

BurstCube.NoahSim.burstutils.response(A, x)Meant to imitate the actual response of a scintillator. Inputs 2 vectors, and responds with a cos^x dependence.

Parameters

• A (float) – The angular separation in radians between the normal vector of the detector,and the position in the sky of the simulated GRB.

• x (float) – The dependence

Returns R – The response function of how the scintillator will respond to a source at angle A.

Return type float


Python Module Index

bBurstCube.bcSim, 45BurstCube.exceptions, 43BurstCube.LocSim.Detector, 50BurstCube.LocSim.GRB, 51BurstCube.LocSim.Spacecraft, 51BurstCube.LocSim.Stats, 51BurstCube.LocSim.Utils, 52BurstCube.NoahSim.burstutils, 53BurstCube.NoahSim.fastcube, 52BurstCube.NoahSim.GRBgenerator, 52BurstCube.plotSim, 47BurstCube.simGenerator, 44BurstCube.sims.detector_effects, 32BurstCube.sims.rsp_gen, 34BurstCube.spectra.spectrum, 28BurstCube.util.coords, 40BurstCube.util.units, 41BurstCube.utils, 49

57


58 Python Module Index

Index

Aabsolute_path() (BurstCube.config.Configurator

method), 42adaptive_moc_mesh()

(BurstCube.io.InstrumentResponse classmethod), 16

add_hit() (BurstCube.containers.SimEvent method),23

addErrors() (in module BurstCube.LocSim.Stats), 51altitude (BurstCube.LocSim.Detector.Detector

attribute), 50ang2pix() (BurstCube.io.InstrumentResponse

method), 16angle() (in module BurstCube.NoahSim.burstutils), 53apply() (BurstCube.sims.detector_effects.SimDetectorEffect

method), 33apply() (BurstCube.sims.detector_effects.SimDetectorEffects

method), 33apply() (BurstCube.sims.detector_effects.SimEfficiencyFromPoints

method), 33apply() (BurstCube.sims.detector_effects.SimEnergyResolutionFromFit

method), 34applyEres() (BurstCube.bcSim.simFiles method), 46Attitude (class in BurstCube.util.coords), 40axes (BurstCube.containers.Histogram attribute), 24axes (BurstCube.sims.DRM attribute), 35Axes (class in BurstCube.containers.histogram), 27axis (BurstCube.containers.Histogram attribute), 24Axis (class in BurstCube.containers.histogram), 26azbins (BurstCube.simGenerator.configurator at-

tribute), 44azimuth (BurstCube.bcSim.simFile attribute), 45azimuth (BurstCube.util.coords.SpacecraftCoords at-

tribute), 41

Bbest_loc() (BurstCube.loc.TSMap method), 39boundaries() (BurstCube.io.InstrumentResponse

method), 17

bounds (BurstCube.containers.histogram.Axis at-tribute), 26

BurstCube.bcSim (module), 45BurstCube.exceptions (module), 43BurstCube.LocSim.Detector (module), 50BurstCube.LocSim.GRB (module), 51BurstCube.LocSim.Spacecraft (module), 51BurstCube.LocSim.Stats (module), 51BurstCube.LocSim.Utils (module), 52BurstCube.NoahSim.burstutils (module), 53BurstCube.NoahSim.fastcube (module), 52BurstCube.NoahSim.GRBgenerator (module),

52BurstCube.plotSim (module), 47BurstCube.simGenerator (module), 44BurstCube.sims.detector_effects (module),

32BurstCube.sims.rsp_gen (module), 34BurstCube.spectra.spectrum (module), 28BurstCube.util.coords (module), 40BurstCube.util.units (module), 41BurstCube.utils (module), 49

CcalcNorms() (in module BurstCube.LocSim.Stats), 51calcNormsWithError() (in module

BurstCube.LocSim.Stats), 52calculateAeff() (BurstCube.bcSim.simFile

method), 45calculateAeff() (BurstCube.bcSim.simFiles

method), 47cart2polar() (BurstCube.LocSim.Detector.Detector

method), 50cartesian (BurstCube.util.coords.SphericalCoords at-

tribute), 41CartesianCoords (class in BurstCube.util.coords),

40centers (BurstCube.containers.histogram.Axis at-

tribute), 27

59


channel_effective_area()(BurstCube.sims.DRM method), 35

chiresponse() (in moduleBurstCube.NoahSim.burstutils), 53

clear() (BurstCube.containers.Histogram method), 24close() (BurstCube.io.InstrumentResponse method),

17cm (in module BurstCube.util.units), 42cm2 (in module BurstCube.util.units), 42CommandLineError, 43compute() (BurstCube.loc.TSMap method), 39concatenate() (BurstCube.containers.Histogram

class method), 24config_example_path()

(BurstCube.config.Configurator static method),43

ConfigError, 43Configurator (class in BurstCube.config), 42configurator (class in BurstCube.simGenerator), 44conformable() (BurstCube.io.InstrumentResponse

method), 17CosimaSim (class in BurstCube.io), 13CosimaSource (class in BurstCube.io), 14counts_to_rsp() (in module

BurstCube.sims.rsp_gen), 34createSourceFiles()

(BurstCube.simGenerator.configuratormethod), 45

createSourceString() (in moduleBurstCube.simGenerator), 45

Ddec (BurstCube.util.coords.SkyCoords attribute), 40deg (in module BurstCube.util.units), 42deg2DMS() (in module BurstCube.LocSim.Utils), 52deg2HMS() (in module BurstCube.LocSim.Utils), 52detA (BurstCube.NoahSim.fastcube.FastCube attribute),

52detB (BurstCube.NoahSim.fastcube.FastCube attribute),

52detC (BurstCube.NoahSim.fastcube.FastCube attribute),

52detD (BurstCube.NoahSim.fastcube.FastCube attribute),

52Detector (class in BurstCube.containers), 23Detector (class in BurstCube.LocSim.Detector), 50detectors (BurstCube.containers.Detector attribute),

23detectors (BurstCube.io.InstrumentResponse at-

tribute), 17detnum (BurstCube.LocSim.Spacecraft.Spacecraft at-

tribute), 51dets (BurstCube.NoahSim.fastcube.FastCube attribute),

52

distance (BurstCube.util.coords.SkyCoords attribute),40

distance (BurstCube.util.coords.SpacecraftCoords at-tribute), 41

DRM (class in BurstCube.sims), 35dts() (BurstCube.fitting.FastNormFit static method),

32dump() (BurstCube.config.Configurator method), 43

Eebins (BurstCube.simGenerator.configurator attribute),

45ED_res (BurstCube.bcSim.simFile attribute), 45effective_area() (BurstCube.sims.DRM method),

35energy (BurstCube.bcSim.simFile attribute), 45energy_channels (BurstCube.sims.DRM attribute),

35energy_channels()

(BurstCube.io.InstrumentResponse method), 17error_area() (BurstCube.loc.TSMap method), 39eV (in module BurstCube.util.units), 42eval() (BurstCube.spectra.spectrum.Mono method),

28eval() (BurstCube.spectra.spectrum.PowerLaw

method), 29eval() (BurstCube.spectra.spectrum.Spectrum

method), 30event_iter() (BurstCube.io.CosimaSim static

method), 13exposure() (BurstCube.LocSim.Detector.Detector

method), 50

FFastCube (class in BurstCube.NoahSim.fastcube), 52FastNormFit (class in BurstCube.fitting), 31filename (BurstCube.io.InstrumentResponse at-

tribute), 17fileToDict() (BurstCube.bcSim.simFile method), 45fill() (BurstCube.containers.Histogram method), 25find_bin() (BurstCube.containers.Histogram

method), 25find_bin() (BurstCube.containers.histogram.Axis

method), 27findAngles() (in module

BurstCube.NoahSim.burstutils), 54flux (BurstCube.spectra.spectrum.PowerLaw attribute),

29flux (BurstCube.spectra.spectrum.Spectrum attribute),

30fold_spectrum() (BurstCube.sims.DRM method),

35frame (BurstCube.loc.HealpixLocTable attribute), 37frame (BurstCube.loc.TSMap attribute), 39

60 Index


from_config() (BurstCube.sims.detector_effects.SimDetectorEffectclass method), 33

from_gbm_rsp() (BurstCube.sims.DRM classmethod), 35

from_gbm_rsp_file() (BurstCube.sims.DRM classmethod), 36

from_megalib() (BurstCube.spectra.spectrum.Spectrumclass method), 30

from_megalib() (BurstCube.util.coords.SpacecraftCoordsclass method), 41

from_name() (BurstCube.sims.detector_effects.SimDetectorEffectclass method), 33

from_name() (BurstCube.spectra.spectrum.Spectrumclass method), 30

from_rsps() (BurstCube.io.InstrumentResponse classmethod), 17

Gget_all_neighbours()

(BurstCube.io.InstrumentResponse method), 17get_background() (BurstCube.loc.HealpixLocTable

method), 37get_background() (BurstCube.loc.LocTable

method), 36get_background() (BurstCube.loc.NormLocLike

method), 38get_data() (BurstCube.loc.HealpixLocTable

method), 37get_data() (BurstCube.loc.LocTable method), 36get_data() (BurstCube.loc.NormLocLike method), 39get_drm() (BurstCube.io.InstrumentResponse

method), 17get_expectation()

(BurstCube.loc.HealpixLocTable method),37

get_expectation() (BurstCube.loc.LocTablemethod), 36

get_expectation() (BurstCube.loc.NormLocLikemethod), 39

get_interp_weights()(BurstCube.io.InstrumentResponse method), 18

get_log_like() (BurstCube.loc.LocLike method),38

get_log_like() (BurstCube.loc.NormLocLikemethod), 39

get_null_log_like() (BurstCube.loc.LocLikemethod), 38

get_null_log_like()(BurstCube.loc.NormLocLike method), 39

get_separation() (BurstCube.LocSim.Detector.Detectormethod), 50

getAllTriggerProbability()(BurstCube.bcSim.simFiles method), 47

getAllTriggerProbability() (in moduleBurstCube.utils), 49

getDetailsFromFilename() (in moduleBurstCube.utils), 49

getEresFromFile() (BurstCube.bcSim.simFilemethod), 45

getFilenameFromDetails() (in moduleBurstCube.utils), 49

getGBMdata() (in module BurstCube.plotSim), 47getHits() (BurstCube.bcSim.simFile method), 45getTriggerProbability()

(BurstCube.bcSim.simFile method), 46getTriggerProbability() (in module

BurstCube.utils), 49GeV (in module BurstCube.util.units), 42GRB (class in BurstCube.LocSim.GRB), 51

Hhalfpi (in module BurstCube.util.units), 42HealpixLocTable (class in BurstCube.loc), 37Histogram (class in BurstCube.containers), 23Hit (class in BurstCube.containers), 22

Iindexer() (in module BurstCube.NoahSim.burstutils),

54inf (in module BurstCube.util.units), 42InstrumentResponse (class in BurstCube.io), 16integrate() (BurstCube.spectra.spectrum.Mono

method), 29integrate() (BurstCube.spectra.spectrum.PowerLaw

method), 29integrate() (BurstCube.spectra.spectrum.Spectrum

method), 30InternalLogicError, 43interp() (BurstCube.containers.Histogram method),

25interp_weights() (BurstCube.containers.histogram.Axes

method), 28interp_weights() (BurstCube.containers.histogram.Axis

method), 27is_fully_defined()

(BurstCube.containers.SimEvent method),23

is_mesh_valid() (BurstCube.io.InstrumentResponsemethod), 18

is_moc (BurstCube.io.InstrumentResponse attribute),18

is_nested (BurstCube.io.InstrumentResponse at-tribute), 18

is_ring (BurstCube.io.InstrumentResponse attribute),18

Index 61


KkeV (in module BurstCube.util.units), 42key_to_index() (BurstCube.containers.histogram.Axes

method), 28

Llabels (BurstCube.containers.histogram.Axes at-

tribute), 28labels (BurstCube.loc.HealpixLocTable attribute), 37labels (BurstCube.loc.LocTable attribute), 37labels (BurstCube.loc.NormLocLike attribute), 39length() (in module BurstCube.NoahSim.burstutils),

54loadConfig() (BurstCube.simGenerator.configurator

method), 45loadFiles() (BurstCube.bcSim.simFiles method), 47loadFRED() (BurstCube.LocSim.GRB.GRB method),

51loadReal() (BurstCube.LocSim.GRB.GRB method),

51LocLike (class in BurstCube.loc), 38LocTable (class in BurstCube.loc), 36logToDict() (BurstCube.bcSim.simFile method), 46look_up_A() (in module

BurstCube.NoahSim.burstutils), 54look_up_B() (in module

BurstCube.NoahSim.burstutils), 55look_up_C() (in module

BurstCube.NoahSim.burstutils), 55look_up_D() (in module

BurstCube.NoahSim.burstutils), 55lower_bounds (BurstCube.containers.histogram.Axis

attribute), 27

Mm (in module BurstCube.util.units), 42main() (in module BurstCube.sims.rsp_gen), 34max (BurstCube.containers.histogram.Axis attribute), 27max_energy (BurstCube.containers.Detector at-

tribute), 23merge() (BurstCube.io.CosimaSim method), 14meter (in module BurstCube.util.units), 42MeV (in module BurstCube.util.units), 42min (BurstCube.containers.histogram.Axis attribute), 27min_energy (BurstCube.containers.Detector at-

tribute), 23moc_from_pixels()

(BurstCube.io.InstrumentResponse classmethod), 18

moc_sort() (BurstCube.io.InstrumentResponsemethod), 19

Mono (class in BurstCube.spectra.spectrum), 28

Nnbins (BurstCube.containers.histogram.Axis attribute),

27ndim (BurstCube.containers.histogram.Axes attribute),

28nest2pix() (BurstCube.io.InstrumentResponse

method), 19nmeasurements (BurstCube.loc.LocTable attribute),

37normA (BurstCube.NoahSim.fastcube.FastCube at-

tribute), 52normalize() (BurstCube.spectra.spectrum.Mono

method), 29normalize() (BurstCube.spectra.spectrum.PowerLaw

method), 30normalize() (BurstCube.spectra.spectrum.Spectrum

method), 30normB (BurstCube.NoahSim.fastcube.FastCube at-

tribute), 52normC (BurstCube.NoahSim.fastcube.FastCube at-

tribute), 52normD (BurstCube.NoahSim.fastcube.FastCube at-

tribute), 52NormLocLike (class in BurstCube.loc), 38NotSupported, 43NotYetImplemented, 43npix (BurstCube.io.InstrumentResponse attribute), 19nside (BurstCube.io.InstrumentResponse attribute), 19

Oopen() (BurstCube.io.CosimaSim class method), 14open() (BurstCube.io.CosimaSource class method), 15open() (BurstCube.loc.HealpixLocTable class method),

37order (BurstCube.io.InstrumentResponse attribute), 19override() (BurstCube.config.Configurator method),

43

PParsingError, 43passEres() (BurstCube.bcSim.simFile method), 46photon_energies (BurstCube.sims.DRM attribute),

36photon_energies()

(BurstCube.io.InstrumentResponse method), 19pi (in module BurstCube.util.units), 42pix2ang() (BurstCube.io.InstrumentResponse

method), 19pix2range() (BurstCube.io.InstrumentResponse

method), 19pix2uniq() (BurstCube.io.InstrumentResponse

method), 19pix2vec() (BurstCube.io.InstrumentResponse

method), 20

62 Index


pix_order_list() (BurstCube.io.InstrumentResponsemethod), 20

pix_rangesets() (BurstCube.io.InstrumentResponsemethod), 20

pixarea() (BurstCube.io.InstrumentResponsemethod), 20

plot() (BurstCube.loc.TSMap method), 39plot_grid() (BurstCube.io.InstrumentResponse

method), 20plotAeff() (in module BurstCube.plotSim), 47plotAeffComparison() (in module

BurstCube.plotSim), 47plotAeffvsEnergy() (in module

BurstCube.plotSim), 48plotAeffvsPhi() (in module BurstCube.plotSim), 48plotAeffvsTheta() (in module BurstCube.plotSim),

48plotAngleComparison() (in module

BurstCube.plotSim), 48polar2cart() (BurstCube.LocSim.Detector.Detector

method), 50PowerLaw (class in BurstCube.spectra.spectrum), 29print_config_example_path()

(BurstCube.config.Configurator static method),43

printDetails() (BurstCube.bcSim.simFile method),46

project() (BurstCube.containers.Histogram method),25

Qquad_solver() (in module

BurstCube.NoahSim.burstutils), 55quaternion (BurstCube.util.coords.Attitude attribute),

40query_disc() (BurstCube.io.InstrumentResponse

method), 21query_polygon() (BurstCube.io.InstrumentResponse

method), 21query_strip() (BurstCube.io.InstrumentResponse

method), 21

Rra (BurstCube.util.coords.SkyCoords attribute), 40rad (in module BurstCube.util.units), 42radian (in module BurstCube.util.units), 42response() (in module

BurstCube.NoahSim.burstutils), 56response2GRB() (BurstCube.NoahSim.fastcube.FastCube

method), 53response2oneGRB()

(BurstCube.NoahSim.fastcube.FastCubemethod), 53

rsp_gen() (in module BurstCube.sims.rsp_gen), 34

rsp_gen_direction() (in moduleBurstCube.sims.rsp_gen), 34

run() (BurstCube.io.CosimaSource method), 15

Ss (in module BurstCube.util.units), 42saveConfig() (BurstCube.simGenerator.configurator

method), 45scale() (BurstCube.containers.Histogram method), 25scale() (BurstCube.containers.histogram.Axis

method), 27scheme (BurstCube.io.InstrumentResponse attribute),

21second (in module BurstCube.util.units), 42set_background() (BurstCube.loc.HealpixLocTable

method), 38set_data() (BurstCube.loc.HealpixLocTable

method), 38set_elims() (BurstCube.spectra.spectrum.Spectrum

method), 30set_point_source() (BurstCube.io.CosimaSource

method), 15setPath() (in module BurstCube.utils), 50shape (BurstCube.containers.Histogram attribute), 26sign_time (BurstCube.LocSim.Detector.Detector at-

tribute), 50sign_times (BurstCube.LocSim.Detector.Detector at-

tribute), 50sim_loc_to_detector()

(BurstCube.containers.Detector method),23

SimDetectorEffect (class inBurstCube.sims.detector_effects), 32

SimDetectorEffects (class inBurstCube.sims.detector_effects), 33

SimEfficiencyFromPoints (class inBurstCube.sims.detector_effects), 33

SimEnergyResolutionFromFit (class inBurstCube.sims.detector_effects), 33

SimEvent (class in BurstCube.containers), 22simFile (class in BurstCube.bcSim), 45simFiles (class in BurstCube.bcSim), 46Sky (class in BurstCube.NoahSim.GRBgenerator), 52SkyCoords (class in BurstCube.util.coords), 40slice() (BurstCube.containers.Histogram method), 26solve() (BurstCube.fitting.FastNormFit method), 32Spacecraft (class in BurstCube.LocSim.Spacecraft),

51SpacecraftCoords (class in BurstCube.util.coords),

40Spectrum (class in BurstCube.spectra.spectrum), 30spherical (BurstCube.util.coords.CartesianCoords

attribute), 40

Index 63


SphericalCoords (class in BurstCube.util.coords),41

TTeV (in module BurstCube.util.units), 42throw_grb() (BurstCube.LocSim.Detector.Detector

method), 50throw_grb() (BurstCube.LocSim.Spacecraft.Spacecraft

method), 51throw_grbs() (BurstCube.LocSim.Spacecraft.Spacecraft

method), 51time_shift() (BurstCube.io.CosimaSim method), 14to_gbm_rsp() (BurstCube.sims.DRM method), 36to_gbm_rsp_file() (BurstCube.sims.DRM

method), 36to_megalib() (BurstCube.spectra.spectrum.Mono

method), 29to_megalib() (BurstCube.spectra.spectrum.PowerLaw

method), 30to_megalib() (BurstCube.spectra.spectrum.Spectrum

method), 31to_megalib() (BurstCube.util.coords.SpacecraftCoords

method), 41to_skycoords() (BurstCube.util.coords.SpacecraftCoords

method), 41to_spacecraftcoords()

(BurstCube.util.coords.SkyCoords method), 40to_TTE() (BurstCube.io.CosimaSim method), 14trigger_time (BurstCube.LocSim.Detector.Detector

attribute), 50triggered_counts (BurstCube.LocSim.Detector.Detector

attribute), 50triggered_counts_error

(BurstCube.LocSim.Detector.Detector at-tribute), 50

ts() (BurstCube.fitting.FastNormFit static method), 32TSMap (class in BurstCube.loc), 39twopi (in module BurstCube.util.units), 42

Uuniq (BurstCube.io.InstrumentResponse attribute), 21upper_bounds (BurstCube.containers.histogram.Axis

attribute), 27UserError, 43

Vvec2pix() (BurstCube.io.InstrumentResponse

method), 22

Wwidths (BurstCube.containers.histogram.Axis at-

tribute), 27write() (BurstCube.io.CosimaSource method), 15write() (BurstCube.loc.HealpixLocTable method), 38

Zzebins (BurstCube.simGenerator.configurator at-

tribute), 45zenith (BurstCube.bcSim.simFile attribute), 46zenith (BurstCube.util.coords.SpacecraftCoords at-

tribute), 41

64 Index

BurstCube Documentation Documentation

Documents

Transcript of BurstCube Documentation Documentation