Querying

The classes defined here are for querying the ATNF pulsar catalogue and viewing the resulting information.

class QueryATNF(params=None, condition=None, psrtype=None, assoc=None, bincomp=None, exactmatch=False, sort_attr='jname', sort_order='asc', psrs=None, include_errs=True, include_refs=False, adsref=False, loadfromfile=None, loadquery=None, loadfromdb=None, cache=True, checkupdate=False, circular_boundary=None, coord1=None, coord2=None, radius=0.0, frompandas=None, fromtable=None, version='latest')[source]

Bases: object

A class to generate a query of the ATNF pulsar catalogue. By default, this class will download and cache the latest version of the catalogue database file. The catalogue can be queried for specificpulsar parameters and for specific named pulsars. Conditions on the parameter can be specified. The results will be stored as a pandas.DataFrame, but can also be accessed as an astropy.table.Table.

Parameters:
  • params (str, list) – a list of strings with the pulsar parameters to query. The parameter names are case insensitive. If this is not given, then all parameters will be returned by default.

  • condition (str) – a string with logical conditions for the returned parameters. The allowed format of the condition string is given here. Defaults to None.

  • psrtype (str, list) – a list of strings, or single string, of conditions on the type of pulsars to return (logical AND will be used for any listed types). Defaults to None.

  • assoc (list, str) – a condition on the associations of pulsars to return (logical AND will be used for any listed associations). Defaults to None.

  • bincomp (str, list) – a list of strings, or single string, of conditions on the binary companion types of pulsars to return (logical AND will be used for any listed associations). Defaults to None.

  • exactmatch (bool) – a boolean stating whether associations and types given as the condition should be an exact match. Defaults to False.

  • sort_attr (str) – the (case insensitive) parameter name on which with sort the returned pulsars. Defaults to JName.

  • sort_ord (str) – the order of the sorting, can be either asc or desc. Defaults to ascending.

  • psrs (list) – a list of pulsar names for which to get the requested parameters. Defaults to None.

  • circular_boundary (list, tuple) – a list containing three entries defining the centre (in right ascension and declination), and radius of a circle in which to search for and return pulsars. The first entry is the centre point right ascension as a string in format ‘hh:mm:ss’, the second entry is the centre point declination as a string in format ‘dd:mm:ss’, and the final entry is the circle’s radius in degrees. This condition will only be applied if viewing the results as an astropy.table.Table. Alternatively, coord1, coord2, and radius can be used.

  • coord1 (str) – a string containing a right ascension in the format (‘hh:mm:ss’) that centres a circular boundary in which to search for pulsars (requires coord2 and radius to be set).

  • coord2 (str) – a string containing a declination in the format (‘dd:mm:ss’) that centres a circular boundary in which to search for pulsars (requires coord1 and radius to be set).

  • radius (float) – the radius (in degrees) of a circular boundary in which to search for pulsars (requires coord1 and coord2 to be set).

  • include_errs (bool) – Set if wanting parameter errors to be returned. Defaults to True.

  • include_refs (bool) – Set if wanting to include references tags in the output tables. Defaults to False.

  • adsref (bool) – Set if wanting to use an ads.search.SearchQuery to get reference information. Defaults to False.

  • loadfromdb (str) – Load a pulsar database file from a given path rather than using the ATNF Pulsar Catalogue database. Defaults to None.

  • loadquery (str) – load an instance of QueryATNF from the given file, rather than performing a new query. This was loadfromfile in earlier versions, which still works but has been deprecated. Defaults to None.

  • cache (bool) – Cache the catalogue database file for future use. This is ignored if loadfromdb is given. Defaults to True.

  • checkupdate (bool) – If True then check whether a cached catalogue file has an update available, and re-download if there is an update. Defaults to False.

  • 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.

  • frompandas (pandas.DataFrame) – create a new psrqpy.QueryATNF object from an existing pandas.DataFrame.

  • fromtable (astropy.table.Table) – create a new psrqpy.QueryATNF object from an existing astropy.table.Table.

