eye-patch 1.0.0__tar.gz → 1.0.0a0__tar.gz

{eye_patch-1.0.0 → eye_patch-1.0.0a0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: eye-patch
-Version: 1.0.0
+Version: 1.0.0a0
 Summary: The pirate mask.
 Project-URL: Homepage, https://github.com/flint-crew/eye-patch
 Project-URL: Bug Tracker, https://github.com/flint-crew/eye-patch/issues
@@ -34,10 +34,6 @@ Description-Content-Type: text/markdown
 
 # Eye Patch
 
-The pirate mask!
-
-<img width="256" height="256" alt="image" src="https://github.com/user-attachments/assets/2a8e442c-036b-4d78-8370-180c02588c95" />
-
 [![Actions Status][actions-badge]][actions-link]
 [![Documentation Status][rtd-badge]][rtd-link]
 [![PyPI version][pypi-version]][pypi-link]
@@ -58,3 +54,73 @@ The pirate mask!
 [coverage-link]:            https://codecov.io/github/flint-crew/eye-patch
 
 <!-- prettier-ignore-end -->
+
+The pirate mask!
+
+A python library and CLI tools for creating masks to assist deconvolution of
+interferometric data.
+
+This library was originally the masking module of the
+[Flint](https://github.com/flint-crew/flint) pipeline, but has now been
+separated out for flexible use.
+
+<img width="256" height="256" alt="image" src="https://github.com/user-attachments/assets/2a8e442c-036b-4d78-8370-180c02588c95" />
+
+## Documentation
+
+Full documentation is provided on
+[ReadtheDocs](https://eye-patch.readthedocs.io/).
+
+## Installation
+
+We publish releases on PyPI:
+
+```bash
+# PyPI release
+pip install eye-patch
+```
+
+You can also install directly from the git repository:
+
+```bash
+# Direct git install (latest push)
+pip install git+https://github.com/flint-crew/eye-patch.git
+```
+
+Or, from a local clone:
+
+```bash
+git clone https://github.com/flint-crew/eye-patch.git
+cd flint
+pip install -e .
+```
+
+We highly recommend using [uv](https://docs.astral.sh/uv/) for speedy
+installations. Reproducible builds can be created using `uv sync`:
+
+```bash
+git clone https://github.com/flint-crew/eye-patch.git
+uv venv
+uv sync
+```
+
+## Contributions
+
+Contributions are welcome! Please do submit a pull-request or issue if you spot
+something you would like to address.
+
+The full set of dev tooling can be installed via:
+
+```bash
+git clone https://github.com/flint-crew/eye-patch.git
+cd eye-patch
+pip install '.[dev]'
+```
+
+Or, using `uv`:
+
+```bash
+git clone https://github.com/flint-crew/eye-patch.git
+cd flint
+uv sync --group dev
+```

eye_patch-1.0.0a0/README.md

@@ -0,0 +1,92 @@
+# Eye Patch
+
+[![Actions Status][actions-badge]][actions-link]
+[![Documentation Status][rtd-badge]][rtd-link]
+[![PyPI version][pypi-version]][pypi-link]
+[![PyPI platforms][pypi-platforms]][pypi-link]
+[![Coverage][coverage-badge]][coverage-link]
+
+<!-- SPHINX-START -->
+
+<!-- prettier-ignore-start -->
+[actions-badge]:            https://github.com/flint-crew/eye-patch/workflows/CI/badge.svg
+[actions-link]:             https://github.com/flint-crew/eye-patch/actions
+[pypi-link]:                https://pypi.org/project/eye-patch/
+[pypi-platforms]:           https://img.shields.io/pypi/pyversions/eye-patch
+[pypi-version]:             https://img.shields.io/pypi/v/eye-patch
+[rtd-badge]:                https://readthedocs.org/projects/eye-patch/badge/?version=latest
+[rtd-link]:                 https://eye-patch.readthedocs.io/en/latest/?badge=latest
+[coverage-badge]:           https://codecov.io/github/flint-crew/eye-patch/branch/main/graph/badge.svg
+[coverage-link]:            https://codecov.io/github/flint-crew/eye-patch
+
+<!-- prettier-ignore-end -->
+
+The pirate mask!
+
+A python library and CLI tools for creating masks to assist deconvolution of
+interferometric data.
+
+This library was originally the masking module of the
+[Flint](https://github.com/flint-crew/flint) pipeline, but has now been
+separated out for flexible use.
+
+<img width="256" height="256" alt="image" src="https://github.com/user-attachments/assets/2a8e442c-036b-4d78-8370-180c02588c95" />
+
+## Documentation
+
+Full documentation is provided on
+[ReadtheDocs](https://eye-patch.readthedocs.io/).
+
+## Installation
+
+We publish releases on PyPI:
+
+```bash
+# PyPI release
+pip install eye-patch
+```
+
+You can also install directly from the git repository:
+
+```bash
+# Direct git install (latest push)
+pip install git+https://github.com/flint-crew/eye-patch.git
+```
+
+Or, from a local clone:
+
+```bash
+git clone https://github.com/flint-crew/eye-patch.git
+cd flint
+pip install -e .
+```
+
+We highly recommend using [uv](https://docs.astral.sh/uv/) for speedy
+installations. Reproducible builds can be created using `uv sync`:
+
+```bash
+git clone https://github.com/flint-crew/eye-patch.git
+uv venv
+uv sync
+```
+
+## Contributions
+
+Contributions are welcome! Please do submit a pull-request or issue if you spot
+something you would like to address.
+
+The full set of dev tooling can be installed via:
+
+```bash
+git clone https://github.com/flint-crew/eye-patch.git
+cd eye-patch
+pip install '.[dev]'
+```
+
+Or, using `uv`:
+
+```bash
+git clone https://github.com/flint-crew/eye-patch.git
+cd flint
+uv sync --group dev
+```

eye_patch-1.0.0a0/docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

eye_patch-1.0.0a0/docs/conf.py

@@ -0,0 +1,73 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+from __future__ import annotations
+
+import eye_patch
+
+project = "eye-patch"
+copyright = "2025, Tim Galvin"
+author = "Tim Galvin"
+version = release = eye_patch.__version__
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+
+extensions = [
+    "myst_parser",
+    "sphinx.ext.autodoc",
+    "sphinx_autodoc_typehints",
+    "sphinx.ext.doctest",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.todo",
+    "sphinx.ext.coverage",
+    "sphinx.ext.mathjax",
+    "sphinx.ext.ifconfig",
+    "sphinx.ext.viewcode",
+    "sphinx.ext.githubpages",
+    "sphinx.ext.napoleon",
+    "sphinx_copybutton",
+    "autoapi.extension",
+    "sphinxarg.ext",
+]
+
+myst_enable_extensions = [
+    "colon_fence",
+]
+
+autoapi_type = "python"
+autoapi_dirs = ["../eye_patch"]
+autoapi_member_order = "groupwise"
+autoapi_keep_files = False
+autoapi_root = "autoapi"
+autoapi_add_toctree_entry = True
+
+# Napoleon settings
+napoleon_google_docstring = True
+napoleon_numpy_docstring = True
+napoleon_include_init_with_doc = True
+napoleon_include_private_with_doc = True
+napoleon_include_special_with_doc = True
+napoleon_use_admonition_for_examples = False
+napoleon_use_admonition_for_notes = False
+napoleon_use_admonition_for_references = False
+napoleon_use_ivar = False
+napoleon_use_param = True
+napoleon_use_rtype = True
+
+source_suffix = [".rst", ".md"]
+templates_path = ["_templates"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = "furo"
+# html_theme = "sphinx_rtd_theme"
+html_static_path = ["_static"]

{eye_patch-1.0.0 → eye_patch-1.0.0a0}/docs/index.md

@@ -1,15 +1,16 @@
-# eye-patch
-
-```{toctree}
-:maxdepth: 2
-:hidden:
-
-```
+# Eye Patch
 
 ```{include} ../README.md
 :start-after: <!-- SPHINX-START -->
 ```
 
+## Table of contents
+
+```{toctree}
+:maxdepth: 1
+masking.md
+```
+
 ## Indices and tables
 
 - {ref}`genindex`

eye_patch-1.0.0a0/docs/masking.md

@@ -0,0 +1,214 @@
+# Creating Clean Masks
+
+The imaging performance of CLEAN and its derivatives can be improved through the
+construction of reliable clean mask regions. These regions restrict the set of
+pixels that are involved during the peak finding stage of CLEAN. Here the aim of
+the game is to optimally select pixels that contain genuine emission. Issues
+such as clean bias. sub-optimal self-calibration and clean divergence can be
+minimised or outright eliminated provided a clean mask has been reliable
+constructed.
+
+`eye-patch` provides functionality to construct such clean masks, where the
+output is a pixel-wise mask of arbitrary shapes that either allow of deny
+cleaning to occur at certain pixel locations. These are intended to be evaluated
+against a restored FITS image. Pixels in the output clean mask are either `0`
+(cleaning is not allowed here) or `1` (cleaning is allowed here).
+
+## Available statistics
+
+`eye-patch` currently supports two statistics to identify pixels of significance
+that should be cleaned.
+
+### Signal-to-noise (SNR)
+
+The obvious method is based on signal-to-noise (SNR). After constructing
+background ({math}`\mu`) and noise ({math}`\sigma`) measures across an image a
+direction-dependent SNR ({math}`\mathrm{SNR}`) across the image
+({math}`\mathrm{img}`) can be expressed:
+
+{math}`\mathrm{SNR}(x,y) = \frac{\left(\mathrm{img}-\mu\right)}{\sigma}.`
+
+In the simplest case constant values may be set across the extent of the image
+{math}`\mu=0`, and {math}`\sigma=\mathrm{SD}(\mathrm{img})`. These can be
+replaced with more sophisticated schemes that compute position dependent metrics
+that also incorporate iterative outlier clipping (e.g.
+[Background and Noise Estimator](https://github.com/PaulHancock/Aegean)) or
+robust statistics (e.g.
+[Selavy](https://www.atnf.csiro.au/computing/software/askapsoft/sdp/docs/current/analysis/selavy.html)).
+
+At their heart these SNR based processes are assuming Gaussian distributed
+zero-mean noise, where pixel intensities that are unlikely to occur by chance
+are assumed to be genuine emission. That is to say, pixels that are
+{math}`\gg5\sigma` are likely to be real and should be included in a mask for
+cleaning.
+
+### Minimum absolute clip
+
+SNR based measures have a clear statistical foundation when identifying bright
+pixels. However, there are situations when such a metric could be perturbed or
+otherwise corrupted, including:
+
+- Calibration errors that produce imaging artefacts,
+- Deconvolution errors that accumulate over minor/major iterations,
+- Mishandling of the w-term so that the 2D Fourier transform approximation
+  breaks down,
+- Extended diffuse structures that represents a large fraction of the region
+  used to calculate the local {math}`\mu` or {math}`\sigma` quantities,
+- Combinations of the above, or
+- Gremlins lurking around in the data.
+
+Ultimately, if the regions being considered in the derivation of the noise do
+not appear Gaussian like, the robustness of methods to calculate the local noise
+level are suspect. Additionally, it is unclear whether an accurate noise
+estimation is even an appropriate basis for such regions. For instance,
+artefacts around a bright sources produced by phase error could be
+{math}`\gg\sigma` if the genuine source is sufficiently bright.
+
+We introduce the Minimum Absolute Clip ({math}`\mathrm{MAC}`) as an alternative
+metric. By assuming:
+
+1. approximately zero-mean distributed Gaussian noise,
+2. the sky brightness is positive definite, and
+3. should there be a significantly bright negative component there will be a
+   positive one of comparable brightness nearby.
+
+These assumptions are fair for Stokes-I images. A masking function can therefore
+be constructed, where:
+
+{math}`\mathrm{MAC}(x, y) = \mathrm{img} > P \times |\mathrm{RollingMinimum}\left(\mathrm{img}, \mathrm{BoxSize}(\mathrm{img}, x, y)\right)|`
+
+where {math}`\mathrm{RollingMinimum}` is a minimum boxcar filter of dimensions
+return by {math}`\mathrm{BoxSize}`pixels, which could be turned in a position
+dependent way. The absolute value of the {math}`\mathrm{RollingMinimum}`
+function is increased by a padding factor {math}`P` to increase the minimum
+positive threshold. The {math}`\mathrm{MAC}` is a simply and efficient statistic
+to compute.
+
+The choice of an appropriate boxcar size is an important consideration. A larger
+size enforces more conservative behaviour from the {math}`\mathrm{MAC}` process.
+Should too small a region be supplied than typically large multi-scale features
+are less reliably assessed. Extensions can be made to detect when an the rolling
+box filter size is too small (e.g. by an imbalance of positive to negative
+pixels). A basic implementation of this adaptive boxcar size is implemented via
+the `MaskingOptions.flood_fill_use_mbd_adaptive` parameters.
+
+<!-- TODO: Need to include some image here -->
+
+## Reverse flood filling
+
+Cleaning source with features that are both faint and diffuse is difficult. On a
+per-pixel basis it is often a reality that a minimum signal-to-noise threshold
+is not met. Should the cleaning thresholds (set in either absolute
+{math}`\mathrm{Jy}/\mathrm{beam}` units or in terms of {math}`\sigma` units) be
+too high this diffuse emission is never cleaned. In `eye-patch` we include a
+reverse flood fill procedure that grows islands of pixels above an initial
+criteria out to adjacent pixels that met a secondary lower level. This process
+is often the initial step of most source finders.
+
+There are two steps to this process:
+
+1. _Initial siginficant island detection_: The statistic of choice (see above)
+   is executed and all pixels above the threshold are marketed as pixels to
+   clean. We can set this via `MaskingOptions.flood_fill_positive_seed_clip`
+2. _Growing the initial set of islands_; Islands that are identified as
+   significant go through a dilation process, where the dilation process is
+   restricted to limit it only to pixels above the lower level threshold. This
+   lower level clip is set via `MaskingOptions.flood_fill_positive_flood_clip`.
+
+Activating the flood fill procedure is 'opt in' and activated via
+`MaskingOptions.flood_fill`. Further, the {math}`\mathrm{MAC}` statistic is only
+exposed when the flood fill is enabled.
+
+<!-- TODO: Need to include some other image here -->
+
+## Eroding output islands
+
+Output binary clean masks are naturally at the resolution of the input image (at
+least in `eye-patch`). All pixels that reside in an island are candidate pixels
+where cleaning is allowed to occur. Consider an unresolved source that is
+perfectly aligned to the discrete pixel grid. In principal its clean component
+should be contained entirely to a single pixel. However, as the source is
+sufficiently bright the resulting mask is made up of many pixels (i.e. the shape
+the restoring beam). Should deep cleaning be employed it is possible that small
+perturbations from the noise underlying a source would also be cleaned.
+
+A binary erosion process with the erosision structure set to the shape of the
+restoring beam at a particular power level can be used to 'contract' all pixel
+masks. The output should better reflect where clean components ought to be
+placed. See the `MaskingOptions.beam_shape_erode` and
+`MaskingOptions.beam_shape_erode_minimum_response` options to activate and
+control this process. The minimum response should be set between 0 to 1, where
+numbers closer to 0 represent a larger binary erosion structure shape. That is
+to say islands need to be _larger_ for any pixels to remain as
+`MaskingOptions.beam_shape_erode_minimum_response` approaches 0.
+
+### Multi-scale beam erosion
+
+basic routines to enable per-scale beam shape erosion are provided via
+`MaskingOptions.beam_shape_eroison_scales`. For each specified scale the
+restoring beam (the base shape in this erosion) is convolved with a circular
+gaussian of the specified scale (each scale is FWHM in pixels). The resulting
+beam is then evaluated in the basic process outlined above, eroding the clean
+islands at the native resolution to the clean islands at the specified scale.
+The clean mask at each scale is stored as 'bitmapped' value - except since these
+are floats the `n`'th scale is stored as `2**n` for each pixel.
+
+This is intended to provide a mechanism to ensure cleaning at larger scales
+occurs in well defined regions. An example of the erosion process for
+`0 1 2 4 8 16 32 64 128 256 512 1024 2056` is shown below. Point source islands
+are still in the mask, it is just that since they are at the initial scale
+defined, they are stored as `2**0 = 1` values.
+
+```{image} _static/multi_scale_erode.jpg
+:alt: Example of multi-scale beam erode
+:width: 100%
+```
+
+## `--convolve-first` option
+
+Historically for extract galactic fields the reverse flood fill process
+described above using a minimum absolute clip as the threshold statistic
+produced reliable clean masks. A subsequent binary erosion process to attempt to
+characterise per-scale clean masks produced meaningful results. For regions like
+the Galactic Plane, however, the reverse flood fill process would often miss
+diffuse emission that was both extended and below the flood fill clip level.
+Reducing this lower level clip would not consistently capture such faint
+extended structures, and pixels boosted by noise would often leak into the clean
+mask from legitimate islands (flying spaghetti monsters).
+
+The `--convol-first` option activates a routine where the base image is first
+put through an `open` filter before being convolved to some desired scale.
+Significance thresholding operations are then applied to this filtered image.
+Importantly, the `open` filter attempts to isolate small structures from larger
+ones. This is implemented through the combined usage of a minimum filter
+followed by a maximum filter (could be considered a high-pass filter).
+
+```{raw} html
+<video width="100%" controls>
+  <source src="_static/open_filter.mp4" type="video/mp4">
+  Your browser does not support the video tag.
+</video>
+```
+
+Should this option be activated be aware that the seed and flood clipping
+threshold change - it should be possible to use lower limits. For example
+`flood_fill_positive_seed_clip=1.02` and `flood_file_positive_flood_clip=0.15`
+when the minimum absolute clip statistic is used.
+
+## Accessing via the CLI
+
+The masking utility may be accessed via a CLI entrypoint:
+
+```{argparse}
+:ref: eye_patch.masking.get_parser
+:prog: eye_patch_masking
+```
+
+## The `MaskingOptions` class
+
+Embedded below is the `eye-patch` `Options` class used to construct clean masks.
+Input values are validated by `pydantic` to ensure they are appropriately typed.
+
+```{literalinclude} ../eye_patch/masking.py
+:pyobject: MaskingOptions
+```

{eye_patch-1.0.0 → eye_patch-1.0.0a0}/eye_patch/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '1.0.0'
-__version_tuple__ = version_tuple = (1, 0, 0)
+__version__ = version = '1.0.0a0'
+__version_tuple__ = version_tuple = (1, 0, 0, 'a0')
 
 __commit_id__ = commit_id = None

{eye_patch-1.0.0 → eye_patch-1.0.0a0}/pyproject.toml

@@ -61,11 +61,13 @@ dev = [
     "ty>=0.0.13",
 ]
 docs = [
-  "sphinx>=7.0",
+  "sphinx<9",
   "myst_parser>=0.13",
   "sphinx_copybutton",
   "sphinx_autodoc_typehints",
   "furo>=2023.08.17",
+  "sphinx-autoapi>=3.8.0",
+  "sphinx-argparse>=0.5.2",
 ]
 
 
@@ -164,3 +166,6 @@ ignore = [
 
 [tool.ruff.lint.per-file-ignores]
 "tests/**" = ["T20"]
+
+[tool.codespell]
+skip = ["uv.lock"]