# Utility functions¶

A selection of useful functions used by the module.

B_field(period, pdot)

Function defining the polar magnetic field strength at the surface of the pulsar in gauss (Equation 5.12 of Lyne & Graham-Smith, Pulsar Astronmy, 2nd edition) with

$B = 3.2\!\times\!10^{19} \sqrt{P\dot{P}}$

NaNs are returned for any negative period derivates, or NaN imput values.

Parameters: period (float) – a pulsar period (s) pdot (float) – a period derivative the magnetic field strength in gauss. float
B_field_pdot(period, Bfield=10000000000.0)

Function to get the period derivative from a given pulsar period and magnetic field strength using

$\dot{P} = \frac{1}{P}\left( \frac{B}{3.2\!\times\!10^{19}} \right)^2$
Parameters: period (list, ndarray) – a list of period values Bfield (float) – the polar magnetic field strength (Defaults to $$10^{10}$$ G) an array of period derivatives numpy.ndarray
age_pdot(period, tau=1000000.0, braking_idx=3.0)

Function returning the period derivative for a pulsar with a given period and characteristic age, using

$\dot{P} = \frac{P}{\tau(n - 1)}$
Parameters: period (list, numpy.ndarray) – the pulsar period in seconds tau (float) – the characteristic age in years braking_idx (float) – the pulsar braking index (defaults to $$n=3$$) an array of period derivatives. numpy.ndarray
characteristic_age(period, pdot, braking_idx=3.0)

Function defining the characteristic age of a pulsar. Returns the characteristic age in years using

$\tau = \frac{P}{\dot{P}(n-1)}$

NaNs are returned for any negative period derivates, or NaN imput values.

Parameters: period (float, array_like) – the pulsar period in seconds pdot (float, array_like) – the pulsar period derivative braking_idx (float) – the pulsar braking index (defaults to $$n=3$$) the characteristic age in years float
check_update()

Check if the ATNF Pulsar Catalogue has been updated compared to the version in the cache.

Returns: True if the cache can be updated. bool
condition(table, expression, exactMatch=False)

Apply a logical expression to a table of values.

Parameters: table (astropy.table.Table or pandas.DataFrame) – a table of pulsar data expression (str, ndarray) – a string containing a set of logical conditions with respect to pulsar parameter names (also containing conditions allowed when accessing the ATNF Pulsar Catalogue), or a boolean array of the same length as the table. exactMatch (bool) – set to true to exactly match some string comparison expressions, e.g., if asking for ‘ASSOC(SNR)’ and exactMatch is True then only pulsar with an association that is just ‘SNR’ will be returned, whereas if it is False then there could be multiple associations including ‘SNR’. the table of values conforming to the input condition. Depending on the type of input table the returned table will either be a astropy.table.Table or pandas.DataFrame.

Example

Some examples of this might are:

1. finding all pulsars with frequencies greater than 100 Hz
>>> newtable = condition(psrtable, 'F0 > 100')


2. finding all pulsars with frequencies greater than 50 Hz and period derivatives less than 1e-15 s/s.

>>> newtable = condition(psrtable, '(F0 > 50) & (P1 < 1e-15)')

1. finding all pulsars in binary systems
>>> newtable = condition(psrtable, 'TYPE(BINARY)')

1. parsing a boolean array equivalent to the first example
>>> newtable = condition(psrtable, psrtable['F0'] > 100)

death_line(logP, linemodel='Ip', rho6=1.0)

The pulsar death line. Returns the base-10 logarithm of the period derivative for the given values of the period.

Parameters: logP (list, ndarray) – the base-10 log values of period. linemodel (str) – a string with one of the above model names. Defaults to 'Ip'. rho6 (float) – the value of the $$\rho_6$$ parameter from [ZHM] . Defaults to 1 is, which is equivalent to $$10^6$$ cm. a vector of period derivative values numpy.ndarray

Note

The death line models can be:

