Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Syntax highlighting in docs #1768

Merged
merged 11 commits into from
Oct 26, 2022
Merged

Syntax highlighting in docs #1768

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
8b1762e
syntax highlight code blocks in readme
bmorris3 Oct 24, 2022
f0b6a30
fixing broken docs URL in readme
bmorris3 Oct 24, 2022
aff3a84
syntax highlight all code blocks in docs
bmorris3 Oct 24, 2022
72ef2b4
cleaning up docstrings, fixing broken internal docs refs
bmorris3 Oct 24, 2022
bec3222
Update README.rst
bmorris3 Oct 25, 2022
8b1150a
Update README.rst
bmorris3 Oct 25, 2022
4359eb5
Update docs/mosviz/displayspectra.rst
bmorris3 Oct 25, 2022
0bac798
Update docs/cubeviz/displayspectra.rst
bmorris3 Oct 25, 2022
3fc90a6
Update docs/mosviz/import_data.rst
bmorris3 Oct 25, 2022
8bfa80a
Correcting a bunch of missed code blocks, thanks @pllim
bmorris3 Oct 25, 2022
8c06e82
Apply suggestions from code review
bmorris3 Oct 26, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 23 additions & 12 deletions README.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,10 +1,11 @@
.. image:: docs/logos/jdaviz.svg
:width: 400
:alt: Jdaviz logo
:width: 400
:alt: Jdaviz logo
:align: center
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think this align has any effect on the GitHub rendering. Should we just remove it?

Suggested change
:align: center

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Interestingly, it does, but not always? This is a feature I've wanted for a long time in GH renders of rst docs, and it works in some repos but not this one... not sure why?


.. image:: https://zenodo.org/badge/DOI/10.5281/zenodo.5513927.svg
:target: https://doi.org/10.5281/zenodo.5513927
:alt: Zenodo DOI
:target: https://doi.org/10.5281/zenodo.5513927
:alt: Zenodo DOI

.. image:: https://github.com/spacetelescope/jdaviz/workflows/CI/badge.svg
:target: https://github.com/spacetelescope/jdaviz/actions
Expand Down Expand Up @@ -49,12 +50,16 @@ Installing
----------

You may want to consider installing ``jdaviz`` in a new virtual or conda environment to avoid
version conflicts with other packages you may have installed, for example::
version conflicts with other packages you may have installed, for example:

.. code-block:: bash
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am not sure if this does anything different in GitHub view but I guess it does not hurt.


conda create -n jdaviz-env python=3.9
conda activate jdaviz-env

Installing the released version can be done using pip::
Installing the released version can be done using pip:

.. code-block:: bash

pip install jdaviz --upgrade

Expand All @@ -70,19 +75,23 @@ As a Web Application
++++++++++++++++++++

``jdaviz`` provides a command-line tool to start the web application. To see the syntax and usage,
from a terminal, type::
from a terminal, type:

.. code-block:: bash

jdaviz --help
jdaviz specviz /path/to/data/spectral_file

For more information on the command line interface, see the
`Jdaviz Quickstart <https://jdaviz.readthedocs.io/en/latest/quickstart.html>`_.
For more information on the command line interfaces for each tool, see the
`Jdaviz docs <https://jdaviz.readthedocs.io/en/latest/index.html>`_.


In a Jupyter Notebook
+++++++++++++++++++++

The power of ``jdaviz`` is that it can integrated into your Jupyter notebook workflow::
The power of ``jdaviz`` is that it can integrated into your Jupyter notebook workflow:

.. code-block:: python

from jdaviz import Specviz

Expand All @@ -93,8 +102,10 @@ To learn more about the various ``jdaviz`` application configurations and loadin
`specviz <https://jdaviz.readthedocs.io/en/latest/specviz/import_data.html>`_, `cubeviz <https://jdaviz.readthedocs.io/en/latest/cubeviz/import_data.html>`_, `mosviz <https://jdaviz.readthedocs.io/en/latest/mosviz/import_data.html>`_, or `imviz <https://jdaviz.readthedocs.io/en/latest/imviz/import_data.html>`_ tools.

