swifttools.ukssdc
module.Quick links: Usage policy | xrt_prods
| data
| query
| ChangeLog | Set of Jupyter notebooks
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.
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
swifttools.ukssdc.query
swifttools.ukssdc.xrt_prods
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.
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.
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:
swifttools.ukssdc.data
swifttools.ukssdc.query
swifttools.ukssdc.xrt_prods
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.