Merge pull request #1871 from dlakaplan/fixdocstrings

Fixed some docstrings: removed newlines, other reformatting
nanograv · Dec 11, 2024 · d5edc21 · d5edc21
2 parents 19abb24 + 9c191d3
commit d5edc21
Show file tree

Hide file tree

Showing 4 changed files with 67 additions and 45 deletions.
diff --git a/CHANGELOG-unreleased.md b/CHANGELOG-unreleased.md
@@ -27,6 +27,7 @@ the released changes.
 - When EQUAD is created from TNEQ, has proper TCB->TDB conversion info
 - TOA selection masks will work when only TOA is the first one
 - Condense code in Glitch model and add test coverage.
+- Fixed some docstrings for binary models.
 ### Removed
 - macOS 12 CI 
 
diff --git a/src/pint/models/binary_bt.py b/src/pint/models/binary_bt.py
@@ -21,7 +21,7 @@
 class BinaryBT(PulsarBinary):
     """Blandford and Teukolsky binary model.
 
-    This binary model is described in Blandford and Teukolshy 1976. It is
+    This binary model is described in Blandford and Teukolsky (1976). It is
     a relatively simple parametrized post-Keplerian model that does not
     support Shapiro delay calculations.
 
@@ -36,12 +36,16 @@ class BinaryBT(PulsarBinary):
     Notes
     -----
     Because PINT's binary models all support specification of multiple orbital
-    frequency derivatives FBn, this is capable of behaving like the model called
-    BTX in tempo2. The model called BTX in tempo instead supports multiple
-    (non-interacting) companions, and that is not supported here. Neither can
-    PINT accept "BTX" as an alias for this model.
+    frequency derivatives ``FBn``, this is capable of behaving like the model called
+    ``BTX`` in ``tempo2``. The model called ``BTX`` in ``tempo`` instead supports multiple
+    (non-interacting) companions, and that is not supported here.
+
+    References
+    ----------
+    - Blandford & Teukolsky 1976, ApJ, 205, 580 [1]_
+
+    .. [1] https://ui.adsabs.harvard.edu/abs/1976ApJ...205..580B/abstract
 
-    See Blandford & Teukolsky 1976, ApJ, 205, 580.
     """
 
     register = True
@@ -82,16 +86,23 @@ def validate(self):
 
 
 class BinaryBTPiecewise(PulsarBinary):
-    """Model implementing the BT model with piecewise orbital parameters A1X and T0X. This model lets the user specify time ranges and fit for a different piecewise orbital parameter in each time range,
-    This is a PINT pulsar binary BTPiecewise model class, a subclass of PulsarBinary.
-    It is a wrapper for stand alone BTPiecewise class defined in
-    ./stand_alone_psr_binary/BT_piecewise.py
-    The aim for this class is to connect the stand alone binary model with the PINT platform.
-    BTpiecewise special parameters, where xxxx denotes the 4-digit index of the piece:
-    T0X_xxxx Piecewise T0 values for piece
-    A1X_xxxx Piecewise A1 values for piece
-    XR1_xxxx Lower time boundary of piece
-    XR2_xxxx Upper time boundary of piece
+    """BT model with piecewise orbital parameters ``A1X`` and ``T0X``. This model lets the user specify time ranges and fit for a different piecewise orbital parameter in each time range.
+
+    ``BTpiecewise`` special parameters, where xxxx denotes the 4-digit index of the piece:
+
+        - ``T0X_xxxx``: Piecewise ``T0`` values for piece
+        - ``A1X_xxxx``: Piecewise ``A1`` values for piece
+        - ``XR1_xxxx``: Lower time boundary of piece
+        - ``XR2_xxxx``: Upper time boundary of piece
+
+    The actual calculations for this are done in
+    :class:`pint.models.stand_alone_psr_binaries.BT_piecewise.BTpiecewise`
+
+    Parameters supported:
+
+    .. paramtable::
+        :class: pint.models.binary_bt.BinaryBTPiecewise
+
     """
 
     register = True

diff --git a/src/pint/models/noise_model.py b/src/pint/models/noise_model.py
@@ -442,8 +442,7 @@ def ecorr_cov_matrix(self, toas):
 
 
 class PLDMNoise(NoiseComponent):
-    """Model of DM variations as radio frequency-dependent noise with a
-    power-law spectrum.
+    """Model of DM variations as radio frequency-dependent noise with a power-law spectrum.
 
     Variations in DM over time result from both the proper motion of the
     pulsar and the changing electron number density along the line of sight
@@ -459,9 +458,11 @@ class PLDMNoise(NoiseComponent):
     .. paramtable::
         :class: pint.models.noise_model.PLDMNoise
 
-    Note
-    ----
-    Ref: Lentati et al. 2014, MNRAS 437(3), 3004-3023
+    References
+    ----------
+    - Lentati et al. 2014, MNRAS 437(3), 3004-3023 [1]_
+
+    .. [1] https://ui.adsabs.harvard.edu/abs/2014MNRAS.437.3004L/abstract
 
     """
 
@@ -558,8 +559,7 @@ def pl_dm_cov_matrix(self, toas):
 
 
 class PLChromNoise(NoiseComponent):