``jdaviz`` also provides a directory of `sample notebooks <https://jdaviz.readthedocs.io/en/latest/sample_notebooks.html>`_ to test the application, located in the ``notebooks`` sub-directory
of the git repository. ``CubevizExample.ipynb`` is provided as an example that loads a SDSS MaNGA IFU data cube with the
``Cubeviz`` configuration. To run the provided example, start the jupyter kernel with the notebook path::
of the git repository. ``CubevizExample.ipynb`` is provided as an example that loads a JWST data cube with the
``Cubeviz`` configuration. To run the provided example, start the Jupyter kernel with the notebook path:

.. code-block:: bash

jupyter notebook /path/to/jdaviz/notebooks/CubevizExample.ipynb

Expand Down
4 changes: 2 additions & 2 deletions docs/cubeviz/displayspectra.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,5 +15,5 @@ below.
Documentation on displaying spectra in a 1D spectrum viewer.

There is one important difference when using the API to access Specviz from within Cubeviz.
The functionality of the `~jdaviz.configs.specviz.helper.Specviz` API can be accessed in Cubeviz via
the `jdaviz.configs.cubeviz.helper.Cubeviz.specviz` attribute, e.g. ``cubeviz.specviz.get_spectra()``.
The functionality of the :class:`jdaviz.configs.specviz.helper.Specviz` API can be accessed in Cubeviz via
the `~jdaviz.configs.cubeviz.helper.Cubeviz.specviz` attribute, e.g. ``cubeviz.specviz.get_spectra()``.
56 changes: 42 additions & 14 deletions docs/cubeviz/export_data.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,19 +18,27 @@ Spatial Regions
Documentation on how to export spatial regions.

Since Specviz can be accessed from Cubeviz, the following line of code
can be used to extract the *spectrum* of a spatial subset named "Subset 1"::
can be used to extract the *spectrum* of a spatial subset named "Subset 1":

.. code-block:: python

subset1_spec1d = cubeviz.specviz.get_spectra("Subset 1")

An example without accessing Specviz::
An example without accessing Specviz:

.. code-block:: python

subset1_spec1d = cubeviz.app.get_data_from_viewer("flux-viewer", data_label="Subset 1")

To get all subsets from the spectrum viewer::
To get all subsets from the spectrum viewer:

.. code-block:: python

subset1_spec1d = cubeviz.app.get_subsets_from_viewer("spectrum-viewer")

To access the spatial regions themselves::
To access the spatial regions themselves:

.. code-block:: python

regions = cubeviz.get_interactive_regions()
regions
Expand All @@ -43,7 +51,9 @@ To access the spatial regions themselves::
:ref:`Export Spectra <specviz-export-data>`
Documentation on how to export data from the ``spectrum-viewer``.

The following line of code can be used to extract a spectral subset named "Subset 2"::
The following line of code can be used to extract a spectral subset named "Subset 2":

.. code-block:: python

subset2_spec1d = cubeviz.specviz.get_spectra("Subset 2")

Expand All @@ -53,28 +63,40 @@ The following line of code can be used to extract a spectral subset named "Subse
2D images and 3D data cubes can be extracted from their respective
:ref:`viewers <cubeviz-viewers>`. The viewer options in the Cubeviz configuration are
``flux-viewer``, ``uncert-viewer``, and ``mask-viewer``.
For example, to list the data available in a particular viewer:::
For example, to list the data available in a particular viewer:

.. code-block:: python

mydata = cubeviz.app.get_data_from_viewer("flux-viewer")

To extract the data you want (replace "data_name" with the name of your data)::
To extract the data you want (replace "data_name" with the name of your data):

.. code-block:: python

mydata = cubeviz.app.get_data_from_viewer("uncert-viewer", "data_name")

The data is returned as a ``glue-jupyter`` object. To convert to a numpy array::
The data is returned as a ``glue-jupyter`` object. To convert to a numpy array:

.. code-block:: python

mydata_flux = mydata["flux"]

To retrieve the data cube as a `specutils.Spectrum1D` object, you can do the following::
To retrieve the data cube as a `specutils.Spectrum1D` object, you can do the following:

.. code-block:: python

from specutils import Spectrum1D
mydata.get_object(cls=Spectrum1D, statistic=None)

Alternatively, you can wrap this all into a single command::
Alternatively, you can wrap this all into a single command:

