docs: more updates to API documentation (#103)

* docs: more docs cleanup

* add tldr to install page

Author: tlambert03

docs/env_var.md

@@ -15,8 +15,9 @@
 
 ## Framework selection
 
-If you have multiple supported GUI or graphics libraries installed, you can
-control which ones `ndv` uses with **`NDV_CANVAS_BACKEND`** and **`NDV_GUI_FRONTEND`**,
+Depending on how you've [installed ndv](./install.md), you may end up with
+multiple supported GUI or graphics libraries installed. You can control which
+ones `ndv` uses with **`NDV_CANVAS_BACKEND`** and **`NDV_GUI_FRONTEND`**,
 respectively, as described above.  Note that currently, only one GUI framework
 can be used per session.
 

docs/install.md

@@ -1,5 +1,19 @@
 # Installation
 
+!!! tip "TLDR;"
+
+    === "For a desktop usage"
+ 
+        ```python
+        pip install "ndv[vispy,pyqt]"
+        ```
+
+    === "For Jupyter notebook/lab"
+    
+        ```python
+        pip install "ndv[vispy,jupyter]"
+        ```
+
 `ndv` can be used in a variety of contexts. It supports various **GUI
  frameworks**, including [PyQt](https://riverbankcomputing.com/software/pyqt),
  [PySide](https://wiki.qt.io/Qt_for_Python), [wxPython](https://wxpython.org),
@@ -14,7 +28,7 @@ and GUI libraries you want to use:
 <!-- logic for this table in install-table.js -->
 <div id="install-table"></div>
 
-!!! tip
+!!! note "Framework Selection"
 
     If you have *multiple* supported GUI or graphics libraries installed, you can
     select which ones `ndv` uses with

docs/motivation.md

@@ -22,14 +22,15 @@ display data.
     amount of time. "Reasonable" is of course relative and subjective, but we
     aim for less than 1 second on a modern laptop (currently at <100ms).
 - [x] **Broad GUI Compatibility**: A common feature request for `napari` is to support
-    Jupyter notebooks. `ndv` [can work with](./env_var.md#framework-selection) Qt,
+    Jupyter notebooks. `ndv` [can work with](./install.md) Qt,
     wxPython, *and* Jupyter.
 - [x] **Flexible Graphics Providers**: `ndv` works with VisPy in a classical OpenGL
     context, but has an abstracting layer that allows for other graphics engines.
     We currently also support `pygfx`, a WGPU-based graphics engine.
 - [x] **Model/View architecture**: `ndv` should have a clear separation between the
     data model and the view. The model should be serializable and easily
-    transferable between different views.
+    transferable between different views. (The primary model is currently
+    [`ArrayDisplayModel`][ndv.models.ArrayDisplayModel])
 - [x] **Asynchronous first**: `ndv` should be asynchronous by default: meaning
     that the data request/response process happens in the background, and the
     GUI remains responsive. (Optimization of remote, multi-resolution data is on

mkdocs.yml

@@ -73,6 +73,8 @@ markdown_extensions:
   - pymdownx.details
   - pymdownx.keys
   - pymdownx.tilde
+  - pymdownx.tabbed:
+      alternate_style: true
   - pymdownx.emoji:
       emoji_index: !!python/name:material.extensions.emoji.twemoji
       emoji_generator: !!python/name:material.extensions.emoji.to_svg
@@ -110,6 +112,7 @@ plugins:
         python:
           import:
             - https://docs.python.org/3/objects.inv
+            - https://numpy.org/doc/stable/objects.inv
             - https://docs.pydantic.dev/latest/objects.inv
             - https://cmap-docs.readthedocs.io/objects.inv
             - https://psygnal.readthedocs.io/en/latest/objects.inv

src/ndv/models/__init__.py

@@ -3,7 +3,14 @@
 from ._array_display_model import ArrayDisplayModel, ChannelMode
 from ._base_model import NDVModel
 from ._data_wrapper import DataWrapper
-from ._lut_model import ClimPolicy, ClimsManual, ClimsMinMax, ClimsPercentile, LUTModel
+from ._lut_model import (
+    ClimPolicy,
+    ClimsManual,
+    ClimsMinMax,
+    ClimsPercentile,
+    ClimsStdDev,
+    LUTModel,
+)
 
 __all__ = [
     "ArrayDisplayModel",
@@ -12,6 +19,7 @@
     "ClimsManual",
     "ClimsMinMax",
     "ClimsPercentile",
+    "ClimsStdDev",
     "DataWrapper",
     "LUTModel",
     "NDVModel",

src/ndv/models/_array_display_model.py

@@ -15,20 +15,26 @@
 from ._reducer import ReducerType
 
 if TYPE_CHECKING:
-    from collections.abc import Mapping
+    from collections.abc import Hashable, Mapping  # noqa: F401
+    from typing import Callable  # noqa: F401
 
     import cmap
+    import numpy.typing as npt  # noqa: F401  # used for mkdocstrings
 
     from ._lut_model import AutoscaleType
 
     class LutModelKwargs(TypedDict, total=False):
+        """Keyword arguments for `LUTModel`."""
+
         visible: bool
         cmap: cmap.Colormap | cmap._colormap.ColorStopsLike
         clims: tuple[float, float] | None
         gamma: float
         autoscale: AutoscaleType
 
     class ArrayDisplayModelKwargs(TypedDict, total=False):
+        """Keyword arguments for `ArrayDisplayModel`."""
+
         visible_axes: tuple[AxisKey, AxisKey, AxisKey] | tuple[AxisKey, AxisKey]
         current_index: Mapping[AxisKey, Union[int, slice]]
         channel_mode: "ChannelMode" | Literal["grayscale", "composite", "color", "rgba"]
@@ -106,40 +112,50 @@ def is_multichannel(self) -> bool:
 class ArrayDisplayModel(NDVModel):
     """Model of how to display an array.
 
-    In the following types, `AxisKey` can be either an integer index or a string label.
+    An `ArrayDisplayModel` is used to specify how to display a multi-dimensional array.
+    It specifies which axes are visible, how to reduce along axes that are not visible,
+    how to display channels, and how to apply lookup tables to channels.  It is
+    typically paired with a [`ndv.DataWrapper`][] in order to resolve axis keys and
+    slice data.
+
+    !!! info
+
+        In the following types, `Hashable` is used to refer to a type that will
+        typically be either an integer index or a string label for an axis.
 
     Attributes
     ----------
-    visible_axes : tuple[AxisKey, ...]
+    visible_axes : tuple[Hashable, ...]
         Ordered list of axes to visualize, from slowest to fastest.
-        e.g. ('z', -2, -1)
-    current_index : Mapping[AxisKey, int | Slice]
+        e.g. `('Z', -2, -1)`
+    current_index : Mapping[Hashable, int | slice]
         The currently displayed position/slice along each dimension.
         e.g. {0: 0, 'time': slice(10, 20)}
         Not all axes need be present, and axes not present are assumed to
         be slice(None), meaning it is up to the controller of this model to restrict
         indices to an efficient range for retrieval.
         If the number of non-singleton axes is greater than `n_visible_axes`,
-        then reducers are used to reduce the data along the remaining axes.
-        NOTE: In terms of requesting data, there is a slight "delocalization" of state
-        here in that we probably also want to avoid requesting data for channel
-        positions that are not visible.
-    reducers : Mapping[AxisKey | None, ReducerType]
-        Callable to reduce data along axes remaining after slicing.
+        then `reducers` are used to reduce the data along the remaining axes.
+    reducers : Mapping[Hashable | None, numpy.ufunc]
+        Function used to reduce data along axes remaining after slicing.
         Ideally, the ufunc should accept an `axis` argument.
-        (TODO: what happens if not?)
+        *(TODO: what happens if not?)*
+    default_reducer : numpy.ufunc
+        Default reducer to use when no reducer is specified for an axis. By default,
+        this is [`numpy.max`][].
     channel_mode : ChannelMode
         How to display channel information:
-            - `GRAYSCALE`: ignore channel axis, use `default_lut`
-            - `COMPOSITE`: display all channels as a composite image, using `luts`
-            - `COLOR`: display a single channel at a time, using `luts`
-            - `RGBA`: display as an RGB image, using `default_lut` (except for cmap)
+
+        - `GRAYSCALE`: ignore channel axis, use `default_lut`
+        - `COMPOSITE`: display all channels as a composite image, using `luts`
+        - `COLOR`: display a single channel at a time, using `luts`
+        - `RGBA`: display as an RGB image, using `default_lut` (except for cmap)
 
         If `channel_mode` is set to anything other than `GRAYSCALE`, then `channel_axis`
         must be set to a valid axis; if no `channel_axis` is set, at the time of
-        display, the `DataWrapper` MAY guess the `channel_axis`, and set it on the
-        model.
-    channel_axis : AxisKey | None
+        display, the [`DataWrapper`][ndv.DataWrapper] MAY guess the `channel_axis`,
+        and set it on the model.
+    channel_axis : Hashable | None
         The dimension index or name of the channel dimension.
         The implication of setting channel_axis is that *all* elements along the channel
         dimension are shown, with different LUTs applied to each channel.
@@ -151,18 +167,24 @@ class ArrayDisplayModel(NDVModel):
         Values are `LUT` objects that specify how to display the channel.
         The special key `None` is used to represent a fallback LUT for all channels,
         and is used when `channel_axis` is None.  It should always be present
+    default_lut : LUTModel
+        Default lookup table to use when no `LUTModel` is specified for a channel in
+        `luts`.
     """
 
     visible_axes: TwoOrThreeAxisTuple = (-2, -1)
+    # NOTE: In terms of requesting data, there is a slight "delocalization" of state
+    # here in that we probably also want to avoid requesting data for channel
+    # positions that are not visible.
     current_index: IndexMap = Field(default_factory=IndexMap, frozen=True)
 
-    channel_mode: ChannelMode = ChannelMode.GRAYSCALE
-    channel_axis: Optional[AxisKey] = None
-
     # map of axis to reducer (function that can reduce dimensionality along that axis)
     reducers: Reducers = Field(default_factory=Reducers, frozen=True)
     default_reducer: ReducerType = "numpy.max"  # type: ignore [assignment]  # FIXME
 
+    channel_mode: ChannelMode = ChannelMode.GRAYSCALE
+    channel_axis: Optional[AxisKey] = None
+
     # map of index along channel axis to LUTModel object
     luts: LutMap = Field(default_factory=_default_luts)
     default_lut: LUTModel = Field(default_factory=LUTModel, frozen=True)

src/ndv/models/_data_wrapper.py

@@ -56,12 +56,13 @@ def _recurse_subclasses(cls: _T) -> Iterator[_T]:
 class DataWrapper(Generic[ArrayT], ABC):
     """Interface for wrapping different array-like data types.
 
-    `DataWrapper.create` is a factory method that returns a DataWrapper instance
-    for the given data type. If your datastore type is not supported, you may implement
-    a new DataWrapper subclass to handle your data type.  To do this, import and
-    subclass DataWrapper, and (minimally) implement the supports and isel methods.
-    Ensure that your class is imported before the DataWrapper.create method is called,
-    and it will be automatically detected and used to wrap your data.
+    [`DataWrapper.create()`][ndv.DataWrapper.create] is a factory method that returns a
+    `DataWrapper` instance for the given data type. If your datastore type is not
+    supported, you may implement a new `DataWrapper` subclass to handle your data type.
+    To do this, import and subclass `DataWrapper`, and (minimally) implement the
+    supports and isel methods. Ensure that your class is imported before the
+    `DataWrapper.create` method is called, and it will be automatically detected and
+    used to wrap your data.
     """
 
     # Order in which subclasses are checked for support.
@@ -102,7 +103,10 @@ def coords(self) -> Mapping[Hashable, Sequence]:
 
     @abstractmethod
     def isel(self, index: Mapping[int, int | slice]) -> np.ndarray:
-        """Return a slice of the data as a numpy array."""
+        """Return a slice of the data as a numpy array.
+
+        `index` will look like (e.g.) `{0: slice(0, 10), 1: 5}`.
+        """
 
     def save_as_zarr(self, path: str) -> None:
         raise NotImplementedError("Saving as zarr is not supported for this data type")
@@ -122,6 +126,21 @@ def dtype(self) -> np.dtype:
 
     @classmethod
     def create(cls, data: ArrayT) -> DataWrapper[ArrayT]:
+        """Create a DataWrapper instance for the given data.
+
+        This method will detect all subclasses of DataWrapper and check them in order of
+        their `PRIORITY` class variable. The first subclass that
+        [`supports`][ndv.DataWrapper.supports] the given data will be used to wrap it.
+
+        !!! tip
+
+            This means that you can subclass DataWrapper to handle new data types.
+            Just make sure that your subclass is imported before calling `create`.
+
+        If no subclasses support the data, a `NotImplementedError` is raised.
+
+        If an instance of `DataWrapper` is passed in, it will be returned as-is.
+        """
         if isinstance(data, DataWrapper):
             return data
 

src/ndv/models/_lut_model.py

@@ -136,13 +136,17 @@ class LUTModel(NDVModel):
     visible : bool
         Whether to display this channel.
         NOTE: This has implications for data retrieval, as we may not want to request
-        channels that are not visible.  See current_index above.
+        channels that are not visible.
+        See [`ArrayDisplayModel.current_index`][ndv.models.ArrayDisplayModel].
     cmap : cmap.Colormap
-        Colormap to use for this channel.
-    clims : Union[ManualClims, PercentileClims, StdDevClims, MinMaxClims]
-        Method for determining the contrast limits for this channel.
+        [`cmap.Colormap`](https://cmap-docs.readthedocs.io/colormaps/) to use for this
+        channel.  This can be expressed as any channel.  This can be expressed as any
+        ["colormap like" object](https://cmap-docs.readthedocs.io/en/latest/colormaps/#colormaplike-objects)
+    clims : Union[ClimsManual, ClimsPercentile, ClimsStdDev, ClimsMinMax]
+        Method for determining the contrast limits for this channel.  If a 2-element
+        `tuple` or `list` is provided, it is interpreted as a manual contrast limit.
     gamma : float
-        Gamma correction for this channel. By default, 1.0.
+        Gamma applied to the data before applying the colormap. By default, `1.0`.
     """
 
     visible: bool = True

src/ndv/util.py

@@ -28,7 +28,10 @@ def imshow(
     display_model: ArrayDisplayModel | None = None,
     **kwargs: Unpack[ArrayDisplayModelKwargs],
 ) -> ArrayViewer:
-    """Display an array or DataWrapper in a new NDViewer window.
+    """Display an array or DataWrapper in a new `ArrayViewer` window.
+
+    This convenience function creates an `ArrayViewer` instance populated with `data`,
+    calls `show()` on it, and then runs the application.
 
     Parameters
     ----------
@@ -37,12 +40,13 @@ def imshow(
     display_model: ArrayDisplayModel, optional
         The display model to use. If not provided, a new one will be created.
     kwargs : Unpack[ArrayDisplayModelKwargs]
-        Additional keyword arguments to pass to the NDViewer
+        Additional keyword arguments used to create the
+        [`ArrayDisplayModel`][ndv.models.ArrayDisplayModel].
 
     Returns
     -------
     ArrayViewer
-        The viewer window.
+        The `ArrayViewer` instance.
     """
     viewer = ArrayViewer(data, display_model, **kwargs)
     viewer.show()

src/ndv/views/_app.py

@@ -586,7 +586,7 @@ def filter_mouse_events(canvas: Any, receiver: Mouseable) -> Callable[[], None]:
 
 
 def run_app() -> None:
-    """Start the GUI application event loop."""
+    """Start the active GUI application event loop."""
     GUI_PROVIDERS[gui_frontend()].exec()