Time Series Demo

Written by Robert Morgan

This notebook will demonstrate the use of deeplenstronomy to create a time series of images.

For this example, we'll use the demo_timeseries.yaml config file, which already has timeseries functionality built in. It is the same demo file we have been using, but we have updated the entries for SPECIES.POINTSOURCE_2 and CONFIGURATION_3 to include the temporal evolution of the supernova in that system.

Note: SURVEY.num_exposures must be set to 1 (to better reflect real time-series data) and cannot be drawn from a distribution if you are using any time-series features.

Configuration File Keywords - MODEL

Check out the information in the SPECIES section for POINTSOURCE_2. You will notice the MODEL keyword is new and has not been used in other examples. Next, take a look at CONFIGURATION_3; you should see an entry for TIMESERIES. These two additions to the config file are all you need to utilize the time series features of deeplenstronomy.

Let's start with the MODEL keyword in the SPECIES section. The MODEL points deeplenstronomy to the type of temporal behavior you want to add to the object.

Time series toy models

The basic options for time series models are:

Time series spectral models

Aside from these toy time-series models, deeplenstronomy has real objects built in as well. You also have the ability to simulate supernova and kilonova light curves. Under the hood, deeplenstronomy has a time series spectral energy distribution (SED) for type-Ia supernovae, core-collapse supernovae, and the kilonova counterpart to GW170817. When these models are called, deeplenstronomy redshifts the spectra, integrates the spectra through the bands of the survey, and produces a magnitude in each band on each nite.

Specifically, these SEDs are automatically downloaded when you request time-series data for the first time. They are:

The GW170817 model is just a single file located in seds/kn/kn.SED

The reason for diving into the raw files is that deeplenstronomy allows you to either choose randomly from all the available SEDs for a given object, or allows you to specify the particular file of interest.

To use a specific SNe-CC or SNe-Ia model, you replace random with the filename you want:

The GW170817 kilonova model is targeted by MODEL: kn_kn.SED to match the syntax of the other models, even though there is currently only one model.

User-specified time series models

Like other features in deeplenstronomy (image background, probability distributions, etc.) the user has the ability to incorporate their own data into the simulations. To use your own file, format a SED file like the built-in deeplenstronomy files:

The columns (from left to right) are days relative to the date of peak flux, the wavelength in angstroms, and the flux in erg / cm$^2$ / sec.

If you are not simulating data using Dark Energy Survey bands, you will need to also supply transmission curevs for all filters in your survey in the filters/ directory while following all formatting of the provided transmission curves.

To target your model from the deeplenstronomy configuration file, you use the MODEL keyword as follows:

Configuration File Keywords - TIMESERIES

The final step in including time series behavior in your dataset is to specify which object in which configuration you want to "time-series-ify", and the temporal spacing of the observations.

In the demo_timeseries.yaml file, we have done:

    CONFIGURATION_3:
        NAME: LENSED_SNE
        FRACTION: 0.25
        PLANE_1:
            OBJECT_1: LENS
            PARAMETERS:
                REDSHIFT: 0.2                    
        PLANE_2:
            OBJECT_1: SOURCE
            OBJECT_2: SUPERNOVA
            PARAMETERS:
                REDSHIFT: 0.7      
        NOISE_SOURCE_1: POISSON_NOISE   
        TIMESERIES:
            NITES: [-10, -5, 0, 5, 10]
            OBJECTS: ['SUPERNOVA']

The name SUPERNOVA is the NAME of POINTSOURCE_2 in the SPECIES section, and listed as OBJECT_2 in PLANE_2 of CONFIGURATION_3. deeplenstronomy uses this NAME value to connect the properties of the object to its temporal behavior. Making sure the NAME value is connected across these sections is essential for deeplenstronomy to work properly.

The remaining TIMESERIES attributes have the following meanings:

What About Quasars???

Searching for lensed quasars is a popular science case at the interface of time-series data and strong lensing. However, deeplenstronomy's time-series functionality is mainly built to simulate explosive objects, not persistent variable objects, so the use of time-series functionality to simulate lensed quasars is discouraged.

That being said, detections of lens quasars from images are usually made by detecting the system in a single image and then obtaining further observations to characterize the light curve of the potential quasar images, as opposed to detecting them only through a time-series set of images. For this purpose, deeplenstronomy's USERDIST functionality is exactly what you're looking for!

Through specifying a USERDIST you can readily put quasar color distributions into your distributions to get realistic single images of lensed quasars.

Generating the Dataset

If this is your first time simulating a particular class of time series object, deeplenstronomy will need to quickly download some data. It will automatically get what it needs from my GitHub, and it will target my deeplenstronomy_data repo.

The data it will download are time-series spectra and the transmission curves for whichever filters you specified.

When you run in time series mode, deeplenstronomy will build up a light curve bank while processing your configuration file and before it begins simulating images. This extra step may take a few minutes to run, but will only need to occur at the beginning of the simulation.

In the config file, the time series objects were placed in CONFIGURATION_3, so let's focus there for this example.

The images for the entire configuration will all be stacked in the dataset.CONFIGURATION_3_images, so therefore it is a good idea to use the OBJID columns in dataset.CONFIGURATION_3_metadata to track the images that are part of the same time series.

Now let's visualize the time-evolution of the object

We can also access and plot the light curve of the point source like this: