• Home
• About
  The Swift Mission UK involvement Instruments

  ---

  GRBs before Swift GRBs in the Swift era Non-GRB science with Swift GRB research at Leicester

  ---

  Spacecraft status Swift in the press Swift Videos
• Support
  Helpdesk TOO requests Guest Investigator program Target visibility checker Search transient database
• Data Access
  Overview Quick Look GCN Notices Download obs data Search obs catalogue The 2SXPS catalogue The LSXPS catalogue
• Data Analysis
  Data analysis overview Swift software

  ---

  Build XRT products

  ---

  BAT data analysis guide XRT data analysis guide XRT digest UVOT data analysis guide
• Data Products
  GRBs Full dataset Swift XRT products for GRBs XRT positions XRT light curves XRT spectra XRT GRB catalogue XRT GRB images Burst analyser Prompt data GRB field info XRT prompt analysis External triggers Einstein Probe follow up SVOM follow up Neutrino follow up Gravitational Wave follow up
• Publications
  Publication index Published papers Submitted papers XRT instrument papers ATels GCNs Conferences
• Links
  Databases NED Simbad GCN circulars archive GRB data table Software & Tools Swift Software (HEASoft) Xanadu WebPIMMS Institutional Swift Sites GSFC PSU OAB SSDC MSSL University of Leicester

How to request products

The main part of requesting products be built is, well, requesting that products be built(!). This is relatively straightforward in concept and can be done with a very small number of commands; however, it does require you to know what parameters can be set, and which ones are mandatory. Fortunately, this page gives you all of that information. Note: This documentation is not designed to introduce the XRT Product Generator. If you are not familiar with this facility we strongly advise you to read that facility's documentation first, and we also recommend that you build a few products via the web interface web interface to familiarise yourself with the system before trying to use the Python module.

On this page we will:

• Detail the Python commands used to create a product request
  • Managing global parameters
  • Managing specific parameters
  • Submitting the request
• List the parameters than can/must be set, by category:
  • Global parameters
  • XRTProductRequest parameter
  • Light curve parameters
  • Spectrum parameters
  • Position parameters
  • Image parameters
  • Source detection parameters

Python commands relating to product creation

The first step for creating a product request is to create an XRTProductRequest object. For this you need the email address you registered with:

In [1]: import swifttools.ukssdc.xrt_prods as ux
In [2]: myReq = ux.XRTProductRequest('YOUR_EMAIL_HERE', silent=False)

Now we need to build up the request. The basic controls are to set global parameters, add products and set their parameters, and to check if the request has all the mandatory parameters set. These steps are all described below.

One little note: in this documentation I am describing all of the options (with code examples from an ipython shell). This is to give an introduction to the API, and of course, you may want to play around like this yourself. However, scripted requests will likely not use many of the functions described below: for example, a script won't decide to add a light curve and then change its mind!

Managing global parameters

Global parameters are set using the setGlobalPars function which receives the parameters as keyword arguments. That is, we simply use "par=value" as the function arguments, where the "par"s are the global parameters. i.e.

In [3]: myReq.setGlobalPars(centroid=True, posErr=1.5)

You can set as many global parameters as you want at a time, and can call setGlobalPars as many times as you want.

If you want to check what values certain global parameters have, you can use the getGlobalPars function. This takes an optional argument which is a parameter name or 'all' (which is the default). The former case will return the value of the specified parameter (or None if it is not yet set). The latter will return a dictionary of all of the parameters that have been set. Optionally in the latter case you can set showUnset=True and this will list all global parameters.

In [4]: myReq.getGlobalPars('centroid')
Out[4]: True

In [5]: print(myReq.getGlobalPars('detMeth')) # add print because (i)python does not show anything for None without it!
Out[5]: None

In [6]: myReq.getGlobalPars() # same as getGlobalPars('all')
Out[6]: {'centroid': True, 'posErr': 1.5}

In [7]: myReq.getGlobalPars(showUnset=True)
Out[7]:
{'name': None,
 'targ': None,
 'T0': None,
 'SinceT0': None,
  ...etc...
}

Managing specific products

The basic format for adding and manipulating products is simple and is the same for all products, except that the product name changes. In the list below I have used the light curve product, but if you replace LightCurve with another product name then you will have the command for the other product.

