Transients

A transient photometry in redback is implemented as a redback.transient object. This class implements the required functionality for fitting and all other analysis. It also provides a homogenous way to plot the data, or do any processing such as converting integrated flux to luminosity, fit a GP to the lightcurve, build a bolometric luminosity from photometry, etc

General transient object

There are two parent classes

Transient: For any type of generic transient
OpticalTransient: For any type of generic optical transient

Specific transient object

These parent classes are inherited by some transient specific classes, which provide additional functionality.

Afterglow: afterglow of a gamma-ray burst
- SGRB/LGRB: short and long gamma-ray bursts
Kilonova: For kilonovae
Prompt: For prompt gamma-ray bursts
Supernova: For supernovae of different varieties
TDE: For tidal disruption events

These classes come with additional functionality and lookup tables which provide metadata useful for further analysis, such as redshift, T90, start time, etc. They also allow other processing such as converting flux to luminosity.

We provide two methods for converting integrated flux to luminosity for GRB afterglow data, a simple analytical method, and a more involved method using sherpa.

For each of the transients we have different data_modes which determines what data to fit, plot labels, type of likelihood to use etc. We note that the latter two can be changed by users if desired.

Data modes

The data modes available for each transient are

Afterglow: luminosity, flux, flux_density, magnitude
Kilonova: flux_density, magnitude, flux
Prompt: counts, time tagged events
Supernova: flux_density, magnitude, luminosity, flux
TDE: flux_density, magnitude, luminosity, flux

Loading catalog data

In redback, we provide several class methods for loading data and creating a transient object. For example loading and creating a transient object for data from the open access catalog is as simple as,

kne = 'at2017gfo'
kilonova = redback.Kilonova.from_open_access_catalogue(name=kne,
            data_mode="flux_density", active_bands=np.array(["g", "i"]))