as_array()[source]
Returns:

the output table as an array.

Return type:

ndarray

property catalogue

Return the entire stored DataFrame catalogue without any sorting or conditions applied.

property catalogue_len

The length of the entire catalogue, i.e., the number of pulsars it contains. This should be the same as catalogue_nrows.

property catalogue_ncols

The number of columns in the entire catalogue, i.e. the number of parameters it contains.

property catalogue_nrows

The number of rows in the entire catalogue, i.e. the number of pulsars it contains.

property catalogue_shape

The shape of the entire catalogue table as a tuple containing the number of rows and the number of columns.

property catalogue_table

Return the full catalogue as a astropy.table.Table without any query conditions applied.

Note: in this returned table any references will not be converted into actual reference strings, but will still be the ATNF Pulsar Catalogue tags.

property columns

Return the table column names.

property condition

Return the string of logical conditions applied to the pulsars.

property dataframe

Return the query table as a pandas.DataFrame.

define_dist()[source]

Set the DIST and DIST1 parameters using other values.

define_galactic()[source]

Calculate the galactic longitude, latitude and position.

Note

The cartesian galactic coordinates returned by this function do not match those returned by the ATNF Pulsar Catalogue and the psrcat software. They are defined using the conventions in the astropy.coordinates.Galactocentric class. This uses a Galactic centre distance of 8.3 kpc compared to 8.5 kpc in psrcat and rotated 90 degrees anticlockwise compared to psrcat.

The Galactic coordinate proper motions returned by this function do not match those returned by the ATNF Pulsar Catalogue and the psrcat software. The values returned here convert the observed proper motions in right ascension and declination (or elliptic longitude and latitude) into equivalent values in the Galactic coordinate system (via the astropy.coordinates.Galactic class). However, the values returned by the ATNF Pulsar Catalogue and the psrcat software are in the Galactic cooridinate system, but additionally have the local solar system velocity and Galactic rotation of the pulsar removed from them as described in Section 3 of Harrison, Lyne & Anderson (1993).

derived_age()[source]

Calculate the characteristic age in years (see characteristic_age(), with an assumed braking index of n=3).

derived_age_i()[source]

Calculate the characteristic age (in years), dervied from period and intrinsic period derivative.

derived_b_lc()[source]

Calculate the magnetic field strength at the light cylinder.

derived_binary()[source]

Calculate derived binary system parameters.

derived_bsurf()[source]

Calculate the surface magnetic field strength (see B_field()).

derived_bsurf_i()[source]

Calculate the surface magnetic field strength, dervied from period and intrinsic period derivative.

derived_ecliptic()[source]

Calculate the ecliptic coordinates, and proper motions, from the right ascension and declination if they are not already given. The ecliptic used here is the astropy’s BarycentricMeanEcliptic (note that this does not include nutation unlike the BarycentricTrueEcliptic for which a bug fix was added in astropy 3.2), which may not exactly match that used in psrcat.

derived_edot()[source]

Calculate the spin-down luminosity.

derived_edot_i()[source]

Calculate the spin-down luminosity, dervied from period and intrinsic period derivative.

derived_edotd2()[source]

Calculate the spin-down luminosity flux at the Sun.

derived_equatorial()[source]

Calculate equatorial coordinates if only ecliptic coordinates are given. Errors on ecliptical coordinates are converted into equavalent errors on equatorial coordinates using a different algorithm to that used in psrcat.

derived_f0()[source]

Calculate the frequency from the period in cases where frequency is not given.

derived_f1()[source]

Calculate the frequency derivative from the period derivative in cases where frequency derivative is not given.

derived_fb0()[source]

Calculate orbital frequency from orbital period.

derived_fb1()[source]

Calculate the orbital frequency derivative from the binary orbital period derivative.