The products available are:

• LightCurve
• Spectrum
• StandardPos
• EnhancedPos
• AstromPos
• Image
• SourceDet

And the functions to manipulate them are:

• addLightCurve()
• removeLightCurve()
• setLightCurvePars()
• getLightCurvePars()
• removeLightCurvePar()

So now let's unpack this a bit.

To add a product you use the add...() function. This can be called either with no parameters, or you can pass parameters as well. These are passed as Python keyword arguments, i.e. just as par=value pairs. The permitted parameters and values for each product appear further down this page.

In [8]: myReq.addLightCurve(binMeth='counts')
Successfully created a light curve

You can only have one of each type of product per request, so if you call addLightCurve when myReq already has a light curve, you will get an error. If you wanted to completely forget the light curve request you'd formed and start again, you can simply add the argument clobber=True to the addLightCurve() function (or the addSpectrum() etc. function for different products).

If you didn't pass the parameters at creation time, or didn't pass all of them or you want to change them, you can do this with the set..() function:

In [9]: myReq.setLightCurvePars(pcCounts=20, wtCounts=30, dynamic=True)

We can check the light curve parameters as we did for the globals:

In [9]: myReq.getLightCurvePars('binMeth')
Out[9]: 'counts'

In [10]: myReq.getLightCurvePars()
Out[10]: {'binMeth': 'counts'}

In [11]: myReq.getLightCurvePars(showUnset=True)
Out[11]:
{'binMeth': 'counts',
 'soft1': None,
 'soft2': None,
 'hard1': None,
 ...etc...
}

Conceivably we may want to remove a parameter we'd set. For example, for a spectrum we may have set a redshift, and then changed our minds, so we can remove it with remove...() thus:

In [12]: myReq.addSpectrum(redshift=1.23)
myReq.addSpectrum(redshift=1.23)
Successfully created a spectrum
Also setting hasRedshift = True

In [13]: myReq.removeSpectrumPar('redshift')
Also setting hasRedshift = False

This example lets me introduce one other concept. There are a few parameters that are automatically set if another parameter is set. In the case above you can see that when we set the redshift the code was intelligent enough to realise that this means we want to fit the spectrum with a redshift, and so it set the hasRedshift parameter to True, and then do the inverse when the redshift was removed.

Finally, we may decide that we don't want to build this product after all, so we can remove it:

In [14]: myReq.removeSpectrum()

Little aside

In the above I've described the functions of the form getLightCurvePars() etc. These are actually convenience functions which are really just wrappers, internally they call generic functions and pass the product name. I can foresee circumstances where your scripts may also prefer to do this (i.e. where you want the product type to be in a variable). In that case you can use the generic functions below:

• addProduct(what)
• removeProduct(what)
• setProductPars(what)
• getProductPars(what)
• removeProductPar(what)

Here what is the product type, i.e. LightCurve, Spectrum etc. Any extra arguments as defined in the product-specific examples can be passed as well, e.g. myReq.setProductPars('LightCurve', binMeth='counts') is the same as myReq.setLightCurvePars(binMeth='counts')

Submitting the request

This step is very straightforward:

In[15]: ok = myReq.submit()

Note that we captured the return in a variable ok, because submit() returns a bool, telling us whether or not the job was successfully submitted. If this is True you can jump to the pages about cancelling the job, querying its status, or downloading the data. Or you can have a look at the data returned by the server if you are curious about that.

But, submission isn't always OK. Indeed, in the case illustrated just here, submission failed, and I want to know why:

In [16]: print(ok)
False
In [17]: print(myReq.submitError)
The request is not ready to submit:

The following problems were found:
* Global parameter `centroid` is not set.
* Global parameter `name` is not set.
* Global parameter `useSXPS` is not set.
* Global parameter `RA` is not set, and nor is the alternative: `getCoords`.
* Global parameter `Dec` is not set, and nor is the alternative: `getCoords`.
* Global parameter `targ` is not set, and nor is the alternative: `getTargs`.

Ah, yes, that would explain it. I forgot to set a bunch of parameters. In this particular case the request submission failed before python even tried to submit it to the server, because some internal checks are done before submission. You can do these checks yourself before running submit() if you want, via the isValid() function. This takes one (optional) argument, which is either 'all' (the default) or a list/tuple of products to check. It returns a list with two entries: first a bool indicating whether the product/request is valid or not, and second a text string saying what's wrong (if it's not ready).

