Utility functions
A selection of useful functions used by the module.
- B_field(period, pdot)[source]
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.
- B_field_pdot(period, Bfield=10000000000.0)[source]
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:
- Returns:
an array of period derivatives
- Return type:
- age_pdot(period, tau=1000000.0, braking_idx=3.0)[source]
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 secondstau (float) – the characteristic age in years
braking_idx (float) – the pulsar braking index (defaults to \(n=3\))
- Returns:
an array of period derivatives.
- Return type:
- characteristic_age(period, pdot, braking_idx=3.0)[source]
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.
- check_update()[source]
Check if the ATNF Pulsar Catalogue has been updated compared to the version in the cache.
- Returns:
True if the cache can be updated.
- Return type:
- condition(table, expression, exactMatch=False)[source]
Apply a logical expression to a table of values.
- Parameters:
table (
astropy.table.Tableorpandas.DataFrame) – a table of pulsar dataexpression (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’.
- Returns:
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.Tableorpandas.DataFrame.- Return type:
Example
Some examples of this might are:
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)')
finding all pulsars in binary systems
>>> newtable = condition(psrtable, 'TYPE(BINARY)')
parsing a boolean array equivalent to the first example
>>> newtable = condition(psrtable, psrtable['F0'] > 100)
- death_line(logP, linemodel='Ip', rho6=1.0)[source]
The pulsar death line. Returns the base-10 logarithm of the period derivative for the given values of the period.
- Parameters:
- Returns:
a vector of period derivative values
- Return type:
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
- ellipticity_to_q22(ellipticity, Izz=1e+38)[source]
Convert a fiducial ellipticity \(\varepsilon\) of the pulsar to the equivalent \(l=m=2\) mass quadrupole \(Q_{22}\) using (see Equation A3 of [LVC]):
\[Q_{22} = \varepsilon I_{zz} \sqrt{\frac{15}{8\pi}}\]- Parameters:
- Returns:
an array of \(Q_{22}\) values.
- Return type:
- fdot_to_pdot(fdot, period=None, frequency=None)[source]
Convert frequency derivatives to period derivatives. Either periods or frequencies must be supplied.
\[\dot{P} = -\frac{\dot{f}}{f^2}\]- Parameters:
- Returns:
an array of period derivatives.
- Return type:
- get_catalogue(path_to_db=None, cache=True, update=False, pandas=False, version='latest')[source]
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.Tableorpandas.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.DataFramerather than the default of anTable.version (str) – the version string (without the leading “v”) of the ATNF catalogue version to download. This defaults to “latest” to get the most up-to-date version.
- Returns:
a table containing the entire catalogue.
- Return type:
- get_gc_catalogue()[source]
Download and parse Paolo Freire’s table of pulsars in globular clusters from http://www.naic.edu/~pfreire/GCpsr.txt. This will be returned as a
astropy.table.Table, but with some additional methods to extract information for individual clusters. If the webpage returned an errorNoneis returned.The additional methods of the returned
Tableare:clusters: by default this returns a list if the common names of the globular clusters in the table, or using thengc=Trueargument will return the NGC names of all clusters.cluster_pulsars: returns a sub-table only containing pulsars within a supplied globular cluster name.
- get_glitch_catalogue(psr=None)[source]
Return a
Tablecontaining 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.
- Returns:
a table containing the entire glitch catalogue.
- Return type:
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_msp_catalogue()[source]
Download and parse Dunc Lorimer’s catalogue of galactic millisecond pulsars. This makes use of code from the now deleted galmsps respository that scraped the database into JSON every month, contributed by @astrogewgaw before deletion via PR #88.
- Returns:
a table the MSPs.
- Return type:
- get_references(useads=False, cache=True, updaterefcache=False, bibtex=False, showfails=False)[source]
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=Trueto 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.
showfails (bool) – if outputting NASA ADS references set this flag to True to output the reference tags of references that fail to be found (mainly for debugging purposes).
- Returns:
a dictionary of references.
- Return type:
- gw_h0_spindown_limit(frequency, fdot, distance, Izz=1e+38)[source]
The gravitational-wave amplutitude at Earth assuming all rotational energy loss is radiated via emission from an \(l=m=2\) mass quadrupole mode, using (see Equation A7 of [LVC])
\[h_0^{\text{sd}} = \frac{1}{d}\left(\frac{5}{2} \frac{G I_{zz}}{c^3} \frac{|\dot{f}|}{f}\right)^{1/2}\]- Parameters:
- Returns:
an array of spin-down limits.
- Return type:
- gw_luminosity(h0, frequency, distance)[source]
The gravitational-wave luminosity as derived from a given gravitatonal-wave amplitude measured at Earth, assuming all rotational energy loss is radiated via emission from an \(l=m=2\) mass quadrupole mode, using (see Equation A5 of [LVC])
\[\dot{E}_{\text{gw}} = \frac{8\pi^2c^3}{5G} f^2 h_0^2 d^2\]- Parameters:
- Returns:
an array of luminosities.
- Return type:
- h0_to_ellipticity(h0, frequency, distance, Izz=1e+38)[source]
Convert a gravitational-wave amplitude \(h_0\) at Earth to an equivalent fiducial ellipticity \(\varepsilon\) of the pulsar using (see Equation A4 of [LVC]):
\[\varepsilon = h_0 \left(\frac{c^4 d}{16\pi^2 G f^2} \right) \sqrt{\frac{15}{8\pi}}\]- Parameters:
- Returns:
an array of \(Q_{22}\) values.
- Return type:
- h0_to_q22(h0, frequency, distance)[source]
Convert a gravitational-wave amplitude \(h_0\) at Earth to an equivalent \(l=m=2\) mass quadrupole \(Q_{22}\) of the pulsar using (see Equations A3 and A4 of [LVC]):
\[Q_{22} = h_0 \left(\frac{c^4 d}{16\pi^2 G f^2} \right) \sqrt{\frac{15}{8\pi}}\]- Parameters:
- Returns:
an array of \(Q_{22}\) values.
- Return type:
- label_line(ax, line, label, color='k', fs=14, frachoffset=0.1)[source]
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%.
- Returns:
an object containing the label information
- Return type:
- pdot_to_fdot(pdot, period=None, frequency=None)[source]
Convert period derivatives to frequency derivatives. Either periods or frequencies must be supplied.
\[\dot{f} = -\frac{\dot{P}}{P^2}\]- Parameters:
- Returns:
an array of frequency derivatives.
- Return type:
- q22_to_ellipticity(q22, Izz=1e+38)[source]
Convert a \(l=m=2\) mass quadrupole \(Q_{22}\) to an equivalent fiducial ellipticity \(\varepsilon\) of the pulsar using (see Equation A3 of [LVC]):
\[\varepsilon = \frac{Q_{22}}{I_{zz}}\sqrt{\frac{8\pi}{15}}\]- Parameters:
- Returns:
an array of \(\varepsilon\) values.
- Return type: