The `swifttools.ukssdc` module.

Quick start

If you just want to get straight into using this and only read the documentation when you really have to, then I would recommend you read the summary section below and skim details of the 3 main packages, via the pages in the quick links above. When you need more detail, or if you prefer to get a good handle before starting, then read through this page and follow the links through to the section(s) of interest.

I am hoping to add a page of examples as well, soon, to get you started.

Summary

The swifttools.ukssdc module was added in v3.0 of swifttools and adds significant new functionality. This includes, for example, the much-requested ability to query a GRB catalogue to find all bursts meeting your criteria, and then download all of the XRT light curves for those object.

The module contains three parts:

swifttools.ukssdc.data: Tools to directly access data; for where you know what you are looking for (so not much help for Bono).
swifttools.ukssdc.query: Tools to query various catalogues, in order to determine what it is you're looking for (more helpful for Bono).
swifttools.ukssdc.xrt_prods: Tools to build XRT data analysis products. This module was formerly swifttools.xrt_prods.

For convenience and consistency, in all documentation and demonstration we import these with short-cut names as follows:

In [1]: import swifttools.ukssdc.data as ud
In [2]: import swifttools.ukssdc.data as uq
In [3]: import swifttools.ukssdc.xrt_prods as ux

with extensions to these for sub-packages which we will cover on the relevant pages. The quick links at the top of this page will take you to the top-level documentation of each of these main packages.

In addition to the above there are some functions common to the whole module which are usually (but not always) called via the above modules.

These modules make substantial use of the standard pandas package, and particularly the DataFrame. Familiarity with these may be of benefit, but throughout this documentation I will demonstrate the key behaviour as and when needed. I have not made astropy a dependency of this module, but if you do have it available then you gain a few extra features (noted inline again) such as the ability to pass coordinates as astropy objects to some functions. If you're likely to use this module interactively, e.g. in Jupyter notebooks, then installing the tqdm module will also make downloading data look prettier.

There are two arguments which are common to almost every function in this module: silent and verbose (swifttools.ukssdc.xrt_prods has only silent). These control how much information is written to the standard output. By default, almost nothing is written except for error messages. Setting silent=False will give some informative output, and verbose=True (which implies silent=False) will give lots of output. The demarcation between non-silent, and verbose output is somewhat arbitrary.

Usage

This Python module is provided free to use, but if you use it for work leading to a publication, please do acknowledge this with a footnote pointing to (https://www.swift.ac.uk/API). The standard usage policy for any of the tools accessed via the API remains in force as well. That is, please incude this in your acknowledgements:

This work made use of data supplied by the UK Swift Science Data Centre at the University of Leicester.

and cite the appropriate paper(s) relating to the data source or algorithms you accessed through the API. Details for each of these can be found on their relevant pages; below are links to those pages and the citations requested.

GRB light curves: Evans et al., (2007), Evans et al., (2009)
GRB enhanced positions: Goad et al., (2007), Evans et al., (2009)
GRB spectra: Evans et al., (2009)
The burst analyser: Evans et al., (2010)
On-demand products: Evans et al., (2009): please see the documentation for citations for the different products.
2SXPS: Evans et al., (2020)
LSXPS: Evans et al., (2023)

About this documentation

The documentation for this Python module is organised by package and sub-package as given in the contents list below. Many of the documentation pages can also be downloaded as Jupyter notebooks, so you can actually execute the example code and experiment with it. Links to the notebooks appear at the top of each page, and a zip archive of all of them is available.

Documentation contents:

Docstrings, PEP8 and so on.

All functions should be fully documented via PEP 257-compliant docstrings, so the help command can be used to obtain full details. If you find something missing or inaccurate, you can open an issue on our GitHub page or just email me (swifthelp@leicester.ac.uk).

While efforts have been made to ensure that the code is PEP8 compliant, eagle-eyed users will notice that function names in this module are of the form someFunction(), rather than the some_function() preferred by PEP8. This is partly simply due to me not reading PEP8 closely enough, but also justified in my entirely objective and not remotely biased view but the note in PEP8 which says:

mixedCase is allowed only in contexts where that’s already the prevailing style (e.g. threading.py), to retain backwards compatibility.

And since all my backend code uses mixedCase, this is clearly a totally acceptable decision 😛. And anyway, the recommended convention is really ugly compared to mixedCase…

More seriously, this issue was only brought to my attention some years after the xrt_prods module was first produced, and so given the choices of breaking everyone's existing scripts, having a mixtured of styles, or just sticking with mixedCase everywhere, the latter really was a no-brainer.

If you find other operational or pythonic issues apart from this convention, feel free to ping me or (if it impacts usability) to open an issue, as above.

The swifttools.ukssdc module.