In [18]: status = myReq.isValid( ['LightCurve', 'Spectrum'])
In [19]: print(status[0])
False
In [20]: print(status[1])
The following problems were found:

light curve problems:
* Global parameter `centroid` is not set.

spectrum problems:
* Global parameter `centroid` is not set.

In [19]: status = myReq.isValid()
In [20]: print(status[1])
The following problems were found:
* Global parameter `centroid` is not set.
* Global parameter `name` is not set.
* Global parameter `useSXPS` is not set.
* Global parameter `RA` is not set, and nor is the alternative: `getCoords`.
* Global parameter `Dec` is not set, and nor is the alternative: `getCoords`.
* Global parameter `targ` is not set, and nor is the alternative: `getTargs`.

light curve problems:
* Global parameter `centroid` is not set.

spectrum problems:
* Global parameter `centroid` is not set.

Note if you supply a product/list of products then the global variables as a whole are not checked. Some globals are only needed by certain products and these will be checked (hence centroid being listed above), but the entire set of shared globals is not. To check that your request is ready to submit you should use isValid('all') (or just isValid()). The submit() function does this internally before trying to submit the job.

Note 2 even if isValid() returns True, request submission can still fail. For example, I created this request with the userID: 'YOUR_EMAIL_HERE'. This is a) not a valid email address and b) not registered with the service. So although the Python module will submit the request to the UKSSDC servers, those servers will reject it. Such a failure is handled in the same way as in these examples: myReq.submit() will return false and myReq.submitError will contain a textual description of the problem.

Advanced submission notes

submit() has an optional parameter, updateProds, which defaults to True. If this is True then the parameters in your request will be updated to those which the server returned. Normally, this doesn't affect you at all, since you can't change the parameters after submission, nor do you need them. So why does this happen?

When you submit a request, you don't have to supply every possible parameter, many of them have default values. And some parameters ask the server to calculate other values: for example if getCoords is True then the server will try to resolve the supplied name, to get the position. You may want to know what values the server actually used, either for sanity checking (is the resolved position what you were expecting?) or so that you can submit a later job with the same set of parameters.

