new docs

.readthedocs.yml

@@ -1,7 +1,7 @@
 version: 2
 
 sphinx:
-  configuration: docs/source/conf.py
+  configuration: docs/conf.py
 
 formats: all
 
@@ -13,6 +13,7 @@ python:
       extra_requirements:
         - all
     - requirements: docs/requirements_docs.txt
+  system_packages: true
 
 submodules:
   include: all

docs/Makefile

@@ -5,8 +5,8 @@
 # from the environment for the first two.
 SPHINXOPTS    ?=
 SPHINXBUILD   ?= sphinx-build
-SOURCEDIR     = source
-BUILDDIR      = build
+SOURCEDIR     = .
+BUILDDIR      = _build
 
 # Put it first so that "make" without argument is like "make help".
 help:

docs/source/conf.py → docs/conf.py

@@ -30,7 +30,10 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ['sphinx.ext.autodoc', 'sphinx.ext.napoleon'
+extensions = [
+    'nbsphinx',
+    'sphinx_gallery.load_style',
+    'sphinx.ext.autodoc', 'sphinx.ext.napoleon',
 ]
 
 # Add any paths that contain templates here, relative to this directory.

docs/examples.rst

@@ -0,0 +1,8 @@
+Examples
+========
+
+.. nbgallery::
+    :name: examples-gallery
+
+    examples/GW150914
+    examples/GW150914_circular

examples/GW150914.ipynb → docs/examples/GW150914.ipynb

@@ -1216,7 +1216,12 @@
    "cell_type": "code",
    "execution_count": 33,
    "id": "80984c85",
-   "metadata": {},
+   "metadata": {
+    "nbsphinx-thumbnail": {
+     "tooltip": "Look for ringdown modes in GW150914 data"
+    },
+    "tags": []
+   },
    "outputs": [
     {
      "data": {
@@ -1878,7 +1883,7 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "Python 3 (ipykernel)",
+   "display_name": "Python 3",
    "language": "python",
    "name": "python3"
   },
@@ -1892,7 +1897,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.9.5"
+   "version": "3.6.8"
   }
  },
  "nbformat": 4,

examples/GW150914_circular.ipynb → docs/examples/GW150914_circular.ipynb

@@ -938,7 +938,12 @@
    "cell_type": "code",
    "execution_count": 60,
    "id": "80984c85",
-   "metadata": {},
+   "metadata": {
+    "nbsphinx-thumbnail": {
+     "tooltip": "Look for circularly-polarized ringdown modes in GW150914 data"
+    },
+    "tags": []
+   },
    "outputs": [
     {
      "data": {
@@ -1249,7 +1254,7 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "Python 3 (ipykernel)",
+   "display_name": "Python 3",
    "language": "python",
    "name": "python3"
   },
@@ -1263,7 +1268,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.9.6"
+   "version": "3.6.8"
   }
  },
  "nbformat": 4,

docs/source/index.rst → docs/index.rst

@@ -6,9 +6,9 @@
 ringdown
 ========
 
-**ringdown** is a Python-based package for the Bayesian analysis of black hole ringdowns in data from gravitational-wave detectors, like `LIGO <https://www.ligo.caltech.edu>`_ and `Virgo <https://www.virgo-gw.eu>`_.
+**ringdown** is a Python package for the Bayesian analysis of black hole ringdowns in data from gravitational-wave detectors, like `LIGO <https://www.ligo.caltech.edu>`_ and `Virgo <https://www.virgo-gw.eu>`_.
 
-ringdown contains basic utilities to manipulate strain data and easily set up your own inference analyses. The current implementation relies on `Stan <https://mc-stan.org>`_ for sampling.
+`ringdown` contains basic utilities to manipulate strain data and easily set up your own inference analyses quickly. The current implementation relies on `Stan <https://mc-stan.org>`_ for sampling.
 
 This documentation is being actively developed. In the meantime, usage examples can be found `here <https://github.com/maxisi/ringdown/tree/main/examples>`_ and API documentation in the :ref:`modindex`.
 
@@ -19,9 +19,24 @@ This documentation is being actively developed. In the meantime, usage examples
 .. image:: https://zenodo.org/badge/DOI/10.5281/zenodo.5094067.svg
    :target: https://doi.org/10.5281/zenodo.5094067
 
+Example
+-------
+
+You can get an analysis going with just a few lines of code. For example, assuming you have already downloaded GW150914 data from `GWOSC <https://www.gw-openscience.org>`_::
+
+    import ringdown as rd
+    fit = rd.Fit('mchi', modes=[(1,-2,2,2,0), (1,-2,2,2,1)])
+    fit.load_data('{i}-{i}1_GWOSC_16KHZ_R1-1126259447-32.hdf5', ifos=['H1', 'L1'], kind='gwosc')
+    fit.set_target(1126259462.4083147, ra=1.95, dec=-1.27, psi=0.82, duration=0.05)
+    fit.condition_data(ds=8)
+    fit.set_prior(A_scale=1e-21, M_min=50, M_max=150)
+    fit.run()
+
+See more examples in the example gallery.
+
 
 How to cite
-===========
+-----------
 
 We ask that scientific users of this code cite the corresponding Zenodo entry (see blue DOI badge above), as well as `Isi & Farr (2021) <https://arxiv.org/abs/2107.05609>`_:
 
@@ -42,10 +57,11 @@ We ask that scientific users of this code cite the corresponding Zenodo entry (s
    :maxdepth: 2
    :caption: Contents:
 
+   examples
 
 
 Indices and tables
-==================
+------------------
 
 * :ref:`genindex`
 * :ref:`modindex`

docs/make.bat

@@ -7,8 +7,8 @@ REM Command file for Sphinx documentation
 if "%SPHINXBUILD%" == "" (
 	set SPHINXBUILD=sphinx-build
 )
-set SOURCEDIR=source
-set BUILDDIR=build
+set SOURCEDIR=.
+set BUILDDIR=_build
 
 if "%1" == "" goto help
 

docs/requirements_docs.txt

@@ -1,3 +1,6 @@
 # docs/requirements_docs.txt
 sphinx
 sphinx-autobuild
+ipykernel
+nbsphinx
+sphinx-gallery

ringdown/data.py

@@ -271,14 +271,15 @@ class Data(TimeSeries):
         detector identifier (e.g., 'H1' for LIGO Hanford).
     """
 
-    _metadata = ['ifo']
+    _metadata = ['ifo', 'info']
 
-    def __init__(self, *args, ifo=None, **kwargs):
+    def __init__(self, *args, ifo=None, info=None,  **kwargs):
         if ifo is not None:
             ifo = ifo.upper()
         kwargs['name'] = kwargs.get('name', ifo)
         super(Data, self).__init__(*args, **kwargs)
         self.ifo = ifo
+        self.info = info or {}
 
     @property
     def _constructor(self):

ringdown/fit.py

@@ -947,8 +947,7 @@ def start_indices(self) -> dict:
             # find sample closest to (but no later than) requested start time
             for ifo, d in self.data.items():
                 t0 = self.start_times[ifo]
-                t = d.time.values - t0
-                i0_dict[ifo] = where(t==amin(abs(t), where=t>=0, initial=inf))[0][0]
+                i0_dict[ifo] = argmin(abs(d.time - t0))
         return i0_dict
 
     @property

ringdown/waveforms/coalescence.py

@@ -8,6 +8,7 @@
 import lalsimulation as ls
 from dataclasses import dataclass, asdict, fields
 import inspect
+import h5py
 
 def docstring_parameter(*args, **kwargs):
     def dec(obj):
@@ -113,6 +114,9 @@ def __post_init__(self):
     def __getitem__(self, *args, **kwargs):
         return getattr(self, *args, **kwargs)
 
+    def __setitem__(self, *args, **kwargs):
+        return setattr(self, *args, **kwargs)
+
     def to_dict(self) -> dict:
             return asdict(self)
 
@@ -128,7 +132,7 @@ def values(self, *args, **kwargs):
     _EXTRINSIC_KEYS = ['ra', 'dec', 'trigger_time']
 
     _SPIN_KEYS_LALINF = ['theta_jn', 'phi_jl', 'tilt_1', 'tilt_2', 'phi_12',
-                         'a_1' 'a_2']
+                         'a_1', 'a_2']
 
     _SPIN_COMP_KEYS = ['spin_{}{}'.format(i,x) for i in [1,2] for x in 'xyz']
     _SPIN_KEYS_LALSIM = ['iota'] + _SPIN_COMP_KEYS
@@ -141,10 +145,15 @@ def values(self, *args, **kwargs):
         'chirp_mass': ['mc', 'mchirp'],
         'mass_ratio': ['q'],
         'luminosity_distance': ['dist', 'dl', 'distance'],
+        'iota': ['inclination', 'inc'],
     }
+    _ALIASES_STR = ''
+    for _k,_v in _ALIASES.items():
+        _ALIASES_STR += f"* `{_k}`: ``{_v}\n``"
+
     for _k in _SPIN_KEYS_LALINF:
         _ALIASES[_k] = [_k.replace('_', '')]
-    del _k
+    del _k, _v
 
     @property
     def intrinsic(self):
@@ -167,19 +176,24 @@ def construct(cls, **kws):
         angles) and automatically convert them to the `LALSimulation`
         convention (Cartesian components) for storage.
 
-        Unrecognized arguments are ignored. Missing parameters will be set to
-        default.
+        A number of aliases for common parameters are recognized (e.g., ``mc``
+        is an alias of ``chirp_mass``); all valid aliases are listed below.
+        Unrecognized arguments are ignored.  Missing parameters will be set to
+        default (see :class:`Parameters` docs).
+
+        Valid aliases:
+        {}
 
         Arguments
         ---------
-        kws
+        \*\*kws
             parameter names and values
 
         Returns
         -------
         pars : Parameters
             coalescence parameters container object
-        """
+        """.format(cls._ALIASES_STR)
         kws['f_ref'] = kws.get('f_ref', kws.get('f_low'))
         for par, aliases in cls._ALIASES.items():
             for k in aliases:
@@ -194,10 +208,15 @@ def construct(cls, **kws):
                 kws['mass_1'], kws['mass_2'] = m1m2_from_mcq(kws['chirp_mass'],
                                                              kws['mass_ratio'])
         # compose spins
-        if not all([k in kws for k in cls._SPIN_KEYS_LALSIM if k != 'iota']):
-            a = [kws[k] for k in cls._SPIN_KEYS_LALINF] + \
-                   [kws['mass_1']*lal.MSUN_SI, kws['mass_2']*lal.MSUN_SI,
-                    kws['fref'], kws['phase']]
+        lsim_given = [k in kws for k in cls._SPIN_KEYS_LALSIM if k!='iota']
+        linf_given = [k in kws for k in cls._SPIN_KEYS_LALINF if k!='theta_jn']
+        if not all(lsim_given) and any(linf_given):
+            try:
+                a = [kws[k] for k in cls._SPIN_KEYS_LALINF] + \
+                       [kws['mass_1']*lal.MSUN_SI, kws['mass_2']*lal.MSUN_SI,
+                        kws['fref'], kws['phase']]
+            except KeyError as e:
+                raise ValueError(f"unable to parse spins, missing: {e}")
             b = lalsim.SimInspiralTransformPrecessingNewInitialConditions(*a)
             kws.update(dict(zip(cls._SPIN_KEYS_LALSIM, b)))
 

ringdown/waveforms/core.py

@@ -30,7 +30,7 @@ def _ishift(hp_t, hc_t):
 class Signal(TimeSeries):
     _metadata = ['parameters']
     _T0_ALIASES = ['t0', 'geocent_time', 'trigger_time', 'triggertime',
-                   'time', 'tc']
+                   'tc', 'tgps_geo', 'tgps_geocent']
     _FROM_GEO_KEY = 'from_geo'
 
     _MODEL_REGISTER = {}
@@ -184,7 +184,11 @@ def project(self, ifo=None, t0=None, antenna_patterns=None, delay=None,
                 dt = (idt - delay*self.fsamp)*self.delta_t
                 h = hint(self.time + dt)
             h = np.roll(h, idt)
-        return Data(h, ifo=ifo, index=self.time)
+        info = self.parameters
+        info.update({k: v for k,v in locals().items() if k in
+                     ['antenna_patterns', 'ra', 'dec', 'psi', 'delay', 
+                     'fd_shift', 'interpolate']})
+        return Data(h, ifo=ifo, index=self.time, info=info)
 
     def plot(self, ax=None, envelope=False):
         """Plot the series' plus and cross components.
@@ -248,12 +252,14 @@ def get_detector_signals(times=None, ifos=None, antenna_patterns=None,
     s_kws = all_kws.copy()
 
     # check if a trigger time was provided
-    t0 = [s_kws.pop(k, None) for k in Signal._T0_ALIASES][0]
+    t0 = None
+    for k in Signal._T0_ALIASES:
+        t0 = t0 if t0 is not None else s_kws.pop(k, None)
     if t0 is None:
         t0 = t0_default
     # get other arguments for signal projection
     p_kws ={k: s_kws.pop(k) for k in kws.keys() if k in 
-            getfullargspec(Signal.project)[0][1:]}
+            getfullargspec(Signal.project)[0][1:] and k != 't0'}
 
     # parse detectors and time arrays
     if isinstance(times, dict):