derived_flux()[source]

Calculate spectral index between 400 and 1400 MHz and radio flux at 400 and 1400 MHz.

derived_gw_h0_spindown_limit()[source]

Calculate the limit on the gravitational-wave emission amplitude at Earth assuming all rotational kinetic energy is lost via gravitational-waves generated from an l=m=2 mass quadrupole (i.e., a braking index of n=5). This uses the intrinsic spin-down values rather than the observed spin-downs.

derived_p0()[source]

Calculate the period from the frequency in cases where period is not given.

derived_p1()[source]

Calculate the period derivative from the frequency derivative in cases where period derivative is not given.

derived_p1_i()[source]

Calculate the intrinsic period derivative.

derived_pb()[source]

Calculate binary orbital period from orbital frequency.

derived_pbdot()[source]

Calculate binary orbital period derivative from orbital frequency derivative.

derived_pmtot()[source]

Calculate the total proper motion and error.

derived_vtrans()[source]

Calculate the transverse velocity.

property empty

Return True if the pandas.DataFrame containing the catalogue is empty.

property exactmatch

Return the boolean stating whether certain conditions should apply an exact match.

get_catalogue(path_to_db=None, cache=True, update=False, overwrite=True, version='latest')[source]

Call the psrqpy.utils.get_catalogue() function to download the ATNF Pulsar Catalogue, or load a given catalogue path.

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.

  • overwrite (bool) – if True the returned catalogue will overwrite the catalogue currently contained within the QueryATNF class. If False then a new QueryATNF copy of the catalogue will be returned.

  • 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 catalogue.

Return type:

psrqpy.QueryATNF

get_ephemeris(psr, precision=15, selected=False)[source]

Return the table row for a particular pulsar and output it as an ephemeris-style string output.

Parameters:
  • psr (str) – The name of a pulsar to return.

  • precision (int) – The precision (number of decimal places) at which to output numbers. Defaults to 15.

  • selected (bool) – If True only output the parameters specified by query_params(), otherwise output all parameters. Defaults to False.

Returns:

an ephemeris

Return type:

str

get_pulsar(psr, selected=False)[source]

Return the table row for a particular pulsar for all the catalogue parameters.

Parameters:
  • psr (str) – The name of a pulsar to return.

  • selected (bool) – If True then output return a table row containing parameters specified by query_params(), otherwise return all parameters. Defaults to False.

Returns:

a table row

Return type:

astropy.table.Table

get_pulsars()[source]
Returns:

the queried pulsars returned as a Pulsars object, which is a dictionary of Pulsar objects.

Return type:

psrqpy.pulsar.Pulsars

get_references(useads=False, cache=True)[source]

Get a dictionary of short reference tags keyed to the full reference string. If requested also get a dictionary of reference tags keyed to NASA ADS URLs for the given reference. This uses the function psrqpy.utils.get_references().

Parameters:
  • useads (bool) – Set this to True to get the NASA ADS reference URLs. Defaults to False.

  • cache (bool) – The flag sets whether or not to use a pre-cached database of references. Defaults to True.

property get_version

Return a string with the ATNF version number, or None if not found.

Returns:

the ATNF version number.

Return type:

str

gw_ellipticity()[source]

Return the \(l=m=2\) mass quadrupoles based on the spin-down limits for the pulsars in the catalogue using h0_to_ellipticity().

Returns:

a table containing PSRJ names and

\(\varepsilon\) values as a column called ELL.

Return type:

astropy.table.Table

gw_mass_quadrupole()[source]

Return the \(l=m=2\) mass quadrupoles based on the spin-down limits for the pulsars in the catalogue using h0_to_q22().

Returns:

a table containing PSRJ names and

\(Q_{22}\) values as a column called Q22.

Return type:

astropy.table.Table

property include_errs

Return a boolean stating whether errors are to be included.

load(fname, cleardfonly=False)[source]