Of course, you can find this out by looking at the data returned by the server, but you then have to manage those data yourself. On the other hand, as discussed in Advanced usage, we provide a simple mechanism to dump the parameters and values from one request and paste them into another: this is useful if you want to create a similar / identical request (for example, to update a product every time it is re-observed, without changing any of the parameters). For this case, it is helpful to have your request parameters updated to include those set by the server, so that if you dump or copy those parameters you know that you are copying the exact parameters. Since changing the product parameters after submission has no effect on the running jobs (and indeed, you can't manually change parameters after submission), this option is True by default, For more infomration see Advanced usage.

Configurable parameters

Above we have explained how to create an XRTProductRequest object and submit the request to the servers to create an actual product-build job. Below we list all of the different parameters that can be set. These come in specific groups:

• XRTProductRequest parameters
• Global parameters
• Product-specific parameters.

The first set are parameters directly related to the Python object you have created, rather than to the products requested. The global parameters are not tied to any specific product but affect all products. The product-specific parameters are, as the name implies, tied to specific parameters.

Most fields are self-explanatory. Times can be entered in any of the formats specified in the XRT Products documentation. the useObs fields can contain either a list of Swift obsIDs, or a comma-separated list of start-stop values, where start/stop are times in the formats just described.

All parameter names are case-sensitive

XRTProductRequest parameters

These parameters relate to the Python object you have created (i.e. myReq in the above). They are set/read by accessing them directly as variables, e.g. myReq.silent=False. Parameter names are case-sensitive

Parameters marked with * are only set when you submit your request. Some parameters will only be set if the submission is (un)successful.

There are also variables for each product you have requested, e.g. myReq.LightCurve, myReq.Spectrum etc. These are intended to be access only to copy products from one request to another, as described in Miscellaneous methods and advanced usage.

Global parameters:

Global parameters are set/retrieved with the setGlobalPars() and getGlobalPars() (described above). All possible global paramters are given in the table below. Parameter names are case-sensitive

*: The targetID(s) must be supplied; these tell the server which sets of data to include in your products, and it can be a comma-separated list if more than one targetID corresponds to your object. You can either supply the targetIDs in the targ field, or set getTargs=True. In the latter case, the server will select all targetIDs in the database where the object name matches that in the name field, and targets in the database where the XRT field of view will overlap the position in the (RA, Dec) fields. If getCoords=True then the targetID determination is carried out after the name has been resolved into a position.

**: A start time is not mandatory, but is helpful, particularly to zero the time axis on light curve, but it can also be used as a reference point for all other input times. You can either supply it in the T0 field, or set getT0=True. In the latter case the server will try to work it out, either as the trigger time (if the object is a GRB), or as the start time of the first observation of the object. In this case T0 will be set in the data returned by the server

***: Coordinates must be supplied. You can either supply these directly using the RA and Dec fields, or you can set getCoords=True. In the latter case the server will attempt to resolve the name (using SIMBAD). If resolving fails, your submission will fail. If it succeeds, the RA and Dec fields will be set in the data returned by the server.

**** Super-soft sources tend to be more strongly affected by pile up, and at lower fluxes than normal sources. Setting sss=True will cause the light curves and spectra to be created using grade 0 events only, and sets wtpuprate and pcpuprate to lower default values.

Light curve parameters

Light curve parameters are set/retrieved with the setLightCurvePars() and getLightCurvePars() (described above). All possible light curve parameters are given in the table below. Parameter names are case-sensitive

Some of the light curve parameters are relevant for all binning methods, some only for specific ones.

For all light curve types

For ‘counts’ binning

‘Counts’ binning is where a bin requires a certain number of counts to be considered complete (unless it spans the maximum inter-observation gap). This is the binning method used by the XRT GRB light curve repository.

For fixed-time binning

Spectrum parameters

Spectrum parameters are set/retrieved with the setSpectrumPars() and getSpectrumPars() (described above). All possible spectrum parameters are given in the table below. Parameter names are case-sensitive

Some parameters are relevant all the time, some are only needed if you are definining time-slices for your spectra.

For all spectra

The last 3 parameters were newly introduced in v1.10 of the module (part of swifttools v3.0) and represent functionality recently added to the service and also available via the website. If galactic is True, the value of the Galactic component is taken from Willingale et al., (2013). The models parameter is case-insensitive and if it contains multiple elements then multiple models will be fitted. Note Specifying multiple models will give separate fits with the different emisssion models. i.e. If you supply models=('apec', 'blackbody') then you will get two fits, an absorbed APEC and an absorbed blackbody. You will not get an absorbed "APEC+blackbody".

If defining specific sub-spectra

If timeslice=="user" then you must define the spectra you wish to create, giving each one a label (alphanumeric characters only) and a GTI interval, as defined in the product generator documentation. You can specify between 1 and 4 spectra, using these parameters:

Position parameters

There are three types of position: Standard, Enhanced and Astrometric.

Most of the position-related parameters are shared by these positions so only set once. If you have requested more than one position and change one of these 'shared' parameters for any of them, it will affect all of them.

There is also a parameter for the astrometric position only:

The reason for this parameter is that both the standard and enhanced positions tend to become systematics-limited relatively quickly (unless the source is very faint) so for speed reasons one may choose not to use all data. However the astrometric position relies on matching serendipitous X-ray sources with 2MASS sources, and so the systematics are strongly affected by how many X-ray sources were found. Thus, including all available data for the astrometric position can make a big difference.

Image parameters

The following parameters can be set for creating an image.

Source detection parameters

When requesting source detection and no other products you do not need to set the global parameters RA, Dec, centroid or useSXPS, since these have no meaning for source detection.

The parameters below can be set for source detection. Note that whichData is mandatory unlike for other products. This is because the setting this parameter to all should only be done consciously, and cautiously: requesting source detection over a large number of datasets can take longer than the 12 hour runtime limit this facility supports. Instead, we encourage you to identify which datasets you want to use for source detection, and set the useObs parameter accordingly (which whichData='user').

UK Swift Science Data Centre
Last updated 2024 May 24
Web page maintained by Vatsalya Maddi
E-mail: swift help
Please read our privacy notice.