• ‘I’ - Equation 3 of [ZHM]
• ‘Ip’ - Equation 4 of [ZHM]
• ‘II’ - Equation 5 of [ZHM]
• ‘IIp’ - Equation 6 of [ZHM]
• ‘III’ - Equation 8 of [ZHM]
• ‘IIIp’ - Equation 9 of [ZHM]
• ‘IV’ - Equation 10 of [ZHM]
• ‘IVp’ - Equation 11 of [ZHM]
 [ZHM] Zhang, Harding & Muslimov, ApJ, 531, L135-L138 (2000), arXiv:astro-ph/0001341
get_catalogue(path_to_db=None, cache=True, update=False, pandas=False)

This function will attempt to download and cache the entire ATNF Pulsar Catalogue database tarball, or read in database file from a provided path. The database will be converted into an astropy.table.Table or pandas.DataFrame. This was originally based on the method in the ATNF.ipynb notebook by Joshua Tan (@astrophysically).

Parameters: path_to_db (str) – if the path to a local version of the database file is given then that will be read in rather than attempting to download the file (defaults to None). cache (bool) – cache the downloaded ATNF Pulsar Catalogue file. Defaults to True. This is ignored if path_to_db is given. update (bool) – if True the ATNF Pulsar Catalogue will be re-downloaded and cached if there has been a change compared to the currently cached version. This is ignored if path_to_db is given. pandas (bool) – if True the catalogue will be returned as a pandas.DataFrame rather than the default of an Table. a table containing the entire catalogue.
get_glitch_catalogue(psr=None)

Return a Table containing the Jodrell Bank pulsar glitch catalogue. If using data from the glitch catalogue then please cite Espinoza et al. (2011) and the URL http://www.jb.man.ac.uk/pulsar/glitches.html.

The output table will contain the following columns:

• NAME: the pulsars common name
• JNAME: the pulsar name based on J2000 coordinates
• Glitch number: the number of the glitch for a particular pulsar in chronological order
• MJD: the time of the glitch in Modified Julian Days
• MJD_ERR: the uncertainty on the glitch time in days
• DeltaF/F: the fractional frequency change
• DeltaF/F_ERR: the uncertainty on the fractional frequency change
• DeltaF1/F1: the fractional frequency derivative change
• DeltaF1/F1_ERR: the uncertainty on the fractional frequency derivative change
• Reference: the glitch publication reference
Parameters: psr (str) – if a pulsar name is given then only the glitches for that pulsar are returned, otherwise all glitches are returned. a table containing the entire glitch catalogue. Table

Example

An example of using this to extract the glitches for the Crab Pulsar would be:

>>> import psrqpy
>>> gtable = psrqpy.get_glitch_catalogue(psr='J0534+2200')
>>> print("There have been {} glitches observed from the Crab pulsar".format(len(gtable)))
27

get_references(*args, **kwargs)

Return a dictionary of paper reference in the ATNF catalogue. The keys are the ref strings given in the ATNF catalogue.

Note: The way that the ATNF references are stored has changed, so if you downloaded the catalogue with a version of psrqpy before v1.0.8 you may need to run this function with updaterefcache=True to allow references to work. You may also want to update the ATNF catalogue tarball with:

>>> import psrqpy
>>> psrqpy.QueryATNF(checkupdate=True)

Parameters: useads (bool) – boolean to set whether to use the python mod:ads module to get the NASA ADS URL for the references. cache (bool) – use cached, or cache, the reference bundled with the catalogue tarball. updaterefcache (bool) – update the cached references. bibtex (bool) – if using ADS return the bibtex for the reference along with the ADS URL. a dictionary of references. dict
label_line(ax, line, label, color='k', fs=14, frachoffset=0.1)

Add an annotation to the given line with appropriate placement and rotation.

Based on code from “How to rotate matplotlib annotation to match a line?” and this answer.

Parameters: ax (matplotlib.axes.Axes) – Axes on which the label should be added. line (matplotlib.lines.Line2D) – Line which is being labeled. label (str) – Text which should be drawn as the label. color (str) – a color string for the label text. Defaults to 'k' fs (int) – the font size for the label text. Defaults to 14. frachoffset (float) – a number between 0 and 1 giving the fractional offset of the label text along the x-axis. Defaults to 0.1, i.e., 10%. an object containing the label information matplotlib.text.Text