waveorder 3.0.0a1__tar.gz → 3.0.0a2__tar.gz

waveorder-3.0.0a2/.github/workflows/test.yml

@@ -0,0 +1,39 @@
+name: test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    name: ${{ matrix.platform }} py${{ matrix.python-version }}
+    runs-on: ${{ matrix.platform }}
+    strategy:
+      matrix:
+        platform: [ubuntu-latest, windows-latest, macos-latest]
+        python-version: ["3.11", "3.12", "3.13"]
+
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v5
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - uses: pyvista/setup-headless-display-action@v4
+        with:
+          qt: true
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install '.[all,dev]'
+
+      - name: Test
+        run: python -m pytest -v --color=yes --cov=waveorder --cov-report=xml
+
+      - name: Coverage
+        uses: codecov/codecov-action@v3

{waveorder-3.0.0a1 → waveorder-3.0.0a2}/.gitignore

@@ -2,7 +2,6 @@
 *.tif[f]
 *.jp[e]g
 *.zar[r]
-*.json
 
 # pycharm IDE
 .idea
@@ -19,6 +18,8 @@ __pycache__/
 # Distribution / packaging
 .Python
 build/
+docs/build/
+docs/wo_examples/
 develop-eggs/
 dist/
 downloads/
@@ -148,7 +149,6 @@ waveorder/_version.py
 
 # images
 *.npz
-*.png
 *.tif[f]
 *.pdf
 

waveorder-3.0.0a2/.readthedocs.yaml

@@ -0,0 +1,28 @@
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version, and other tools you might need
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.12"
+  jobs:
+    post_build:
+      - python docs/scripts/fix_md_links.py
+
+# Optionally, but recommended,
+# declare the Python requirements required to build your documentation
+# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+   configuration: docs/conf.py

{waveorder-3.0.0a1 → waveorder-3.0.0a2}/CONTRIBUTING.md

