Skip to content

Commit

Permalink
More documentation updates - refs #4
Browse files Browse the repository at this point in the history
  • Loading branch information
@mattpitkin
mattpitkin committed Nov 24, 2017
1 parent 423ecf2 commit f8c8f27
Show file tree
Hide file tree
Showing 5 changed files with 98 additions and 70 deletions.
2 changes: 0 additions & 2 deletions docs/source/config.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,5 +5,3 @@ Setup constants
.. automodule:: psrqpy.config
:members:

.. autodata:: psrqpy.config.ATNF_VERSION
:annotation: = Blah
3 changes: 0 additions & 3 deletions docs/source/pulsar.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,6 @@
Pulsars
#######

The classes defined here are hold information on an individual pulsar
or an interable list of pulsars.

.. automodule:: psrqpy.pulsar
:members:

38 changes: 23 additions & 15 deletions psrqpy/config.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,12 +5,9 @@

import itertools

#: the default ATNF version
ATNF_VERSION = '1.57'

#: the ATNF pulsar catalogue base URL
ATNF_BASE_URL = r'http://www.atnf.csiro.au/people/pulsar/psrcat/'
ATNF_URL = ATNF_BASE_URL + r'proc_form.php?version={version}'
ATNF_VERSION = '1.57' #: the default ATNF catalogue version
ATNF_BASE_URL = r'http://www.atnf.csiro.au/people/pulsar/psrcat/' #: the ATNF pulsar catalogue base URL
ATNF_URL = ATNF_BASE_URL + r'proc_form.php?version={version}' #: the ATNF pulsar catalogue base URL for queries

PARAMS_QUERY = r'{params}'
USERDEFINED_QUERY = r'&startUserDefined=true&c1_val=&c2_val=&c3_val=&c4_val='
Expand All @@ -20,6 +17,7 @@
EPHEMERIS_QUERY = r'&submit_ephemeris={getephemeris}'
QUERY_FLUFF = r'&ephemeris=long&coords_unit=raj%2Fdecj&radius=&coords_1=&coords_2=&style=Long+with+errors&no_value=*&nohead=nohead&state=query&table_bottom.x=30&table_bottom.y=22'

#: the full ATNF catalogue query URL
QUERY_URL = ATNF_URL + PARAMS_QUERY + USERDEFINED_QUERY + SORT_QUERY + CONDITION_QUERY + PSRNAMES_QUERY + EPHEMERIS_QUERY + QUERY_FLUFF

# pulsar parameters (http://www.atnf.csiro.au/research/pulsar/psrcat/psrcat_help.html) that can be queried
Expand All @@ -28,8 +26,6 @@
# - 'err': True if the parameter can have an associated error value
# - 'unit': a string giving the units for the parameter (to be used if generating an astropy table)
# - 'format': a string giving the parameter format (to be used if generating an astropy table)