This loads the data from at2017gfo that was previously downloaded and creates a kilonova object, with the flux_density data mode. Here we have also specified active_bands=np.array(['g', 'i'). This sets the rest of the data to be inactive, i.e., not used in the fitting. All bands/frequencies are active by default.

We can use this transient object to create plots of the data.

kwargs = {}
kilonova.plot_data()
fig, axes = plt.subplots(3, 2, sharex=True, sharey=True, figsize=(12, 8))
kilonova.plot_multiband(figure=fig, axes=axes,
                        filters=["g", "r", "i", "z", "y", "J"], **kwargs)

Here the first plot_data will plot the data with all bands on one plot. While the second will plot all filters in the list in separate panels. We have also passed kwargs here (in this case empty) but can be populated with other keyword arguments to pass to matplotlib. We have also passed in a fig and axes to set up the plot in the specific way we wanted. We note that if no figure/axes/filters are passed then redback will use the defaults. More plotting documentation is available here.

Other transient objects can be constructed in a similar manner to the kilonova object.

prompt = '910505'
GRB = '070809'
sne = "SN2011kl"
tde = "PS18kh"

afterglow = redback.SGRB.from_swift_grb(name=GRB, data_mode='flux')
tidal_disruption_event = redback.TDE.from_open_access_catalogue(tde, data_mode='magnitude')
prompt = redback.PromptTimeSeries.from_batse_grb_name(name=name)
supernova = redback.supernova.Supernova.from_open_access_catalogue(name=sne,
                            data_mode='flux_density', use_phase_model=True)

Which loads the SGRB, TDE, prompt, and Supernova transient objects with the data for the specific transient respectively. Note that in the supernova object, we set phase_model=True. This sets the time attribute of the class to the modified julian date time of the observations. This is specifically for situations when users want to also sample the start time of the transient.

Loading private/simulated data

The above showed the scenario where a user has used redback to download the data. In many cases, this is not possible as either a catalog is not implemented in redback, or the data is simulated, or the data is private.

In this scenario, a user can still create the redback.transient object and use it as they would otherwise.

We demonstrate this with data loaded from a pandas dataframe in the example here. An example to load the simulated data from redback simulation module is shown here.

In general, you can ignore the class methods and to create your own transient object by passing in the different attributes (time/flux/frequencies/bands) to the transient object of relevance.

For example,

import pandas as pd
import redback

data = pd.read_csv('data.csv')
time_days = data['time'].values
flux_density = data['flux_density'].values
frequency = data['frequency'].values
flux_density_err = data['flux_density_err'].values

name = '220501'
afterglow = redback.afterglow(name=name, time=time_days, flux=flux_density,
                                flux_density_err=flux_density_err, frequency=frequency)

We can again plot the data and multiband data

afterglow.plot_data()
afterglow.plot_multiband()

These transient objects provide the interface to fit and interpret many types of electromagnetic transients. In particular, broadband afterglows, kilonovae, prompt gamma-ray burst, supernovae, tidal disruption events, magnetar powered transients, millisecond magnetars or any other generic electromagnetic transient. A more general example which shows the different ways to create transient objects in redback is available here.

Working with transient data in MJD

Quite often the only time values we have are in MJD. In this case, we can set the time attribute of the transient object to be in MJD. As an example,

import redback
import pandas as pd

# load your data
data = pd.read_csv('data.csv')
time_mjd = data['time'].values
magnitude = data['mag'].values
bands = data['frequency'].values
mag_err = data['mag_err'].values

name = 'my_transient'
# note that we set the time_mjd instead of a time attribute
# note that we set use_phase_model=True
sn = redback.transient.Supernova(name=name, time_mjd=time_mjd, magnitude=flux_density,
                                magnitude_err=mag_err, bands=bands, use_phase_model=True)

Now when we call the plot_data method, we will see the time in MJD. And the time attribute of the transient object will be in MJD. To fit this we will need to use a phase model or a model that works with time data. Please look at the rest of the documentation and examples for more details.

GP interpolation

redback provides a simple interface for doing GP interpolation directly from the transient object. This can be done to simply interpolate the data, and generate new data, or to do a GP fit with some mean model.

For example, we can do a GP interpolation of the data in the supernova object as follows,

# Use any transient object previously made.
from george import kernels

k1 = kernels.ConstantKernel(np.std(transient.y/transient.y.max()), ndim=2)
k2 = kernels.Matern32Kernel([np.var(np.diff(transient.unique_frequencies)), 100], ndim=2)
kernel = k1 * k2

output = transient.fit_gp(mean_model="None", kernel=kernel, use_frequency=True)

Here we set mean_model="None" to not use any mean model. The kernel is a product of two kernels, a constant kernel and a Matern32 kernel. And use_frequency=True to use the frequency data so that we can use a 2D kernel with time and the effective frequency of the different bands. We could also pass in a mean model to use, such as a power law or a polynomial, or things like a Bazin or Gaussian model. We could also just use a 1D kernel.

Note that this method only optimizes the GP hyperparameters and does not sample a posterior. In the examples, we show how you can use a GP + a mean model and get a full posterior of the GP hyperparameters and the model.

The output here contains the GP object alongside a bunch of useful attributes. The GP fit can be plotted alongside the data using

Where we can pass in additional keyword arguments to the plotting functions. Please look at the API and plotting documentation for more details.

This GP result can be used to generate a new set of data points via,

t_new = np.linspace(10, 150, 100)
new_sn = redback.analysis.generate_new_transient_data_from_gp(output, t_new=t_new,
                                                             transient=transient)

Where we are returned a new transient object with the new data points. Which works exactly like all other transient objects within redback.

Again, we provide a notebook example here and some other examples in the examples folder.

Blackbody temperature and radius estimation.

redback provides a simple interface for estimating the blackbody temperature and radius of the transient object. This is done by fitting a blackbody model to the data and estimating the temperature and radius from the best fit parameters.

For example, we can do this for the kilonova object as follows,

# Use any optical transient object previously made.
# these can be passed to the method,
# here we use the default values which are used if nothing is passed.
bin_width = 1 # width with which to bin the data in days,
min_filters = 3 # minimum number of filters/frequencies the epoch must have to be fit.

# Some other things can also be passed to this function, look at the API.
df_bb = kilonova.estimate_bb_params(distance=distance, bin_width=bin_width,
                                    min_filters=min_filters)

Here we are returned a pandas dataframe with the best fit temperature and radius and their errors at times dictated by the bin widths where the transient also has a mininum number of filters.

We provide a detailed notebook example here.

Bolometric luminosity estimation.

redback provides a simple interface for estimating the bolometric luminosity of the transient object. This can be done either using a blackbody SED, or any other redback SED or with some bolometric corrections.

For example, we can do this for the kilonova object as follows,

# Some other things can also be passed to this function, look at the API.
df_lbol = kilonova.estimate_bolometric_luminosity(distance=distance, bin_width=bin_width,
                                                    min_filters=min_filters)

Here we are returned a pandas dataframe with the bolometric luminosity and its errors at times dictated by the bin widths where the transient also has a minimum number of filters. Note this method by default works assuming a blackbody SED, but we provide a simple option to include the effects of line blanketing as well as host/MW extinction.

This data can be easily used to create another transient object with the bolometric luminosity data and then fit. Please look at the API for more details and the examples

Spectrum object

redback also provides a spectrum object which can be used to load, plot, and fit spectral energy distributions. These are treated the same for all transients and are generic enough to describe any wavelength spectrum. The spectrums can be fit with any redback model or any user defined model. And some examples are provided in the examples folder on the github repository.