@@ -41,15 +41,18 @@ git clone https://github.com/mehta-lab/waveorder.git
 Otherwise, you can follow [these instructions](https://docs.github.com/en/get-started/quickstart/fork-a-repo)
 to [fork](https://github.com/mehta-lab/waveorder/fork) the repository.
 
-Then install the package in editable mode with the development dependencies:
+Next, install the package in editable mode with all dependencies
 
 ```sh
 cd waveorder/ # or the renamed project root directory
-pip install -e ".[dev]"
+pip install -e ".[all]"
+```
+and check that the tests pass with
+```sh
+pytest
 ```
 
-Then make the changes and [track them with Git](https://docs.github.com/en/get-started/using-git/about-git#example-contribute-to-an-existing-repository).
-
+Finally, make the changes and [track them with Git](https://docs.github.com/en/get-started/using-git/about-git#example-contribute-to-an-existing-repository).
 
 ### Code style
 
@@ -60,3 +63,25 @@ pre-commit install
 ```
 
 When these packages are executed within the project root directory, they should automatically use the [project settings](./pyproject.toml).
+
+### Developing documentation
+
+Documentation infrastructure is built using [Markdown (.md)](https://www.sphinx-doc.org/en/master/usage/markdown.html) and [reStructuredText (.rst)](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html) files. [Sphinx](https://www.sphinx-doc.org/en/master/index.html) utilizes these to build highly customization .html pages for User Guides, API References and Examples rendered directly from source code files.
+
+#### Building the HTML version locally
+
+```sh
+cd waveorder/ # or the renamed project root directory
+pip install -e ".[all]"
+cd docs/
+sphinx-build -M html ./ ./build
+```
+
+Generated HTML documentation can be found in the ``build/html`` directory. Open ``build/html/index.html`` to view the home page for the documentation.
+
+Automated building of `docs` is done via _read-the-docs_ which will automatically pull commits to the `main` branch and host them here: <https://waveorder.readthedocs.io>
+
+#### Documentation change
+
+If you find that any documentation in this project is incomplete, inaccurate, or ambiguous, please open an issue.
+We welcome contributions to the documentation from users, particularly user guides that we can collaboratively edit.

{waveorder-3.0.0a1 → waveorder-3.0.0a2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: waveorder
-Version: 3.0.0a1
+Version: 3.0.0a2
 Summary: Wave-optical simulations and deconvolution of optical properties
 Author-email: CZ Biohub SF <compmicro@czbiohub.org>
 Maintainer-email: Talon Chandler <talon.chandler@czbiohub.org>, Shalin Mehta <shalin.mehta@czbiohub.org>
@@ -56,7 +56,7 @@ License-File: LICENSE
 Requires-Dist: click>=8.0.1
 Requires-Dist: colorspacious>=1.1.2
 Requires-Dist: importlib-metadata
-Requires-Dist: iohub<0.3,>=0.2
+Requires-Dist: iohub<0.4,>=0.2
 Requires-Dist: ipywidgets>=7.5.1
 Requires-Dist: matplotlib>=3.1.1
 Requires-Dist: natsort>=7.1.1
@@ -69,20 +69,36 @@ Requires-Dist: scipy>=1.3.0
 Requires-Dist: torch>=2.4.1
 Requires-Dist: qtpy
 Requires-Dist: wget>=3.2
-Provides-Extra: all
-Requires-Dist: napari[pyqt6]; extra == "all"
-Requires-Dist: napari-ome-zarr>=0.3.2; extra == "all"
-Requires-Dist: pycromanager==0.27.2; extra == "all"
-Requires-Dist: jupyter; extra == "all"
+Provides-Extra: visual
+Requires-Dist: napari[pyqt6]; extra == "visual"
+Requires-Dist: napari-ome-zarr>=0.3.2; extra == "visual"
+Requires-Dist: pycromanager==0.27.2; extra == "visual"
+Requires-Dist: jupyter; extra == "visual"
 Provides-Extra: dev
 Requires-Dist: black==25.1.0; extra == "dev"
 Requires-Dist: click>=8.2.0; extra == "dev"
 Requires-Dist: hypothesis; extra == "dev"
+Requires-Dist: napari[pyqt6]; extra == "dev"
 Requires-Dist: pre-commit; extra == "dev"
 Requires-Dist: pytest-cov; extra == "dev"
 Requires-Dist: pytest-qt; extra == "dev"
 Requires-Dist: pytest>=5.0.0; extra == "dev"
-Requires-Dist: tox; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: sphinx_copybutton; extra == "docs"
+Requires-Dist: sphinxcontrib-video; extra == "docs"
+Requires-Dist: myst_parser; extra == "docs"
+Requires-Dist: sphinx_mdinclude; extra == "docs"
+Requires-Dist: linkify-it-py; extra == "docs"
+Requires-Dist: numpydoc; extra == "docs"
+Requires-Dist: sphinx_sitemap; extra == "docs"
+Requires-Dist: sphinx_gallery; extra == "docs"
+Requires-Dist: pydata_sphinx_theme; extra == "docs"
+Requires-Dist: matplotlib; extra == "docs"
+Requires-Dist: importlib_metadata; extra == "docs"
+Provides-Extra: all
+Requires-Dist: waveorder[visual]; extra == "all"
+Requires-Dist: waveorder[dev]; extra == "all"
+Requires-Dist: waveorder[docs]; extra == "all"
 Dynamic: license-file
 
 <p align="center">
@@ -288,23 +304,32 @@ conda create -y -n waveorder python=3.12
 conda activate waveorder
 ```
 
-Install `waveorder` from PyPI:
-
+Most users should install `waveorder` with:
 ```sh
-pip install waveorder
+pip install waveorder[visual]
 ```
 
-(Optional) Install all visualization dependencies (napari, jupyter), clone the repository, and run an example script:
+We also maintain three dependency sets for different interfaces:
+
 ```sh
-pip install "waveorder[all]"
-git clone https://github.com/mehta-lab/waveorder.git
-python waveorder/examples/models/phase_thick_3d.py
+pip install waveorder          # API, CLI
+pip install waveorder[visual]  # API, CLI, GUI  
+pip install waveorder[all]     # API, CLI, GUI, docs, dev dependencies
 ```
 
+
+
 (M1 users) `pytorch` has [incomplete GPU support](https://github.com/pytorch/pytorch/issues/77764),
 so please use `export PYTORCH_ENABLE_MPS_FALLBACK=1`
 to allow some operators to fallback to CPU if you plan to use GPU acceleration for polarization reconstruction.
 
 
 ## Examples
-The [examples](https://github.com/mehta-lab/waveorder/tree/main/docs/examples) illustrate simulations and reconstruction for 2D QLIPP, 3D phase from brightfield, and 2D/3D PTI methods.
+The [examples](https://github.com/mehta-lab/waveorder/tree/main/docs/examples) illustrate simulations and reconstruction for 2D QLIPP, 3D phase from brightfield, and 2D/3D PTI methods. To run examples, use
+
+```sh
+git clone https://github.com/mehta-lab/waveorder.git
+cd waveorder
+pip install -e .[all]
+python ./docs/examples/models/phase_thick_3d.py
+```

{waveorder-3.0.0a1 → waveorder-3.0.0a2}/README.md

@@ -201,23 +201,32 @@ conda create -y -n waveorder python=3.12
 conda activate waveorder
 ```
 
-Install `waveorder` from PyPI:
-
+Most users should install `waveorder` with:
 ```sh
-pip install waveorder
+pip install waveorder[visual]
 ```
 
-(Optional) Install all visualization dependencies (napari, jupyter), clone the repository, and run an example script:
+We also maintain three dependency sets for different interfaces:
+
 ```sh
-pip install "waveorder[all]"
-git clone https://github.com/mehta-lab/waveorder.git
-python waveorder/examples/models/phase_thick_3d.py
+pip install waveorder          # API, CLI
+pip install waveorder[visual]  # API, CLI, GUI  
+pip install waveorder[all]     # API, CLI, GUI, docs, dev dependencies
 ```
 
+
+
 (M1 users) `pytorch` has [incomplete GPU support](https://github.com/pytorch/pytorch/issues/77764),
 so please use `export PYTORCH_ENABLE_MPS_FALLBACK=1`
 to allow some operators to fallback to CPU if you plan to use GPU acceleration for polarization reconstruction.
 
 
 ## Examples
-The [examples](https://github.com/mehta-lab/waveorder/tree/main/docs/examples) illustrate simulations and reconstruction for 2D QLIPP, 3D phase from brightfield, and 2D/3D PTI methods.
+The [examples](https://github.com/mehta-lab/waveorder/tree/main/docs/examples) illustrate simulations and reconstruction for 2D QLIPP, 3D phase from brightfield, and 2D/3D PTI methods. To run examples, use
+
+```sh
+git clone https://github.com/mehta-lab/waveorder.git
+cd waveorder
+pip install -e .[all]
+python ./docs/examples/models/phase_thick_3d.py
+```

{waveorder-3.0.0a1 → waveorder-3.0.0a2}/docs/README.md

@@ -4,24 +4,25 @@ We have organized our documentation by user type and intended task.
 
 ## Software users
 
-**Reconstruct existing data:** start with the [reconstruction guide](./reconstruction-guide.md) and consult the [data schema](./data-schema.md) for `waveorder`'s data format.
+**Reconstruct existing data:** start with the [reconstruction guide](guide/reconstruction-guide.md) and consult the [data schema](guide/data-schema.md) for `waveorder`'s data format.
 
-**Reconstruct with a GUI:** start with the [plugin's reconstruction guide](./napari-plugin-guide.md#reconstruction-tab).
+**Reconstruct with a GUI:** start with the [plugin's reconstruction guide](guide/napari-plugin-guide.md#acquisition--reconstruction-tab).
 
-**Integrate `waveorder` into my software:** start with [`examples/`](./examples/)
+
+**Integrate `waveorder` into my software:** start with [`examples/`](examples/)
 
 ## Hardware users
 
-**Buy hardware for a polarized-light installation:** start with the [buyer's guide](./buyers-guide.md).
+**Buy hardware for a polarized-light installation:** start with the [buyer's guide](guide/buyers-guide.md).
 
-**Install `waveorder` on my microscope:** start with the [microscope installation guide](./microscope-installation-guide.md).
+**Install `waveorder` on my microscope:** start with the [microscope installation guide](guide/microscope-installation-guide.md).
 
-**Use the `napari plugin` to calibrate:** start with the [plugin guide](./napari-plugin-guide.md).
+**Use the `napari plugin` to calibrate:** start with the [plugin guide](guide/napari-plugin-guide.md).
 
-**Understand `waveorder`'s calibration routine**: read the [calibration guide](./calibration-guide.md).
+**Understand `waveorder`'s calibration routine**: read the [calibration guide](guide/calibration-guide.md).
 
 ## Software developers
 
-**Set up a development environment and test `waveorder`**: start with the [development guide](./development-guide.md).
+**Set up a development environment and test `waveorder`**: start with the [development guide](guide/development-guide.md).
 
 **Report an error in the documentation or code:** [open an issue](https://github.com/mehta-lab/waveorder/issues/new/choose) or [send us an email](mailto:shalin.mehta@czbiohub.org,talon.chandler@czbiohub.org). We appreciate your help!

waveorder-3.0.0a2/docs/_static/css/custom.css

@@ -0,0 +1,8 @@
+blockquote {
+	background-color: var(--pst-color-background);
+	border-left: none;
+}
+
+video {
+    width: -webkit-fill-available;
+}

waveorder-3.0.0a2/docs/_static/switcher.json

@@ -0,0 +1,14 @@
+[
+    {
+        "version": "latest",
+        "url": "/en/latest/index.html"
+    },
+    {
+        "version": "v3.0.0a0",
+        "url": "/en/v3.0.0a0/index.html"
+    },
+    {
+        "version": "v2.2.1",
+        "url": "/en/v2.2.1/index.html"
+    }
+]

waveorder-3.0.0a2/docs/api/settings.rst

@@ -0,0 +1,6 @@
+Settings
+========
+
+.. automodule:: waveorder.cli.settings
+    :members:
+    :undoc-members:

waveorder-3.0.0a2/docs/api/stokes.rst

@@ -0,0 +1,5 @@
+Stokes
+========
+
+.. automodule:: waveorder.stokes
+    :members:

waveorder-3.0.0a2/docs/api.rst

@@ -0,0 +1,14 @@
+API Reference
+=============
+
+.. toctree::
+    :maxdepth: 3
+
+    api/settings
+    api/stokes
+
+Index
+-----
+
+* :ref:`genindex`
+* :ref:`search`

waveorder-3.0.0a2/docs/conf.py

@@ -0,0 +1,250 @@
+# -*- coding: utf-8 -*-
+
+
+import os
+import re
+
+# Add any Sphinx extension module names, as strings. They can be extensions
+# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
+import sys
+
+import importlib_metadata
+
+# -- General configuration ----------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+# needs_sphinx = '1.0'
+
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+sys.path.insert(0, os.path.abspath("../"))
+
+source_dir = os.path.dirname(__file__)
+sys.path.insert(0, os.path.join(source_dir, "ext"))
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.doctest",
+    "sphinx.ext.mathjax",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.extlinks",
+    "sphinx.ext.viewcode",
+    "sphinx_copybutton",
+    "numpydoc",
+    "myst_parser",
+    "sphinx_sitemap",
+    "sphinxcontrib.video",
+    "sphinx_gallery.gen_gallery",
+]
+
+myst_enable_extensions = [
+    "amsmath",
+    "attrs_inline",
+    "colon_fence",
+    "deflist",
+    "dollarmath",
+    "fieldlist",
+    "linkify",
+    "html_admonition",
+    "html_image",
+    "replacements",
+    "smartquotes",
+    "strikethrough",
+    "substitution",
+    "tasklist",
+]
+
+myst_file_suffixes = [".md"]
+myst_all_links_external = True
+
+# default url is a dummy for local build
+html_baseurl = os.environ.get("GITHUB_PAGES_URL", f"/build/html/")
+sitemap_locales = ["en"]
+sitemap_url_scheme = "{link}"
+
+numpydoc_show_class_members = True
+
+# Add any paths that contain templates here, relative to this directory.
+# templates_path = ["_templates"]
+
+# The suffix of source filenames.
+source_suffix = {
+    ".rst": "restructuredtext",
+    ".md": "markdown",
+}
+
+# The encoding of source files.
+# source_encoding = 'utf-8-sig'
+
+# The master toctree document.
+master_doc = "index"
+
+# General information about the project.
+project = "waveorder"
+copyright = "2023. Talon Chandler. Chan Zuckerberg Biohub. All rights reserved"
+release = importlib_metadata.version("waveorder")
+
+json_url = f"./_static/switcher.json"
+if "dev" in release or "rc" in release:
+    # json_url = "_static/switcher.json"
+    version_match = "latest"
+else:
+    version_match = release
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+# language = None
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+# today = ''
+# Else, today_fmt is used as the format for a strftime call.
+# today_fmt = '%B %d, %Y'
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+exclude_patterns = []
+
+# The reST default role (used for this markup `text`) to use for all documents.
+# default_role = None
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+# add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+# add_module_names = True
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+# show_authors = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = "default"
+
+# A list of ignored prefixes for module index sorting.
+# modindex_common_prefix = []
+
+
+# -- Options for HTML output --------------------------------------------------
+
+html_theme = "pydata_sphinx_theme"
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+html_theme_options = {
+    "show_toc_level": 2,
+    "switcher": {
+        "json_url": json_url,
+        "version_match": version_match,
+    },
+    "icon_links": [
+        {
+            "name": "GitHub",
+            "url": "https://github.com/mehta-lab/waveorder",
+            "icon": "fa-brands fa-square-github",
+            "type": "fontawesome",
+        }
+    ],
+    "navbar_end": ["theme-switcher", "navbar-icon-links", "version-switcher"],
+}
+
+# Add any paths that contain custom themes here, relative to this directory.
+# html_theme_path = []
+
+# The name for this set of Sphinx documents.  If None, it defaults to
+# "<project> v<release> documentation".
+html_title = "waveorder"
+
+# A shorter title for the navigation bar.  Default is the same as html_title.
+# html_short_title = None
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+# html_logo = "resources/1.png"
+
+
+# The name of an image file (within the static path) to use as favicon of the
+# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+# emoji favicon code adapted from:
+# https://twitter.com/LeaVerou/status/1241619866475474946
+html_favicon = "_static/waveorder.ico"
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ["_static"]
+html_css_files = [
+    "css/custom.css",  # Adjust path if your CSS is in a subdirectory
+]
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+# html_last_updated_fmt = '%b %d, %Y'
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+# html_use_smartypants = True
+
+# Custom sidebar templates, maps document names to template names.
+html_sidebars = {"**": ["sidebar-nav-bs"]}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+# html_additional_pages = {}
+
+# If false, no module index is generated.
+# html_domain_indices = True
+
+# If false, no index is generated.
+# html_use_index = True
+
+# If true, the index is split into individual pages for each letter.
+# html_split_index = False
+
+# If true, links to the reST sources are added to the pages.
+# html_show_sourcelink = True
+
+# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
+html_show_sphinx = False
+
+# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
+# html_show_copyright = True
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a <link> tag referring to it.  The value of this option must be the
+# base URL from which the finished HTML is served.
+# html_use_opensearch = ''
+
+# This is the file name suffix for HTML files (e.g. ".xhtml").
+# html_file_suffix = None
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = "waveorderdoc"
+
+numpydoc_show_class_members = False
+
+# sphinx-gallery config
+sphinx_gallery_conf = {
+    "examples_dirs": ["examples"],
+    "gallery_dirs": ["wo_examples"],
+    "download_all_examples": False,
+    "filename_pattern": "/run_",
+    "show_signature": False,
+    "write_computation_times": False,
+}
+
+
+def setup(app):
+    app.connect("source-read", transform_md_links)
+
+
+def transform_md_links(app, docname, source):
+    content = source[0]
+    # Transform .md links to .html for Sphinx build
+    content = re.sub(r"\]\(([^)#]+?)\.md(#[^)]+)?\)", r"](\1.html\2)", content)
+    source[0] = content

waveorder-3.0.0a2/docs/contact_us.rst

@@ -0,0 +1,15 @@
+Contact Us
+==========
+
+If you would like to report a bug, request a feature, or communicate any related problem,
+please create an issue on our
+`GitHub repository <https://github.com/mehta-lab/waveorder>`_
+if there is not an existing issue on the topic.
+You can also track pull-requests, milestones and our plans on our repository.
+
+Contributing
+------------
+
+Feel free to participate in discussions and contribute,
+but do not forget to read our
+`contributing guidelines <https://github.com/mehta-lab/waveorder/blob/main/CONTRIBUTING.md>`_ first.