Skip to content

Commit

Permalink
docs: update
Browse files Browse the repository at this point in the history
  • Loading branch information
wcxve committed Mar 2, 2024
1 parent 5de38e1 commit 9bce699
Show file tree
Hide file tree
Showing 19 changed files with 301 additions and 235 deletions.
2 changes: 1 addition & 1 deletion .readthedocs.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ build:
python: "3.9"
jobs:
pre_build:
- sphinx-apidoc -e -o docs/apidoc src/elisa
- sphinx-apidoc -e -o -T docs/apidoc src/elisa

sphinx:
configuration: docs/conf.py
Expand Down
88 changes: 80 additions & 8 deletions docs/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -14,32 +14,104 @@
import elisa # noqa: E402

project = 'elisa'
copyright = '2023-2024, Wang-Chen Xue & contributors'
author = 'Wang-Chen Xue'
copyright = '2023-2024, W.-C. Xue & contributors'
author = 'elisa developers'
release = elisa.__version__

# -- General configuration ---------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration

extensions = [
'sphinx.ext.autodoc',
'sphinx.ext.doctest',
'sphinx.ext.todo',
'sphinx.ext.autosummary',
'sphinx.ext.coverage',
'sphinx.ext.mathjax',
'sphinx.ext.napoleon',
'sphinx.ext.doctest',
'sphinx.ext.intersphinx',
'sphinx.ext.viewcode',
'numpydoc.numpydoc',
'sphinx_autodoc_typehints',
'sphinx_book_theme',
'sphinx_copybutton',
'sphinx_design',
'myst_nb',
'numpydoc',
]

source_suffix = {
'.rst': 'restructuredtext',
'.ipynb': 'myst-nb',
}

templates_path = ['_templates']
exclude_patterns = ['_build']


# -- Options for HTML output -------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output

html_theme = 'sphinx_rtd_theme'
html_theme = 'sphinx_book_theme'
html_theme_options = {
'github_url': 'https://github.com/wcxve/elisa',
'repository_url': 'https://github.com/wcxve/elisa',
'repository_branch': 'main',
'home_page_in_toc': True,
'path_to_docs': 'docs',
'launch_buttons': {
'binderhub_url': 'https://mybinder.org',
'colab_url': 'https://colab.research.google.com/',
'notebook_interface': 'jupyterlab',
},
'navigation_with_keys': False,
'use_edit_page_button': True,
'use_repository_button': True,
'use_download_button': True,
'use_issues_button': True,
}
# html_static_path = ['_static']
html_baseurl = 'https://elisa-lib.readthedocs.io/en/latest/'

intersphinx_mapping = {
'python': ('https://docs.python.org/3.9', None),
'arviz': ('https://python.arviz.org/en/stable/', None),
'jax': ('https://jax.readthedocs.io/en/latest/', None),
'matplotlib': ('https://matplotlib.org/stable/', None),
'numpy': ('https://numpy.org/doc/stable/', None),
'numpyro': ('https://num.pyro.ai/en/stable/', None),
'tinygp': ('https://tinygp.readthedocs.io/en/latest/', None),
}

myst_enable_extensions = [
'amsmath',
'dollarmath',
]

nb_ipywidgets_js = {
'https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.4/require.min.js': {
'integrity': 'sha256-Ae2Vz/4ePdIu6ZyI/5ZGsYnb+m0JlOmKPjt6XZ9JJkA=',
'crossorigin': 'anonymous',
},
'https://cdn.jsdelivr.net/npm/'
'@jupyter-widgets/html-manager@*/dist/embed-amd.js': {
'data-jupyter-widgets-cdn': 'https://cdn.jsdelivr.net/npm/',
'crossorigin': 'anonymous',
},
}
nb_execution_mode = 'auto'
nb_execution_timeout = -1

numpydoc_attributes_as_param_list = False
numpydoc_class_members_toctree = False
numpydoc_show_class_members = True
numpydoc_show_inherited_class_members = True
numpydoc_xref_param_type = True
numpydoc_xref_ignore = {'optional', 'type_without_description', 'BadException'}
# Run docstring validation as part of build process
# numpydoc_validation_checks = {"all", "GL01", "SA04", "RT03"}
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'