Load a previously saved pickle of this class.

Parameters:
  • fname (str) – the filename of the pickled object

  • cleardfonly (bool) – set to True to only clear the catalogue DataFrame from the current object, but leave other attributes intact.

property num_pulsars

Return the number of pulsars found in with query

property pandas

Return the query table as a pandas.DataFrame.

parse_assoc()[source]

Parse default string representing source associations, extracting (first) value and reference. Multiple values and references currently not supported.

parse_bincomp()[source]

Parse default string representing source companion type, extracting (first) value and reference. Multiple values and references currently not supported.

parse_conditions(psrtype=None, assoc=None, bincomp=None)[source]

Parse a string of conditions, i.e., logical statements with which to apply to a catalogue query, e.g., condition = 'f0 > 2.5 && assoc(GC)', so that they are in the format required for the query URL.

Parameters:
  • psrtype (list, str) –

    a list of strings, or single string, of conditions on the type of pulsars to return (logical AND will be used for any listed types)

  • assoc (list, str) – a list of strings, or single string, of conditions on the associations of pulsars to return (logical AND will be used for any listed associations)

  • bincomp (list, str) – a list of strings, or single string, of conditions on the binary companion types of pulsars to return (logical AND will be used for any listed associations)

  • exactmatch (bool) – a boolean stating whether assciations and types given as the condition should be an exact match

Returns:

a string with the format required for use in QUERY_URL

Return type:

str

parse_ref(refs, useads=False)[source]

This function takes a short format reference string from the ATNF Pulsar Catalogue and returns the full format reference. It can also return a NASA ADS URL if requested and present.

Parameters:
  • refs (str, array_like) – a single short reference string, or an array of reference strings.

  • useads (bool) – Set whether or not to also return a NASA ADS reference URL if present.

Returns:

a single full reference string, or an array of full reference strings. If NASA ADS URLs are requested, each return value will be a tuple containing the reference string and URL.

Return type:

array_like

parse_type()[source]

Parse default string representing source type, extracting (first) value and reference. Multiple values and references currently not supported.

parse_types()[source]

Parse information in ‘ASSOC’, ‘TYPE’, and ‘BINCOMP’, as described in http://www.atnf.csiro.au/research/pulsar/psrcat/psrcat_help.html#psr_types.

ppdot(intrinsicpdot=False, excludeGCs=False, showtypes=[], showGCs=False, showSNRs=False, markertypes={}, deathline=True, deathmodel='Ip', filldeath=True, filldeathtype={}, showtau=True, brakingidx=3, tau=None, showB=True, Bfield=None, pdotlims=None, periodlims=None, usecondition=True, usepsrs=True, rcparams={})[source]

Draw a lovely period vs period derivative diagram.

Parameters:
  • intrinsicpdot (bool) – use the intrinsic period derivative corrected for the Shklovskii effect rather than the observed value. Defaults to False.

  • excludeGCs (bool) – exclude globular cluster pulsars as their period derivatives can be contaminated by intra-cluster accelerations. Defaults to False.

  • showtypes (list, str) – a list of pulsar types to highlight with markers in the plot. These can contain any of the following: BINARY, HE, NRAD, RRAT, XINS, AXP or SGR, or ALL to show all types. Default to showing no types.

  • showGCs (bool) – show markers to denote the pulsars in globular clusters. Defaults to False.

  • showSNRs (bool) – show markers to denote the pulsars with supernova remnants associated with them. Defaults to False.

  • markertypes (dict) – a dictionary of marker styles and colors keyed to the pulsar types above

  • deathline (bool) – draw the pulsar death line. Defaults to True.

  • deathmodel (str) – the type of death line to draw based on the models in psrqpy.utils.death_line(). Defaults to 'Ip'.

  • filldeath (bool) – set whether to fill the pulsar graveyard under the death line. Defaults to True.

  • filldeathtype (dict) – a dictionary of keyword arguments for the fill style of the pulsar graveyard.

  • showtau (bool) – show lines for a selection of characteritic ages. Defaults to True, and shows lines for \(10^5\) through to \(10^9\) yrs with steps in powers of 10.

  • brakingidx (int) – a braking index to use for the calculation of the characteristic age lines. Defaults to 3 for magnetic dipole radiation.

  • tau (list) – a list of characteristic ages to show on the plot.

  • showB (bool) – show lines of constant magnetic field strength. Defaults to True, and shows lines for \(10^{10}\) through to \(10^{14}\) gauss with steps in powers of 10.

  • Bfield (list) – a list of magnetic field strengths to plot.

  • periodlims (array_like) – the [min, max] period limits to plot with

  • pdotlims (array_like) – the [min, max] pdot limits to plot with

  • usecondition (bool) – if True create the P-Pdot diagram only with pulsars that conform to the original query condition values. Defaults to True.

  • usepsrs (bool) – if True create the P-Pdot diagram only with pulsars specified in the original query. Defaults to True.

  • rcparams (dict) – a dictionary of matplotlib.rcParams setup parameters for the plot.

