From 5e86c4723e8a8aa78d6f3969052f97331cdb475b Mon Sep 17 00:00:00 2001 From: "Brett M. Morris" Date: Tue, 18 Jun 2024 21:38:46 -0400 Subject: [PATCH] docs updates --- docs/conf.py | 109 +++++++++++++++++++++++++++++++++++-- docs/gadfly/start.rst | 32 ++++++----- docs/gadfly/validation.rst | 47 ++++++++-------- docs/index.rst | 5 -- pyproject.toml | 6 +- 5 files changed, 145 insertions(+), 54 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 970a4bc..12370f1 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -6,16 +6,22 @@ # full list see the documentation: # http://www.sphinx-doc.org/en/master/config +import datetime +import inspect +import sys +from os.path import relpath, dirname # -- Project information ----------------------------------------------------- project = 'gadfly' -copyright = '2022, Brett M. Morris' author = 'Brett M. Morris' +copyright = f"{datetime.datetime.now().year}, {author}" # noqa: A001 # The full version, including alpha/beta/rc tags +import gadfly from gadfly import __version__ release = __version__ +dev = "dev" in release # -- General configuration --------------------------------------------------- @@ -32,6 +38,7 @@ 'sphinx.ext.napoleon', 'sphinx.ext.doctest', 'sphinx.ext.mathjax', + 'sphinx.ext.linkcode', 'sphinx_automodapi.automodapi', 'sphinx_automodapi.smart_resolver', 'sphinx.ext.autosectionlabel', @@ -54,23 +61,29 @@ # The master toctree document. master_doc = 'index' +# Treat everything in single ` as a Python reference. +default_role = 'py:obj' + # -- Options for intersphinx extension --------------------------------------- # Example configuration for intersphinx: refer to the Python standard library. intersphinx_mapping = { - 'https://docs.python.org/': None, + 'python': ('https://docs.python.org/', None), 'numpy': ('https://numpy.org/doc/stable/', None), 'celerite2': ('https://celerite2.readthedocs.io/en/latest/', None), 'astropy': ('https://docs.astropy.org/en/stable/', None), 'lightkurve': ('https://docs.lightkurve.org/', None), 'matplotlib': ('http://matplotlib.org/stable', None), - 'tynt': ('https://tynt.readthedocs.io/en/latest/', None) + 'tynt': ('https://tynt.readthedocs.io/en/latest/', None), } # -- Options for HTML output ------------------------------------------------- +github_issues_url = 'https://github.com/bmorris3/gadfly/issues/' + # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. +html_copy_source = False html_theme = 'sphinx_book_theme' # Add any paths that contain custom static files (such as style sheets) here, @@ -80,9 +93,10 @@ html_favicon = "assets/logo.ico" html_theme_options = { - "logo_only": True, + "use_edit_page_button": True, "use_download_button": True, "repository_url": "https://github.com/bmorris3/gadfly", + "github_url": "https://github.com/bmorris3/gadfly", "repository_branch": "main", "path_to_docs": "docs", } @@ -91,12 +105,97 @@ autodoc_inherit_docstrings = True html_context = { - "display_github": True, "github_user": "bmorris3", "github_repo": "gadfly", "github_version": "main", "conf_py_path": "docs/", + "default_mode": "light", + "to_be_indexed": ["stable", "latest"], + "is_development": dev, + "doc_path": "docs", + "display_github": True, } autosectionlabel_prefix_document = True autoclass_content = 'both' + +# The name for this set of Sphinx documents. If None, it defaults to +# " v documentation". +html_title = '{0}'.format(project) + +# Output file base name for HTML help builder. +htmlhelp_basename = project + 'doc' + +# Prefixes that are ignored for sorting the Python module index +modindex_common_prefix = ["gadfly."] + +suppress_warnings = ['autosectionlabel.*'] + + +def linkcode_resolve(domain, info): + """ + Determine the URL corresponding to Python object + """ + if domain != 'py': + return None + + modname = info['module'] + fullname = info['fullname'] + + submod = sys.modules.get(modname) + if submod is None: + return None + + obj = submod + for part in fullname.split('.'): + try: + obj = getattr(obj, part) + except Exception: + return None + + # strip decorators, which would resolve to the source of the decorator + # possibly an upstream bug in getsourcefile, bpo-1764286 + try: + unwrap = inspect.unwrap + except AttributeError: + pass + else: + obj = unwrap(obj) + + fn = None + lineno = None + + if fn is None: + try: + fn = inspect.getsourcefile(obj) + except Exception: + fn = None + if not fn: + return None + + # Ignore re-exports as their source files are not within the numpy repo + module = inspect.getmodule(obj) + if module is not None and not module.__name__.startswith("shone"): + return None + + try: + source, lineno = inspect.getsourcelines(obj) + except Exception: + lineno = None + + fn = relpath(fn, start=dirname(gadfly.__file__)) + + if lineno: + linespec = "#L%d-L%d" % (lineno, lineno + len(source) - 1) + else: + linespec = "" + + if 'dev' in gadfly.__version__: + return "https://github.com/bmorris3/shone/blob/main/shone/%s%s" % ( + fn, linespec) + else: + return "https://github.com/bmorris3/shone/blob/v%s/shone/%s%s" % ( + gadfly.__version__, fn, linespec) + + +plot_formats = [('png', 250)] diff --git a/docs/gadfly/start.rst b/docs/gadfly/start.rst index 8b33abb..0a25b8c 100644 --- a/docs/gadfly/start.rst +++ b/docs/gadfly/start.rst @@ -118,11 +118,11 @@ out their key properties: import astropy.units as u # Some (randomly chosen) real stars from Huber et al. (2011) - kics = [9333184, 8416311, 8624155, 3120486, 9650527] - masses = [0.9, 1.5, 1.8, 1.9, 2.0] * u.M_sun - radii = [10.0, 2.2, 8.8, 6.7, 10.9] * u.R_sun - temperatures = [4919, 6259, 4944, 4929, 4986] * u.K - luminosities = [52.3, 6.9, 41.2, 23.9, 65.4] * u.L_sun + kics = [9333184, 8624155, 3120486] + masses = [0.9, 1.8, 1.9] * u.M_sun + radii = [10.0, 8.8, 6.7] * u.R_sun + temperatures = [4919, 4944, 4929] * u.K + luminosities = [52.3, 41.2, 23.9] * u.L_sun stellar_props = [ kics, masses, radii, temperatures, luminosities @@ -142,6 +142,8 @@ generalization of the :py:class:`~gadfly.SolarOscillatorKernel`. import matplotlib.pyplot as plt fig, ax = plt.subplots(figsize=(8, 4)) + plot_frequencies = np.geomspace(0.1, 300, 25_000) * u.uHz + # iterate over each star: for i, (kic, mass, rad, temp, lum) in enumerate(zip(*stellar_props)): # scale the set of solar hyperparameters for each @@ -161,12 +163,12 @@ generalization of the :py:class:`~gadfly.SolarOscillatorKernel`. # Plot the kernel's PSD: kernel.plot( ax=ax, - n_samples=5e3 + freq=plot_frequencies ) # Label the legend, set the power range in plot: legend = ax.legend(title='Simulated kernels') - ax.set_ylim(1e-1, 1e6) + ax.set_ylim(1, 1e6) .. plot:: @@ -178,14 +180,16 @@ generalization of the :py:class:`~gadfly.SolarOscillatorKernel`. # Some (randomly chosen) real stars from Huber et al. (2011) # https://ui.adsabs.harvard.edu/abs/2011ApJ...743..143H/abstract - kics = [9333184, 8416311, 8624155, 3120486, 9650527] - masses = [0.9, 1.5, 1.8, 1.9, 2.0] * u.M_sun - radii = [10.0, 2.2, 8.8, 6.7, 10.9] * u.R_sun - temperatures = [4919, 6259, 4944, 4929, 4986] * u.K - luminosities = [52.3, 6.9, 41.2, 23.9, 65.4] * u.L_sun + kics = [9333184, 8624155, 3120486] + masses = [0.9, 1.8, 1.9] * u.M_sun + radii = [10.0, 8.8, 6.7] * u.R_sun + temperatures = [4919, 4944, 4929] * u.K + luminosities = [52.3, 41.2, 23.9] * u.L_sun stellar_props = [kics, masses, radii, temperatures, luminosities] + plot_frequencies = np.geomspace(0.1, 300, 25_000) * u.uHz + # iterate over each star: for i, (kic, mass, radius, temperature, luminosity) in enumerate(zip(*stellar_props)): # scale the set of solar hyperparameters for each @@ -201,12 +205,12 @@ generalization of the :py:class:`~gadfly.SolarOscillatorKernel`. # Plot the kernel's PSD: kernel.plot( ax=ax, - n_samples=5e3 + freq=plot_frequencies ) # Label the legend, set the power range in plot: legend = ax.legend(title='Simulated kernels') - ax.set_ylim(1e-1, 1e6) + ax.set_ylim(1, 1e6) The resulting plot has "simulated" power spectra for the five stars, built by scaling the observed solar oscillations and granulation, which were parameterized by diff --git a/docs/gadfly/validation.rst b/docs/gadfly/validation.rst index e3424bd..c5ec691 100644 --- a/docs/gadfly/validation.rst +++ b/docs/gadfly/validation.rst @@ -108,14 +108,13 @@ Now we'll call a big loop to do most of the work: # Compute the power spectrum: ps = PowerSpectrum.from_light_curve( lc, - name=target_name, - detrend_poly_order=1 + name=target_name ) # Plot the binned PSD and the kernel PSD. This plot function # takes lots of keyword arguments so you can fine-tune your # plots: - obs_kw = dict(color='k', marker='.', lw=0) + obs_kw = dict(color='k', marker='.', lw=0, alpha=0.4, zorder=-10) ps.bin(1_500).plot( ax=axis, @@ -123,10 +122,10 @@ Now we'll call a big loop to do most of the work: freq=ps.frequency, obs_kwargs=obs_kw, legend=True, - n_samples=5e3, + n_samples=1e4, label_kernel='Pred. kernel', label_obs=target_name, - kernel_kwargs=dict(color=f'C{i}', alpha=0.9), + kernel_kwargs=dict(color=f'C{i}', lw=1.5), title="" ) @@ -196,22 +195,21 @@ Ok, let's see the output: # Compute the power spectrum: ps = PowerSpectrum.from_light_curve( lc, name=target_name, - detrend_poly_order=1 ) - obs_kw = dict(color='k', marker='.', lw=0) + obs_kw = dict(color='k', marker='.', lw=0, alpha=0.4, zorder=-10) # Plot the binned PSD of the light curve: - ps.bin(1_500).plot( + ps.bin(1_000).plot( ax=axis, kernel=kernel, freq=ps.frequency, legend=True, - n_samples=5e3, + n_samples=1e4, label_kernel='Pred. kernel', label_obs=target_name, obs_kwargs=obs_kw, - kernel_kwargs=dict(color=f'C{i}', alpha=0.9), + kernel_kwargs=dict(color=f'C{i}', lw=1.5), title="" ) @@ -252,17 +250,17 @@ kernel: .. code-block:: python - light_curve = search_lightcurve( - name, mission='Kepler', quarter=range(6), cadence='short' - ).download_all() + light_curve = search_lightcurve( + name, mission='Kepler', quarter=range(6), cadence='short' + ).download_all() - kernel = ( - # kernel for scaled stellar oscillations and granulation - StellarOscillatorKernel(hp, texp=1 * u.min) + + kernel = ( + # kernel for scaled stellar oscillations and granulation + StellarOscillatorKernel(hp, texp=1 * u.min) + - # add in a kernel for Kepler shot noise - ShotNoiseKernel.from_kepler_light_curve(light_curve) - ) + # add in a kernel for Kepler shot noise + ShotNoiseKernel.from_kepler_light_curve(light_curve) + ) Let's now run the adapted code on the first two stars (click the "Source code" link below to see the code that generates this plot): @@ -320,11 +318,11 @@ to see the code that generates this plot): ps = PowerSpectrum.from_light_curve( light_curve, name=name, detrend_poly_order=1 - ).bin(1_500) + ).bin(500) - kernel_kw = dict(color=f"C{i}", alpha=0.9) - obs_kw = dict(color='k', marker='.', lw=0) - freq = np.logspace(-0.5, 4, int(1e3)) * u.uHz + kernel_kw = dict(color=f"C{i}", lw=1.5) + obs_kw = dict(color='k', marker='.', lw=0, alpha=0.5, zorder=-10) + freq = np.logspace(-0.5, 4, int(1e4)) * u.uHz kernel.plot( ax=axis, p_mode_inset=False, @@ -332,7 +330,6 @@ to see the code that generates this plot): obs=ps, obs_kwargs=obs_kw, kernel_kwargs=kernel_kw, - n_samples=1e4, title="" ) @@ -407,7 +404,7 @@ Kepler would observe for each target. ps = PowerSpectrum.from_light_curve( light_curve, name=name, detrend_poly_order=3, - ).bin(500) + ).bin(100) # adjust some plot settings: kernel_kw = dict(color=f"C{i}", alpha=0.9) diff --git a/docs/index.rst b/docs/index.rst index 4b71b59..d8e75df 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -10,11 +10,6 @@ This is the documentation for ``gadfly``, a Python package for generating photom stars with granulation and p-mode oscillations. The source code is available `on GitHub `_. -.. note:: - - ``gadfly`` is under active development. If you run into any issues, please `let us - know on GitHub `_. - .. toctree:: :maxdepth: 2 :caption: Contents: diff --git a/pyproject.toml b/pyproject.toml index 70c8e7d..e52e4bc 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -16,11 +16,10 @@ authors = [ { name = "Brett M. Morris", email = "morrisbrettm@gmail.com" }, ] dependencies = [ - "numpy", + "numpy<2", # until lightkurve fixes are available "celerite2", "astropy", "matplotlib", - "PyYAML", "scipy", "lightkurve", "tynt", @@ -32,13 +31,10 @@ test = [ "pytest", "pytest-doctestplus", "pytest-cov", - "scipy", ] docs = [ "sphinx", "sphinx-automodapi", - "scipy", - "lightkurve", "sphinx-book-theme>=0.3.3", "numpydoc", ]