Skip to content

Commit

Permalink
docs updates
Browse files Browse the repository at this point in the history
  • Loading branch information
@bmorris3
bmorris3 committed Jun 19, 2024
1 parent 062c32c commit 5e86c47
Show file tree
Hide file tree
Showing 5 changed files with 145 additions and 54 deletions.
109 changes: 104 additions & 5 deletions docs/conf.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 ---------------------------------------------------

Expand All @@ -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',
Expand All @@ -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,
Expand All @@ -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",
}
Expand All @@ -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
# "<project> v<release> 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)]
32 changes: 18 additions & 14 deletions docs/gadfly/start.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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::

Expand All @@ -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
Expand All @@ -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
Expand Down
47 changes: 22 additions & 25 deletions docs/gadfly/validation.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -108,25 +108,24 @@ 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,
kernel=kernel,
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=""
)
Expand Down Expand Up @@ -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=""
)

Expand Down Expand Up @@ -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):
Expand Down Expand Up @@ -320,19 +318,18 @@ 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,
freq=freq,
obs=ps,
obs_kwargs=obs_kw,
kernel_kwargs=kernel_kw,
n_samples=1e4,
title=""
)

Expand Down Expand Up @@ -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)
Expand Down
5 changes: 0 additions & 5 deletions docs/index.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 <https://github.com/bmorris3/gadfly>`_.

.. note::

``gadfly`` is under active development. If you run into any issues, please `let us
know on GitHub <https://github.com/bmorris3/gadfly/issues>`_.

.. toctree::
:maxdepth: 2
:caption: Contents:
Expand Down
Loading

0 comments on commit 5e86c47

Please sign in to comment.