numpydoc_xref_aliases = {
'ParameterBase': 'elisa.model.parameter.ParameterBase',
}

typehints_use_signature = True
typehints_use_signature_return = True
17 changes: 3 additions & 14 deletions docs/index.rst
Original file line number Diff line number Diff line change
@@ -1,20 +1,9 @@
.. elisa documentation master file, created by
sphinx-quickstart on Tue Nov 14 22:43:20 2023.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
Welcome to elisa's documentation!
====================================
=================================

.. toctree::
:maxdepth: 2
:caption: Contents:

apidoc/modules

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
quick-start
modules
8 changes: 6 additions & 2 deletions pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -44,8 +44,12 @@ xspec = ["xspex"]
test = ["pytest", "pytest-cov", "coverage[toml]"]
docs = [
"sphinx",
"sphinx_rtd_theme",
"numpydoc"
"sphinx-autodoc-typehints",
"sphinx-book-theme",
"sphinx-copybutton",
"sphinx-design",
"myst-nb",
"numpydoc",
]
dev = ["pre-commit>=3.6.0", "ruff"]

Expand Down
7 changes: 2 additions & 5 deletions src/elisa/__init__.py
Original file line number Diff line number Diff line change
@@ -1,11 +1,8 @@
from . import data, infer, model, util
from .__about__ import __version__ as __version__
from .data import * # noqa F403
from .infer import * # noqa F403
from .data.ogip import * # noqa F403
from .infer.fit import * # noqa F403
from .model import * # noqa F403
from .util import jax_enable_x64, set_cpu_cores

__all__ = data.__all__ + infer.__all__ + model.__all__ + util.__all__

jax_enable_x64(True)
set_cpu_cores(4)
8 changes: 5 additions & 3 deletions src/elisa/data/__init__.py
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
from .ogip import Data

__all__ = ['Data']
from .ogip import (
Data as Data,
Response as Response,
Spectrum as Spectrum,
)
10 changes: 0 additions & 10 deletions src/elisa/data/grouping.py
Original file line number Diff line number Diff line change
Expand Up @@ -6,16 +6,6 @@

from elisa.util.typing import NumPyArray as NDArray

__all__ = [
'group_const',
'group_min',
'group_sig',
'group_pos',
'group_opt',
'group_optmin',
'group_optsig',
]

GroupResultType = tuple[NDArray, bool]


Expand Down
60 changes: 33 additions & 27 deletions src/elisa/data/ogip.py
Original file line number Diff line number Diff line change
Expand Up @@ -19,8 +19,7 @@
)
from elisa.util.typing import NumPyArray as NDArray

__all__ = ['Data', 'Spectrum', 'Response']
# TODO: support multiple sources
# TODO: support multiple sources in a single data object
# TODO: support creating Data object from array