Returns:

the figure object

Return type:

matplotlib.figure.Figure

property psrs

Return the name(s) of particular pulsars asked for in the query.

property query_params

Return the parameters required for the query.

query_table(query_params=None, usecondition=True, usepsrs=True, useseparation=True)[source]

Return an astropy.table.Table from the query with new parameters or conditions if given.

Parameters:
  • query_params (str, list) – a parameter, or list of parameters, to return from the query. If this is None then all parameters are returned.

  • usecondition (bool, str) – If True then the condition parsed to the psrqpy.QueryATNF: class will be used when returning the table. If False no condition will be applied to the returned table. If a string is given then that will be the assumed condition string.

  • usepsrs (bool, str) – If True then the list of pulsars parsed to the psrqpy.QueryATNF: class will be used when returning the table. If False then all pulsars in the catalogue will be returned. If a string, or list of strings, is given then that will be assumed to be a set of pulsar names to return.

  • useseparation (bool) – If True and a set of sky coordinates and radius around which to return pulsars was set in the psrqpy.QueryATNF: class then only pulsars within the given radius of the sky position will be returned. Otherwise all pulsars will be returned.

Returns:

a table of the pulsar data returned by the query.

Return type:

astropy.table.Table

save(fname)[source]

Output the QueryATNF instance to a pickle file for future loading.

Parameters:

fname (str) – the filename to output the pickle to

set_derived()[source]

Compute any derived parameters and add them to the class.

These calculations are based on those in the readCatalogue.c and defineParameters.c files from the PSRCAT code.

sort(sort_attr='JNAME', sort_order='asc', inplace=False)[source]

Sort the generated catalogue DataFrame on a given attribute and in either ascending or descending order.

Parameters:
  • sort_attr (str) – The parameter on which to perform the sorting of the query output. Defaults to ‘JNAME’.

  • sort_order (str) – Set to ‘asc’ to sort the parameter values in ascending order, or ‘desc’ to sort in descending order. Defaults to ascending.

  • inplace (bool) – If True, and sorting the class’ internal DataFrame, then the sorting will be done in place without returning a copy of the table, otherwise a sorted copy of the table will be returned.

Returns:

a table containing the sorted catalogue.

Return type:

DataFrame

property table

Return a astropy.table.Table based on the query.

update(column, name=None, overwrite=False)[source]

Update a column in the internal pandas.DataFrame table using pandas.DataFrame.update(). If the column does not exist, it will be added to the table.

Parameters:
  • column (pandas.Series) – a named column of values.

  • name (str) – the name of the column (required if column is not a pandas.Series, or to overwrite the current column name)

  • overwrite (bool) – set whether to overwrite non-NA values or not if the column already exists. Defaults to False, so non-NA values will not be overwritten.