.. code-block:: python

mydata = cubeviz.app.get_data_from_viewer("uncert-viewer", "data_name")

Data can also be accessed directly from ``data_collection`` using the following code::
Data can also be accessed directly from ``data_collection`` using the following code:

.. code-block:: python

cubeviz.app.data_collection[0]

Expand All @@ -88,16 +110,22 @@ previous example).
Model Fits
==========

For a list of model labels::
For a list of model labels:

.. code-block:: python

models = cubeviz.get_models()
models

Once you know the model labels, to get a specific model::
Once you know the model labels, to get a specific model:

.. code-block:: python

mymodel = cubeviz.get_models(model_label="ModelLabel", x=10)

To extract all of the model parameters::
To extract all of the model parameters:

.. code-block:: python

myparams = cubeviz.get_model_parameters(model_label="ModelLabel", x=x, y=y)
myparams
Expand Down
34 changes: 24 additions & 10 deletions docs/cubeviz/import_data.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,9 @@ To then extract your data from Cubeviz, please see the :ref:`cubeviz-notebook` s
Importing data through the Command Line
=======================================

You can load your data into the Cubeviz application through the command line::
You can load your data into the Cubeviz application through the command line:

.. code-block:: bash

jdaviz cubeviz /my/directory/cube.fits

Expand All @@ -70,13 +72,15 @@ Importing data via the API

Alternatively, users who work in a coding environment like a Jupyter
notebook can access the Cubeviz helper class API. Using this API, users can
load data into the application through code with the :meth:`~jdaviz.configs.specviz.helper.Specviz.load_spectrum`
load data into the application through code with the :py:meth:`~jdaviz.configs.specviz.helper.Specviz.load_spectrum`
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Don't think :py: is strictly necessary but I guess it doesn't hurt?

method, which takes as input a :class:`~specutils.Spectrum1D` object.

FITS Files
----------

The example below loads a FITS file into Cubeviz::
The example below loads a FITS file into Cubeviz:

.. code-block:: python

from jdaviz import Cubeviz
cubeviz = Cubeviz()
Expand All @@ -88,7 +92,9 @@ Spectrum1D (from file)

For cases where the built-in parser is unable to understand your file format,
you can try the `~specutils.Spectrum1D` parser directly and then pass the object to the
:meth:`~jdaviz.core.helpers.ConfigHelper.load_data` method::
:py:meth:`~jdaviz.core.helpers.ConfigHelper.load_data` method:

.. code-block:: python

from specutils import Spectrum1D
from jdaviz import Cubeviz
Expand All @@ -100,7 +106,9 @@ you can try the `~specutils.Spectrum1D` parser directly and then pass the object
Spectrum1D (from array)
-----------------------

You can create your own `~specutils.Spectrum1D` object by hand to load into Cubeviz::
You can create your own :class:`~specutils.Spectrum1D` object by hand to load into Cubeviz:

.. code-block:: python

import numpy as np
from astropy import units as u
Expand All @@ -124,7 +132,9 @@ JWST datamodels
---------------

If you have a `jwst.datamodels <https://jwst-pipeline.readthedocs.io/en/latest/jwst/datamodels/index.html>`_
object, you can load it into Cubeviz as follows::
object, you can load it into Cubeviz as follows:

.. code-block:: python

import numpy as np
import astropy.wcs as fitswcs
Expand Down Expand Up @@ -162,19 +172,23 @@ Importing regions via the API
=============================

If you have a region file supported by :ref:`regions:regions_io`, you
can load the regions into Cubeviz as follows::
can load the regions into Cubeviz as follows:

.. code-block:: python

cubeviz.load_regions_from_file("/path/to/data/myregions.reg")

Unsupported regions will be skipped and trigger a warning. Those that
failed to load, if any, can be returned as a list of tuples of the
form ``(region, reason)``::
form ``(region, reason)``:

.. code-block:: python

bad_regions = cubeviz.load_regions_from_file("/path/to/data/myregions.reg", return_bad_regions=True)

.. note:: Sky regions are currently unsupported in Cubeviz, unlike Imviz.