Expand Down Expand Up @@ -53,14 +52,17 @@ class Data:
group : str or None, optional
Method to group spectrum and background adaptively, these options are
available so that each channel group has:
* const: `scale` number channels
* min: counts >= `scale` for src + bkg
* sig: src significance >= `scale`-sigma
* opt: optimal binning, see Kaastra & Bleeker (2016) [3]_
* optmin: opt with counts >= `scale` for src + bkg
* optsig: opt with src significance >= `scale`-sigma
* bmin: counts >= `scale` for bkg (useful for wstat)
* bpos: bkg < 0 with probability < `scale` (useful for pgstat)
* 'const': `scale` number channels
* 'min': counts >= `scale` for src + bkg
* 'sig': src significance >= `scale`-sigma
* 'opt': optimal binning, see Kaastra & Bleeker (2016) [3]_
* 'optmin': opt with counts >= `scale` for src + bkg
* 'optsig': opt with src significance >= `scale`-sigma
* 'bmin': counts >= `scale` for bkg (useful for wstat)
* 'bpos': bkg < 0 with probability < `scale` (useful for pgstat)
The default is None.
scale : float or None, optional
Grouping scale. Only takes effect if `group` is not None.
spec_poisson : bool or None, optional
Expand All @@ -74,11 +76,13 @@ class Data:
ignore_bad : bool, optional
Whether to ignore channels with ``QUALITY==5``.
The default is True. The possible values for spectral ``QUALITY`` are
* 0: good
* 1: defined bad by software
* 2: defined dubious by software
* 5: defined bad by user
* -1: reason for bad flag unknown
record_channel : bool, optional
Whether to record channel information in the label of grouped
channel. Only takes effect if `group` is not None or spectral data
Expand All @@ -96,12 +100,12 @@ class Data:
References
----------
.. [1] `The OGIP Spectral File Format <https://heasarc.gsfc.nasa.gov/docs/heasarc/ofwg/docs/spectra/ogip_92_007/ogip_92_007.html>`_
and `Addendum: Changes log <https://heasarc.gsfc.nasa.gov/docs/heasarc/ofwg/docs/spectra/ogip_92_007a/ogip_92_007a.html>`_
.. [1] `The OGIP Spectral File Format <https://heasarc.gsfc.nasa.gov/docs/heasarc/ofwg/docs/spectra/ogip_92_007/ogip_92_007.html>`__
and `Addendum: Changes log <https://heasarc.gsfc.nasa.gov/docs/heasarc/ofwg/docs/spectra/ogip_92_007a/ogip_92_007a.html>`__
.. [2] `The Calibration Requirements for Spectral Analysis (Definition of
RMF and ARF file formats) <https://heasarc.gsfc.nasa.gov/docs/heasarc/caldb/docs/memos/cal_gen_92_002/cal_gen_92_002.html>`_
and `Addendum: Changes log <https://heasarc.gsfc.nasa.gov/docs/heasarc/caldb/docs/memos/cal_gen_92_002a/cal_gen_92_002a.html>`_
.. [3] `Kaastra & Bleeker 2016, A&A, 587, A151 <https://doi.org/10.1051/0004-6361/201527395>`_
RMF and ARF file formats) <https://heasarc.gsfc.nasa.gov/docs/heasarc/caldb/docs/memos/cal_gen_92_002/cal_gen_92_002.html>`__
and `Addendum: Changes log <https://heasarc.gsfc.nasa.gov/docs/heasarc/caldb/docs/memos/cal_gen_92_002a/cal_gen_92_002a.html>`__
.. [3] `Kaastra & Bleeker 2016, A&A, 587, A151 <https://doi.org/10.1051/0004-6361/201527395>`__
"""

Expand Down Expand Up @@ -287,14 +291,16 @@ def group(self, method: str, scale: float | int):
method : str
Method to group spectrum and background adaptively, these options
are available so that each channel group has:
* const: `scale` number channels
* min: counts >= `scale` for src + bkg
* sig: src significance >= `scale`-sigma
* opt: optimal binning, see Kaastra & Bleeker (2016, A&A)
* optmin: opt with counts >= `scale` for src + bkg
* optsig: opt with src significance >= `scale`-sigma
* bmin: counts >= `scale` for bkg (useful for W-stat)
* bpos: bkg < 0 with probability < `scale` (useful for PG-stat)
* 'const': `scale` number channels
* 'min': counts >= `scale` for src + bkg
* 'sig': src significance >= `scale`-sigma
* 'opt': optimal binning, see Kaastra & Bleeker (2016, A&A)
* 'optmin': opt with counts >= `scale` for src + bkg
* 'optsig': opt with src significance >= `scale`-sigma
* 'bmin': counts >= `scale` for bkg (useful for W-stat)
* 'bpos': bkg<0 with probability < `scale` (useful for PG-stat)
scale : float
Grouping scale.
Expand Down Expand Up @@ -624,8 +630,8 @@ class Spectrum:
References
----------
.. [1] `The OGIP Spectral File Format <https://heasarc.gsfc.nasa.gov/docs/heasarc/ofwg/docs/spectra/ogip_92_007/ogip_92_007.html>`_
and `Addendum: Changes log <https://heasarc.gsfc.nasa.gov/docs/heasarc/ofwg/docs/spectra/ogip_92_007a/ogip_92_007a.html>`_
.. [1] `The OGIP Spectral File Format <https://heasarc.gsfc.nasa.gov/docs/heasarc/ofwg/docs/spectra/ogip_92_007/ogip_92_007.html>`__
and `Addendum: Changes log <https://heasarc.gsfc.nasa.gov/docs/heasarc/ofwg/docs/spectra/ogip_92_007a/ogip_92_007a.html>`__
"""