#: general parameters (e.g., name, position, distance...)
PSR_GENERAL = {'NAME': {'ref': True, 'err': False, 'units': None, 'format': 'S32'}, # Pulsar name. The B name if exists, otherwise the J name.
'JNAME': {'ref': True, 'err': False, 'units': None, 'format': 'S32'}, # Pulsar name based on J2000 coordinates
'RAJ': {'ref': True, 'err': True, 'units': None, 'format': 'S32'}, # Right ascension (J2000) (hh:mm:ss.s)
Expand Down Expand Up @@ -120,11 +116,25 @@
PSR_DERIVED_PARS = PSR_DERIVED.keys()

# a list of all allowed parameters for querying

""": a dict of allowed pulsars parameters (e.g., name, position, distance...)
Each parameter name key gives a dictionary containing the keys:
* ``ref`` (bool) - True if the parameter has an associated reference with it
* ``err`` (bool) - True if the parameter has an associated error value
* ``units`` (str) - a string with the parameters units that can be parsed by
:class:`~astropy.units.core.Unit`
* ``format`` (str) - a string with a :class:`numpy.dtype` for storing the parameter in an
:class:`~astropy.table.Table`
The allowed parameters and their units are given
`here <http://www.atnf.csiro.au/research/pulsar/psrcat/psrcat_help.html?type=normal#par_list>`_.
"""
PSR_ALL = dict(itertools.chain(PSR_GENERAL.items(), PSR_TIMING.items(), PSR_BINARY.items(), PSR_DERIVED.items()))
PSR_ALL_PARS = PSR_GENERAL_PARS + PSR_TIMING_PARS + PSR_BINARY_PARS + PSR_DERIVED_PARS

# "types" of pulsar http://www.atnf.csiro.au/research/pulsar/psrcat/psrcat_help.html#psr_types
# for use in 'type()' when setting logical conditions
#: `"types" <http://www.atnf.csiro.au/research/pulsar/psrcat/psrcat_help.html#psr_types>`_ of pulsar for use in ``type()`` when setting logical conditions
PSR_TYPES = ['AXP', # Anomalous X-ray Pulsar or Soft Gamma-ray Repeater with detected pulsations
'BINARY', # Pulsar has one or more stellar companion(s)
'HE', # Spin-powered pulsar with pulsed emission from radio to infrared or higher frequencies
Expand All @@ -134,20 +144,18 @@
'XINS' # Isolated neutron stars with pulsed thermal X-ray emission but no detectable radio emission
]

# binary companion types http://www.atnf.csiro.au/research/pulsar/psrcat/psrcat_help.html?type=normal#bincomp_type
# for use in 'bincomp()' when setting logical conditions
#: binary companion `types <http://www.atnf.csiro.au/research/pulsar/psrcat/psrcat_help.html?type=normal#bincomp_type>`_ for use in ``bincomp()`` when setting logical conditions
PSR_BINARY_TYPE = ['MS', # Main-sequence star
'NS', # Neutron star
'CO', # CO or ONeMg White Dwarf
'He', # Helium White Dwarf
'UL' # Ultra-light companion or planet (mass < 0.08 solar masses)
]

# other objects associated with the pulsar (this is not an exhaustive list
# # for use in 'assoc()' when setting logical conditions)
#: other objects associated with the pulsar (this is not an exhaustive list for use in ``assoc()`` when setting logical conditions)
PSR_ASSOC_TYPE = ['GC', # globular cluster
'SNR' # supernova remnant
]

# URL for the NASA ADS
#: URL for the NASA ADS
ADS_URL = 'https://ui.adsabs.harvard.edu/#abs/{}/'
119 changes: 70 additions & 49 deletions psrqpy/search.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -456,10 +456,10 @@ def get_pulsars(self):
"""
Returns:
:class:`psrqpy.pulsar.Pulsars`: the queried pulsars returned as a
:class:`~psrqpy.pulsar.Pulsars` object, which is a dictionary of
:class:`~psrqpy.pulsar.Pulsar` objects. If ``JNAME`` or ``NAME`` was not in the
original query, it will be performed again, so that a name is present, which is
required for a :class:`~psrqpy.pulsar.Pulsar` object
:class:`~psrqpy.pulsar.Pulsars` object, which is a dictionary of
:class:`~psrqpy.pulsar.Pulsar` objects. If ``JNAME`` or ``NAME`` was not in the
original query, it will be performed again, so that a name is present, which is
required for a :class:`~psrqpy.pulsar.Pulsar` object
"""

if not self._pulsars:
Expand Down Expand Up @@ -497,8 +497,9 @@ def get_pulsars(self):
@property
def get_version(self):
"""
Return a string with the ATNF version number, or the default giving in
ATNF_VERSION if not found
Returns:
str: seturn a string with the ATNF version number, or the default giving in
:attr:`~psrqpy.config.ATNF_VERSION` if not found.
"""

if self._atnf_version is None:
Expand All @@ -508,14 +509,30 @@ def get_version(self):

def parse_conditions(self, condition, psrtype=None, assoc=None, bincomp=None, exactmatch=False):
"""
Parse a string on conditions, i.e., logical statements on with to perform a search, like
condition = 'f0 > 2.5 && assoc(GC)'
:param condition: a string of conditional statements
:param psrtype: 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)
:param assoc: 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)
:parsm bincomp: a list of strings, or single string, of conditions on the binary companiion types of pulsars to return (logical AND will be used for any listed associations)
:param extractmatch: a boolean stating whether assciations and types given as the condition should be an exact match
Parse a string of `conditions
<http://www.atnf.csiro.au/research/pulsar/psrcat/psrcat_help.html#condition>`_, 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.
Args:
condition (str): a string of `conditional <http://www.atnf.csiro.au/research/pulsar/psrcat/psrcat_help.html#condition>`_
statements
psrtype (list, str): a list of strings, or single string, of conditions on the
`type <http://www.atnf.csiro.au/research/pulsar/psrcat/psrcat_help.html#psr_types>`_ 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 <http://www.atnf.csiro.au/research/pulsar/psrcat/psrcat_help.html?type=normal#bincomp_type>`_
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:
str: a string with the format required for use in :attr:`~psrqpy.config.QUERY_URL`
"""

if not condition:
Expand Down Expand Up @@ -646,14 +663,16 @@ def parse_conditions(self, condition, psrtype=None, assoc=None, bincomp=None, ex

def __len__(self):
"""
Length method returns the number of pulsars
Returns:
int: :func:`len` method returns the number of pulsars
"""

return self._npulsars

def __str__(self):
"""
String method returns string method of astropy table
Returns:
str: :func:`str` method returns the str method of an :class:`astropy.table.Table`.
"""

if self._npulsars > 0:
Expand All @@ -663,54 +682,56 @@ def __str__(self):

def __repr__(self):
"""
repr method returns repr method of astropy table
Returns:
str: :func:`repr` method returns the repr method of an :class:`astropy.table.Table`.
"""

if self._npulsars > 0:
return repr(self.table())
else:
return repr(self._query_output) # should be empty dict

def ppdot(self, 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, rcparams={}):
def ppdot(self, 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,
rcparams={}):
"""
Draw a lovely period vs period derivative diagram.
Args:
intrinsicpdot (bool): use the intrinsic period derivative corrected for the
Shlovskii 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 or 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
`Shklovskii effect <https://en.wikibooks.org/wiki/Pulsars_and_neutron_stars/Pulsar_properties#Pulse_period>`_
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
:func:`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.
:func:`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 :math:`10^5` through to :math:`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 :math:`10^{10}` through to :math:`10^{14}` gauss with
steps in powers of 10.
Bfield (:obj:`list`): a list of magnetic field strengths to plot.
rcparams (dict): a dictionary of Matplotlib setup parameters for the plot.
showB (bool): show lines of constant magnetic field strength. Defaults to True, and
shows lines for :math:`10^{10}` through to :math:`10^{14}` gauss with steps in
powers of 10.
Bfield (:py:obj:`list`): a list of magnetic field strengths to plot.
rcparams (dict): a dictionary of :py:obj:`matplotlib.rcParams` setup parameters for the plot.
Returns:
A :class:`matplotlib.figure.Figure` object
Expand Down
6 changes: 5 additions & 1 deletion psrqpy/utils.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -328,7 +328,7 @@ def death_line(logP, linemodel='Ip', rho6=1.):
Args:
logP (list, :class:`~numpy.ndarray`): the base-10 log values of period.
linemodel (str): a string with one of the above model names. Defaults to ``Ip``.
linemodel (str): a string with one of the above model names. Defaults to ``'Ip'``.
rho6 (float): the value of the :math:`\rho_6` parameter from [ZHM]_ . Defaults to 1 is,
which is equivalent to :math:`10^6` cm.
Expand Down Expand Up @@ -376,6 +376,10 @@ def label_line(ax, line, label, color='k', fs=14, frachoffset=0.1):
ax (:class:`matplotlib.axes.Axes`): Axes on which the label should be added.
line (:class:`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:
:class:`matplotlib.text.Text`: a :class:`~matplotlib.text.Text` object containing the label
Expand Down

0 comments on commit f8c8f27

Please sign in to comment.