For more details on the API, please see
:meth:`~jdaviz.core.helpers.ImageConfigHelper.load_regions_from_file`
and :meth:`~jdaviz.core.helpers.ImageConfigHelper.load_regions` methods
:py:meth:`~jdaviz.core.helpers.ImageConfigHelper.load_regions_from_file`
and :py:meth:`~jdaviz.core.helpers.ImageConfigHelper.load_regions` methods
in Cubeviz.
32 changes: 24 additions & 8 deletions docs/dev/links.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,9 @@ up with the first (32,32) pixels of the larger dataset, starting at the origin.
This is equivalent to the "match image" mode in DS9.

An example of setting up an identity link in pixel coordinates between two
n-dimensional datasets where n is the same for both datasets would look like::
n-dimensional datasets where n is the same for both datasets would look like:

.. code-block:: python

from glue.core.link_helpers import LinkSame

Expand All @@ -52,7 +54,9 @@ n-dimensional datasets where n is the same for both datasets would look like::
This can also be used to link, for example, the two spatial dimensions of a
collapsed cube with the original cube, as done in the `cube collapse
functionality <https://github.com/spacetelescope/jdaviz/blob/0553aca6c2e9530d8dff74088e877fc9593c2d3c/jdaviz/configs/default/plugins/collapse/collapse.py>`_
in Jdaviz::
in Jdaviz:

.. code-block:: python

pix_id_1 = self._selected_data.pixel_component_ids[i1]
pix_id_1c = self.data_collection[label].pixel_component_ids[i1c]
Expand Down Expand Up @@ -89,7 +93,9 @@ The more robust approach for linking datasets by WCS is to use the
:class:`~glue.plugins.wcs_autolinking.wcs_autolinking.WCSLink` class. Given two
datasets, and a list of pixel component IDs to link in each dataset, this class
will set up links between the pixel components by internally representing the
chain of WCS transformations required. As an example::
chain of WCS transformations required. As an example:

.. code-block:: python

from glue.plugins.wcs_autolinking.wcs_autolinking import WCSLink

Expand All @@ -107,7 +113,9 @@ both a FITS WCS to a GWCS instance, and vice versa.
Using LinkSame (not recommended)
--------------------------------

The first is to do something similar to how pixel coordinates are linked in :ref:`link_by_pixel`::
The first is to do something similar to how pixel coordinates are linked in :ref:`link_by_pixel`:

.. code-block:: python

from glue.core.link_helpers import LinkSame

Expand All @@ -121,7 +129,9 @@ The first is to do something similar to how pixel coordinates are linked in :ref
data_collection.add_link(links)

or see the `following example in app.py <https://github.com/spacetelescope/jdaviz/blob/d296c6312b020897034e9dd1fc58c84a2559efa5/jdaviz/app.py>`_
from Jdaviz::
from Jdaviz:

.. code-block:: python

def _link_new_data(self):
"""
Expand Down Expand Up @@ -163,7 +173,9 @@ necessary if the two datasets are close to each other and have a similar WCS.
For the best performance, it is possible to approximate the
:class:`~glue.plugins.wcs_autolinking.wcs_autolinking.WCSLink` by a simple affine
transformation between the datasets. This can be done with the
:meth:`~glue.plugins.wcs_autolinking.wcs_autolinking.WCSLink.as_affine_link` method::
:meth:`~glue.plugins.wcs_autolinking.wcs_autolinking.WCSLink.as_affine_link` method:

.. code-block:: python

link = WCSLink(data1=data1, data2=data2,
cids1=data1.pixel_component_ids,
Expand Down Expand Up @@ -194,7 +206,9 @@ using the
:meth:`~glue.core.data_collection.DataCollection.delay_link_manager_update`
context manager. Use this around any block that adds multiple datasets to the
data collection, components/attributes to datasets, or links to the data
collection, e.g.::
collection, e.g.:

.. code-block:: python

with data_collection.delay_link_manager_update():
for i in range(10):
Expand All @@ -208,7 +222,9 @@ Setting or resetting all links in one go

If you want to prepare and set all links in one go, discarding any previous links,
you can make use of the :meth:`~glue.core.data_collection.DataCollection.set_links`
method, which takes a list of links::
method, which takes a list of links:

.. code-block:: python

data_collection.set_links([link1, link2, link3])

Expand Down
Loading