-    """Model of a radio frequency-dependent noise with a power-law spectrum and
-    arbitrary chromatic index.
+    """Model of a radio frequency-dependent noise with a power-law spectrum and arbitrary chromatic index.
 
     Such variations are usually attributed to time-variable scattering in the
     ISM. Scattering smears/broadens the shape of the pulse profile by convolving it with
@@ -579,9 +579,11 @@ class PLChromNoise(NoiseComponent):
     .. paramtable::
         :class: pint.models.noise_model.PLChromNoise
 
-    Note
-    ----
-    Ref: Lentati et al. 2014, MNRAS 437(3), 3004-3023
+    References
+    ----------
+    - Lentati et al. 2014, MNRAS 437(3), 3004-3023 [1]_
+
+    .. [1] https://ui.adsabs.harvard.edu/abs/2014MNRAS.437.3004L/abstract
     """
 
     register = True
@@ -692,10 +694,11 @@ class PLRedNoise(NoiseComponent):
     .. paramtable::
         :class: pint.models.noise_model.PLRedNoise
 
-    Note
-    ----
-    Ref: Lentati et al. 2014, MNRAS 437(3), 3004-3023
+    References
+    ----------
+    - Lentati et al. 2014, MNRAS 437(3), 3004-3023 [1]_
 
+    .. [1] https://ui.adsabs.harvard.edu/abs/2014MNRAS.437.3004L/abstract
     """
 
     register = True

diff --git a/src/pint/models/wavex.py b/src/pint/models/wavex.py
@@ -12,9 +12,7 @@
 
 class WaveX(DelayComponent):
     """
-    Implementation of the wave model as a delay correction
-
-    Delays are expressed as a sum of sinusoids.
+    Implementation of the wave model as a delay correction, with delays are expressed as a sum of sinusoids.
 
     Used for decomposition of timing noise into a series of sine/cosine components with the amplitudes as fitted parameters.
 
@@ -23,25 +21,34 @@ class WaveX(DelayComponent):
     .. paramtable::
         :class: pint.models.wavex.WaveX
 
-    This is an extension of the L13 method described in Lentati et al., 2013 doi: 10.1103/PhysRevD.87.104021
-    This model is similar to the TEMPO2 WAVE model parameters and users can convert a `TimingModel` with a Wave model
-    to a WaveX model and produce the same results. The main differences are that the WaveX frequencies are explicitly stated,
+    This is an extension of the method described in Lentati et al. (2013).
+    This model is similar to the TEMPO2 WAVE model parameters and users can convert a :class:`~pint.models/timing_model.TimingModel`
+    with a :class:`~pint.models.wave.Wave` model to a ``WaveX`` model and produce the same results.
+    The main differences are that the ``WaveX`` frequencies are explicitly stated,
     they do not necessarily need to be harmonics of some base frequency, the wave amplitudes are fittable parameters, and the
-    sine and cosine amplutides are reported as separate `prefixParameter`s rather than as a single `pairParameter`.
+    sine and cosine amplutides are reported as separate :class:`~pint.models.parameter.prefixParameter` rather than as a
+    single :class:`pint.models.parameter.pairParameter`.
 
     Analogous parameters in both models have the same units:
-    WAVEEPOCH is the same as WXEPOCH
-    WAVEOM and WXFREQ_000N have units of 1/d
-    WAVEN and WXSIN_000N/WXCOS_000N have units of seconds
 
-    The `pint.utils` functions `translate_wave_to_wavex()` and `translate_wavex_to_wave()` can be used to go back and forth between
-    two model.
+        - ``WAVEEPOCH`` is the same as ``WXEPOCH``
+        - ``WAVEOM`` and ``WXFREQ_000N`` have units of 1/d
+        - ``WAVEN`` and ``WXSIN_000N/WXCOS_000N`` have units of seconds
+
+    The :mod:`pint.utils` functions :func:`~pint.utils.translate_wave_to_wavex` and :func:`~pint.utils.translate_wavex_to_wave`
+    can be used to go back and forth between two model.
+
+    WARNING: If the choice of ``WaveX`` frequencies in a :class:`~pint.models/timing_model.TimingModel` doesn't correspond to harmonics of some base
+    freqeuncy, it will not be possible to convert it to a :class:`~pint.models.wave.Wave` model.
+
+    To set up a ``WaveX`` model, users can use the :mod:`pint.utils` function :func:`~pint.utils.wavex_setup` with either a list of frequencies or a choice
+    of harmonics of a base frequency determined by ``2 * pi /Timespan``
 
-    WARNING: If the choice of WaveX frequencies in a `TimingModel` doesn't correspond to harmonics of some base
-    freqeuncy, it will not be possible to convert it to a Wave model.
+    References
+    ----------
+    - Lentati et al. (2013), PRD, 87, 104021 [1]_
 
-    To set up a WaveX model, users can use the `pint.utils` function `wavex_setup()` with either a list of frequencies or a choice
-    of harmonics of a base frequency determined by 2 * pi /Timespan
+    .. [1] https://ui.adsabs.harvard.edu/abs/2013PhRvD..87j4021L/abstract
     """
 
     register = True