From ae8ee9db9f89d10f030d563d771db587dc0b21ea Mon Sep 17 00:00:00 2001 From: Lukas Hergt Date: Mon, 31 Jul 2023 10:32:14 -0700 Subject: [PATCH] Add specific docs for the GUI (#315) * add copy buttons to the docs (with automatic ommission of standard prompt characters) * add docs for using the anesthetic gui, especially for manually launching the gui * version bump to 2.0.1 * Made a note to use %matplotlib interactive * Corrected indent * version bump * version bump to 2.1.3 --------- Co-authored-by: Will Handley --- README.rst | 2 +- anesthetic/_version.py | 2 +- docs/source/conf.py | 7 +++++ docs/source/gui.rst | 66 ++++++++++++++++++++++++++++++++++++++++++ docs/source/index.rst | 1 + pyproject.toml | 2 +- 6 files changed, 77 insertions(+), 3 deletions(-) create mode 100644 docs/source/gui.rst diff --git a/README.rst b/README.rst index a8fba59d..8d780bb6 100644 --- a/README.rst +++ b/README.rst @@ -2,7 +2,7 @@ anesthetic: nested sampling post-processing =========================================== :Authors: Will Handley and Lukas Hergt -:Version: 2.1.2 +:Version: 2.1.3 :Homepage: https://github.com/handley-lab/anesthetic :Documentation: http://anesthetic.readthedocs.io/ diff --git a/anesthetic/_version.py b/anesthetic/_version.py index f8115612..2d31b1c3 100644 --- a/anesthetic/_version.py +++ b/anesthetic/_version.py @@ -1 +1 @@ -__version__ = '2.1.2' +__version__ = '2.1.3' diff --git a/docs/source/conf.py b/docs/source/conf.py index 0c595a01..45291474 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -57,6 +57,7 @@ def get_version(short=False): 'sphinx.ext.viewcode', 'sphinx.ext.githubpages', 'sphinx.ext.imgconverter', + 'sphinx_copybutton', 'matplotlib.sphinxext.plot_directive', 'numpydoc', ] @@ -102,6 +103,12 @@ def get_version(short=False): # -- Options for autosectionlabel------------------------------------------ autosectionlabel_prefix_document = True + +# -- Options for sphinx-copybutton ---------------------------------------- +copybutton_prompt_text = r">>> |\.\.\. |\$ |In \[\d*\]: | {2,5}\.\.\.: | {5,8}: " +copybutton_prompt_is_regexp = True + + # -- Options for numpydoc ------------------------------------------------- numpydoc_show_inherited_class_members = False numpydoc_show_class_members = False diff --git a/docs/source/gui.rst b/docs/source/gui.rst new file mode 100644 index 00000000..b2257baa --- /dev/null +++ b/docs/source/gui.rst @@ -0,0 +1,66 @@ +****************************** +Graphical User Interface (GUI) +****************************** + +For an interactive view of a nested sampling run, you can use the +anesthetic GUI by running the follwing in your console: + +.. code:: console + + $ anesthetic + +Replace the ```` with the correct path and file root +of your nested sampling run (e.g. try it out with the anesthetic example data +in ``anesthetic/tests/example_data/pc``). This will launch a new window +looking somewhat like this: + +.. image:: https://github.com/handley-lab/anesthetic/raw/master/images/anim_1.gif + +.. warning:: + Note that the GUI only works out-of-the-box if your files follow a specific + structure, matching either the one from + `PolyChord `_, + `MultiNest `_, or from + `UltraNest `_. + +.. note:: + However, you can also manually feed in your data and launch the GUI as + demonstrated in the following example: + + .. plot:: + + import numpy as np + import matplotlib.pyplot as plt + from anesthetic import NestedSamples + + # Set up `data`, `logL`, and `logL_birth` + file_path = "../../tests/example_data/pc_dead-birth.txt" + file_data = np.loadtxt(file_path) + data, logL, logL_birth = np.split(file_data, [-2, -1], axis=1) + + samples = NestedSamples(data=data, logL=logL, logL_birth=logL_birth) + samples.gui() + plt.show() + + To make this example work with the anesthetic example data, place the above + code snippet into a python script (let's call it + ``my_anesthetic_gui_script.py``), make sure the file path correctly points + to the example data in the ``anesthetic/tests/`` folder, and launch it from + the command line: + + .. code:: console + + $ python my_anesthetic_gui_script.py + + To modify the above example for your own case, you only need to change the + middle block to read in your data file(s) instead of the anesthetic example + data and pass on the ``data``, ``logL``, and ``logL_birth`` arrays, which + contain the parameter samples, their corresponding log-likelihood values, and + the log-likelihood values of their birth contours, respectively. + +.. note:: + If you are using a jupyter notebook, you should use + ``%matplotlib interactive`` magic command (or equivalent) to use the + interactive GUI. + + diff --git a/docs/source/index.rst b/docs/source/index.rst index 8b8f8687..051f7a57 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -9,6 +9,7 @@ Reading and writing Samples and statistics Plotting + GUI anesthetic .. include:: ../../README.rst diff --git a/pyproject.toml b/pyproject.toml index d8f2e151..b75b5352 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -58,7 +58,7 @@ classifiers = [ "JOSS paper" = "https://joss.theoj.org/papers/10.21105/joss.01414" [project.optional-dependencies] -docs = ["sphinx", "sphinx_rtd_theme", "numpydoc"] +docs = ["sphinx", "sphinx_rtd_theme", "sphinx-copybutton", "numpydoc"] test = ["pytest", "pytest-cov", "flake8", "pydocstyle", "packaging", "pre-commit"] ultranest = ["h5py"] astropy = ["astropy"]