diff --git a/docs/source/config.rst b/docs/source/config.rst index 11467c4c..aee85cc0 100644 --- a/docs/source/config.rst +++ b/docs/source/config.rst @@ -5,5 +5,3 @@ Setup constants .. automodule:: psrqpy.config :members: -.. autodata:: psrqpy.config.ATNF_VERSION - :annotation: = Blah diff --git a/docs/source/pulsar.rst b/docs/source/pulsar.rst index 2fccc6d4..82cc5292 100644 --- a/docs/source/pulsar.rst +++ b/docs/source/pulsar.rst @@ -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: diff --git a/psrqpy/config.py b/psrqpy/config.py index fd0df78b..39115c8c 100644 --- a/psrqpy/config.py +++ b/psrqpy/config.py @@ -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=' @@ -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 @@ -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) @@ -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 `_. +""" 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" `_ 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 @@ -134,8 +144,7 @@ '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 `_ for use in ``bincomp()`` when setting logical conditions PSR_BINARY_TYPE = ['MS', # Main-sequence star 'NS', # Neutron star 'CO', # CO or ONeMg White Dwarf @@ -143,11 +152,10 @@ '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/{}/' diff --git a/psrqpy/search.py b/psrqpy/search.py index 9e90e945..be0a7e1e 100644 --- a/psrqpy/search.py +++ b/psrqpy/search.py @@ -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: @@ -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: @@ -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 + `_, 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 `_ + statements + 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: + str: a string with the format required for use in :attr:`~psrqpy.config.QUERY_URL` + """ if not condition: @@ -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: @@ -663,7 +682,8 @@ 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: @@ -671,46 +691,47 @@ def __repr__(self): 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 `_ + 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 diff --git a/psrqpy/utils.py b/psrqpy/utils.py index 0ab91e7b..275356be 100644 --- a/psrqpy/utils.py +++ b/psrqpy/utils.py @@ -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. @@ -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