Expand Down Expand Up @@ -962,8 +968,8 @@ class Response:
References
----------
.. [1] `The Calibration Requirements for Spectral Analysis (Definition of
RMF and ARF file formats) <https://heasarc.gsfc.nasa.gov/docs/heasarc/caldb/docs/memos/cal_gen_92_002/cal_gen_92_002.html>`_
and `Addendum: Changes log <https://heasarc.gsfc.nasa.gov/docs/heasarc/caldb/docs/memos/cal_gen_92_002a/cal_gen_92_002a.html>`_
RMF and ARF file formats) <https://heasarc.gsfc.nasa.gov/docs/heasarc/caldb/docs/memos/cal_gen_92_002/cal_gen_92_002.html>`___
and `Addendum: Changes log <https://heasarc.gsfc.nasa.gov/docs/heasarc/caldb/docs/memos/cal_gen_92_002a/cal_gen_92_002a.html>`__
"""

Expand Down
7 changes: 4 additions & 3 deletions src/elisa/infer/__init__.py
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
from .fit import BayesianFit, LikelihoodFit

__all__ = ['BayesianFit', 'LikelihoodFit']
from .fit import (
BayesianFit as BayesianFit,
LikelihoodFit as LikelihoodFit,
)
10 changes: 8 additions & 2 deletions src/elisa/infer/fit.py
Original file line number Diff line number Diff line change
Expand Up @@ -37,8 +37,6 @@
replace_string,
)

__all__ = ['LikelihoodFit', 'BayesianFit']

Statistic = Literal['chi2', 'cstat', 'pstat', 'pgstat', 'wstat']
T = TypeVar('T')

Expand All @@ -55,11 +53,13 @@ class BaseFit(ABC):
stat : str or sequence of str
The likelihood option for the data and model. Available likelihood
options are:
* 'chi2' : Gaussian data
* 'cstat' : Poisson data
* 'pstat' : Poisson data with known background
* 'pgstat' : Poisson data with Gaussian background
* 'wstat' : Poisson data with Poisson background
seed : int, optional
Random number generator seed. The default is 42.
Expand Down Expand Up @@ -595,19 +595,25 @@ def mle(
strategy : {0, 1, 2}, optional
Optimization strategy to use in Minuit.
Available options are:
* 0: Fast.
* 1: Default.
* 2: Careful. This improves accuracy at the cost of time.
lopt : {'minuit', 'lm'}, optional
Local optimization algorithm to use.
Available options are:
* 'minuit': Migrad algorithm of Minuit.
* 'lm': Levenberg-Marquardt algorithm of :mod:`jaxopt`.
The default is 'minuit'.
gopt : {'ns'}, optional
Global optimization algorithm to find the initial guess for MLE.
Available options are:
* 'ns' : nested sampling of :mod:`jaxns`.
The default is None.
nboot : int, optional
Number of parametric bootstrap based on the MLE. These simulation
Expand Down
2 changes: 1 addition & 1 deletion src/elisa/infer/likelihood.py
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,7 @@ def pgstat_background(
References
----------
.. [1] `XSPEC Manual Appendix B: Statistics in XSPEC <https://heasarc.gsfc.nasa.gov/xanadu/xspec/manual/XSappendixStatistics.html>`_.
.. [1] `XSPEC Manual Appendix B: Statistics in XSPEC <https://heasarc.gsfc.nasa.gov/xanadu/xspec/manual/XSappendixStatistics.html>`__.
"""
variance = b_err * b_err
Expand Down
1 change: 0 additions & 1 deletion src/elisa/infer/nested_sampling.py
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,6 @@
from numpyro.infer.reparam import Reparam
from numpyro.infer.util import _guess_max_plate_nesting, _validate_model, log_density

__all__ = ["NestedSampler"]

tfpd = tfp.distributions

Expand Down
Loading

0 comments on commit 9bce699

Please sign in to comment.