Merge branch 'main' of github.com:SOFIA-USRA/grig

CHANGES.rst

@@ -1,4 +1,3 @@
-1.0.0
-=====
-
+1.0.0  (2023-08-13)
+===================
 - Initial release.

codemeta.json

@@ -4,7 +4,7 @@
         "http://schema.org"
     ],
     "@type": "SoftwareSourceCode",
-    "identifier": "TBD",
+    "identifier": "https://doi.org/10.5281/zenodo.8176181",
     "name": "grig",
     "description": "N-Dimensional Resampler for Irregularly Gridded Data",
     "license": "BSD 3-Clause",

docs/grig/index.rst

@@ -3,7 +3,49 @@ Grig Documentation
 ******************
 
 Grig is a fully N-dimensional resampling package for irregularly
-gridded data with associated errors.
+gridded data with associated errors. It was primarily developed for
+generating astronomical image mosaics and spectral image cubes, but has broad
+applicability to scientific data arrays with or without associated errors.
+
+Given a cloud of irregularly spaced data points, the resampling algorithm
+assigns values to voxels of a regular grid by fitting data points in a local cloud
+with a low-order polynomial function, by default. See the figure below for an
+illustration.
+
+The resampling algorithm has a wide set of parameters to allow customization to
+particular use cases:
+
+    - Splines can be used in place of polynomial fits for the local interpolation.
+    - The convolution kernel may be regular or irregular.
+    - The kernel size and shape may be fixed or may adapt to the data.
+
+See the :ref:`example section <resample_examples>` for more possible applications, or the
+`white paper <https://raw.githubusercontent.com/SOFIA-USRA/grig/main/docs/grig/resampling/paper/Perera.pdf>`__
+included with the source distribution for a complete technical description.
+
+.. figure:: resampling/images/resample_algorithm.png
+   :alt: Left: Observations: Cloud of irregular data points with spatial (x,y) and
+         spectral (lambda) coordinates. The image shows many irregularly spaced points.
+         Middle: 1. Model observations as F = f(x, y, lambda) + epsilon where F = flux,
+         epsilon = error, and f is a polynomial function. 2. For voxel (i, j, k), derive
+         the local function f by fitting to a localized cloud of samples in the region
+         of (x-i, y-j, lambda-k).  3. Set F-i-j-k = f(x-i, y-i, lambda-k) where F-i-j-k
+         is the flux at voxel (i, j, k).  The image shows a three dimensional grid containing
+         a sphere, representing the local datacloud. The sphere contains a small red cube,
+         representing a single output voxel.
+         Right: Data Cube: Regularly spaced array of voxels where each voxel element
+         is at coordinate (x-i, y-j, lambda-k) and i, j, k respectively mark indices
+         along dimensions x, y, lambda of the cube.  The image shows a regular cube with
+         edges labeled x, y, and lambda, containing a small red cube representing the
+         voxel from the middle image.
+   :name: resample_algorithm
+
+   Resampling algorithm application to a spectral cube with two spatial dimensions and
+   one spectral.  The algorithm assigns values to voxels of a regular grid by fitting data
+   points in a local cloud with a low-order polynomial function.  Data points in the local
+   cloud are weighted by distance from the output point and by their associated error
+   estimates.
+
 
 Getting Started
 ===============

docs/install.rst

@@ -53,11 +53,7 @@ Remove the environment if necessary::
 Via Pip
 ^^^^^^^
 
-Alternately, prerequisites for the package can be installed with::
-
-  pip install -r requirements.txt
-
-and the package can then be installed as usual::
+Alternately, prerequisites for the package can be installed along with the source code::
 
    pip install -e .
 
@@ -84,6 +80,6 @@ directory::
 
    conda create --name grig python=3.11
    pip install -r freeze_requirements.txt
-   pip install -e .
+   pip install -e . --no-deps
 
 

freeze_requirements.txt

@@ -1,8 +1,10 @@
 bottleneck==1.3.7
 cloudpickle==2.2.1
-joblib==1.3.0
+joblib==1.3.2
+llvmlite==0.40.1
 numba==0.57.1
 numpy==1.24.4
 psutil==5.9.5
 scikit-learn==1.3.0
 scipy==1.11.1
+threadpoolctl==3.2.0