spectrum normalization switched back on; docs updates (#227)

Author: pmelchior

docs/0-quickstart.ipynb

@@ -19,7 +19,7 @@
     "import jax.numpy as jnp\n",
     "import matplotlib.pyplot as plt\n",
     "\n",
-    "from scarlet2 import *"
+    "import scarlet2 as sc2"
    ]
   },
   {
@@ -71,14 +71,11 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Define Observation and Frame\n",
+    "## Define the Observation\n",
     "\n",
-    "An {py:class}`~scarlet2.Observation` combines several data elements with a {py:class}`~scarlet2.Frame`, similar to header-data arrangement in FITS files. In addition to the actual science image cube, you can and often must provide weights for all elements in the data cube, an image cube of the PSF model (one image for all or one for each channel), an {py:class}`astropy.wcs.WCS` structure to translate from pixel to sky coordinates, and labels for all channels.\n",
+    "An {py:class}`~scarlet2.Observation` stored several data arrays. In addition to the actual science image cube, you can and often must provide weights for all elements in the data cube, an image cube of the PSF model (one image for all or one for each channel), an {py:class}`astropy.wcs.WCS` structure to translate from pixel to sky coordinates, and labels for all channels.\n",
     "\n",
-    "The {py:class}`~scarlet2.Frame` is a description of the hyperspectral cube of the observations. Think of it as the metadata, what aspects of the sky are described here. At the least, a {py:class}`~scarlet2.Frame` holds the `shape` of the cube, for which we use the convention `(C, H, W)` for the number of elements in 3 dimensions: `C` for the number of bands/channels and `H/W` for the height and width of the images.\n",
-    "\n",
-    "\n",
-    "\n"
+    "The observation stores any needed meta-data in {py:class}`~scarlet2.Frame` (similar to the header in a FITS file). At the least, a {py:class}`~scarlet2.Frame` holds the `shape` of the cube, for which we use the convention `(C, H, W)` for the number of elements in 3 dimensions: `C` for the number of bands/channels and `H/W` for the height and width of the images."
    ]
   },
   {
@@ -87,55 +84,64 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "obs = Observation(\n",
+    "obs = sc2.Observation(\n",
     "    data,\n",
     "    weights,\n",
-    "    psf=ArrayPSF(psf),\n",
+    "    psf=sc2.ArrayPSF(psf),\n",
     "    channels=channels,\n",
-    ")\n",
-    "model_frame = Frame.from_observations(obs)"
+    ")"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "_scarlet2_ will construct another {py:class}`~scarlet2.Frame` for the _model_ of the sky you seek to fit. It differs from the observation frame because the model needs to be superior in terms of spatial resolution, PSF blurring, spectral coverage, or all of the above, so that the observation can be computed from the model by a degradation operation, the so-called \"forward operator. In _scarlet2_, {py:class}`~scarlet2.renderer.Renderer` implements this operation and contains, e.g., PSF difference kernels and resampling transformations.\n",
-    "\n",
-    "In this example, we assume that bands and pixel locations are identical between the model and the observation. Because we have ground-based images, the degradation comes from the PSF. With different PSFs in each band, we need to define a reference PSF that is sufficiently narrow. Our default is minimal Gaussian PSF that is barely well-sampled (standard deviation of 0.7 pixels) as our reference kernel:\n",
-    "\n",
-    "Note also the validation results that are automatically generated.\n",
-    "These are executed automatically on behalf of the user and act as guardrails.\n",
-    "Here we can see that check number ``007`` produced a error and prints a message indicating that the PSF is not the same for all channels.\n",
-    "While validation errors will not cause the code to stop running, they do indicate a likely problem that warrants attention.\n",
-    "Automatic validation is performed at several times in ``scarlet2``, which can be seen later in this notebook.\n",
+    "Note the validation results, which are automatically generated (unless switched off) and act as early warning signs.\n",
+    "We'll see more of these validation tests later in this notebook.\n",
+    "Here the check number ``007`` indicates that the PSF is not centered at the same position for all channels.\n",
+    "The offsets are minor, so we'll proceed, but we're going to come back to this issue at the end.\n",
     "For additional information about automatic validation, please see the [\"Validation\" section](3-validation) of the documentation."
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Display the Image Cube\n",
+    "\n",
+    "We can now make use of the plotting function {py:func}`scarlet2.plot.observation` to create a RGB image of our data.\n",
+    "We're going to use the {py:class}`~scarlet2.plot.AsinhAutomaticNorm`, which scales the observed data by a {math}`\\mathrm{sinh}^{-1}` function that is automatically tuned to reveal both the noise level and the highlights, to create a color-consistent RGB image."
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,
    "metadata": {},
    "outputs": [],
    "source": [
-    "print(model_frame)"
+    "norm = sc2.plot.AsinhAutomaticNorm(obs)\n",
+    "sc2.plot.observation(obs, norm=norm, sky_coords=centers, show_psf=True, add_labels=True)\n",
+    "plt.show()"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "If other properties of the model are desired, they can be provided to {py:func}`scarlet2.Frame.from_observations`."
+    "Since we did't provide a `wcs` for this {py:class}`~scarlet2.Observation`, all spatial coordinates (like `centers` above) are in image pixels. Otherwise RA/Dec coordinates (as `astropy.SkyCoord`) are required."
    ]
   },
   {
    "cell_type": "markdown",
-   "metadata": {},
+   "metadata": {
+    "ExecuteTime": {
+     "end_time": "2025-10-10T03:47:09.322341Z",
+     "start_time": "2025-10-10T03:47:09.307669Z"
+    }
+   },
    "source": [
-    "## Display Image Cube\n",
-    "\n",
-    "We can now make use of the plotting function {py:func}`scarlet2.plot.observation` to create a RGB image of our data.\n",
-    "We're going to use the {py:class}`~scarlet2.plot.AsinhAutomaticNorm`, which scales the observed data by a {math}`\\mathrm{sinh}^{-1}` function that is automatically tuned to reveal both the noise level and the highlights, to create a color-consistent RGB image."
+    "## Define the Model Frame\n",
+    "_scarlet2_ needs another {py:class}`~scarlet2.Frame`, which describes the properties of the _model_ of the sky you seek to fit. Given one or several observations, _scarlet2_ can make an educated guess what model frame would be best:"
    ]
   },
   {
@@ -144,16 +150,34 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "norm = plot.AsinhAutomaticNorm(obs)\n",
-    "plot.observation(obs, norm=norm, sky_coords=centers, show_psf=True, add_labels=True)\n",
-    "plt.show()"
+    "model_frame = sc2.Frame.from_observations(obs)\n",
+    "print(model_frame)"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Since we use no `wcs` in this {py:class}`~scarlet2.Observation`, all coordinates are already in image pixels, otherwise RA/Dec pairs are expected as `astropy` sky coordinates."
+    "If only one observation is given (as above), we assume that bands and pixel locations are identical between the model and the observation. Because we have ground-based images, we need to account for different PSFs in each band, which means the model frame needs to define a reference PSF that is sufficiently narrow. Our default is a minimal Gaussian PSF that is barely well-sampled (standard deviation of 0.7 pixels) as the PSF reference.\n",
+    "If other properties of the model frame are desired, they can be provided to {py:func}`scarlet2.Frame.from_observations`.\n",
+    "\n",
+    "But what's the point of the model frame? Why is it needed at all?\n",
+    "\n",
+    "```{info}\n",
+    "\n",
+    "To fit multiple images with different PSF, different bands, different resolutions, etc..., we must define a model that is superior in all of these aspects, so that each observation can be computed from the model by a degradation operation, the so-called \"forward operator\". The point of joint modeling is to find one superior model of the sky that is consistent with all observations.\n",
+    "```\n",
+    "\n",
+    "In _scarlet2_, the forward operators are implemented as {py:class}`~scarlet2.renderer.Renderer`, which contains, e.g., PSF difference kernels and resampling transformations. It was created earlier by {py:func}`~scarlet2.Frame.from_observation`."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "obs.renderer"
    ]
   },
   {
@@ -173,15 +197,15 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "with Scene(model_frame) as scene:\n",
+    "with sc2.Scene(model_frame) as scene:\n",
     "    for center in centers:\n",
     "        try:\n",
-    "            spectrum, morph = init.from_gaussian_moments(obs, center, min_corr=0.99)\n",
+    "            spectrum, morph = sc2.init.from_gaussian_moments(obs, center, min_corr=0.99)\n",
     "        except ValueError:\n",
-    "            spectrum = init.pixel_spectrum(obs, center)\n",
-    "            morph = init.compact_morphology()\n",
+    "            spectrum = sc2.init.pixel_spectrum(obs, center)\n",
+    "            morph = sc2.init.compact_morphology()\n",
     "\n",
-    "        Source(center, spectrum, morph)"
+    "        sc2.Source(center, spectrum, morph)"
    ]
   },
   {
@@ -197,19 +221,19 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "with Scene(model_frame) as scene:\n",
+    "with sc2.Scene(model_frame) as scene:\n",
     "    for i, center in enumerate(centers):\n",
     "        if i == 0:  # we know source 0 is a star\n",
-    "            spectrum = init.pixel_spectrum(obs, center, correct_psf=True)\n",
-    "            PointSource(center, spectrum)\n",
+    "            spectrum = sc2.init.pixel_spectrum(obs, center, correct_psf=True)\n",
+    "            sc2.PointSource(center, spectrum)\n",
     "        else:\n",
     "            try:\n",
-    "                spectrum, morph = init.from_gaussian_moments(obs, center, min_corr=0.99)\n",
+    "                spectrum, morph = sc2.init.from_gaussian_moments(obs, center, min_corr=0.99)\n",
     "            except ValueError:\n",
-    "                spectrum = init.pixel_spectrum(obs, center)\n",
-    "                morph = init.compact_morphology()\n",
+    "                spectrum = sc2.init.pixel_spectrum(obs, center)\n",
+    "                morph = sc2.init.compact_morphology()\n",
     "\n",
-    "            Source(center, spectrum, morph)"
+    "            sc2.Source(center, spectrum, morph)"
    ]
   },
   {
@@ -299,21 +323,21 @@
     "\n",
     "# best step size for parameters with a relative \"uncertainty\":\n",
     "# big/bright sources adjust more quickly\n",
-    "spec_step = partial(relative_step, factor=0.05)\n",
-    "morph_step = partial(relative_step, factor=1e-3)\n",
+    "spec_step = partial(sc2.relative_step, factor=0.05)\n",
+    "morph_step = partial(sc2.relative_step, factor=1e-3)\n",
     "\n",
-    "with Parameters(scene) as parameters:\n",
+    "with sc2.Parameters(scene) as parameters:\n",
     "    for i in range(len(scene.sources)):\n",
-    "        Parameter(\n",
+    "        sc2.Parameter(\n",
     "            scene.sources[i].spectrum,\n",
     "            name=f\"spectrum:{i}\",\n",
     "            constraint=constraints.positive,\n",
     "            stepsize=spec_step,\n",
     "        )\n",
     "        if i == 0:\n",
-    "            Parameter(scene.sources[i].center, name=f\"center:{i}\", stepsize=0.1)\n",
+    "            sc2.Parameter(scene.sources[i].center, name=f\"center:{i}\", stepsize=0.1)\n",
     "        else:\n",
-    "            Parameter(\n",
+    "            sc2.Parameter(\n",
     "                scene.sources[i].morphology,\n",
     "                name=f\"morph:{i}\",\n",
     "                constraint=constraints.unit_interval,\n",
@@ -380,7 +404,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "plot.scene(\n",
+    "sc2.plot.scene(\n",
     "    scene_,\n",
     "    obs,\n",
     "    norm=norm,\n",
@@ -440,9 +464,9 @@
     "matplotlib.rc(\"image\", interpolation=\"none\", origin=\"lower\")\n",
     "\n",
     "fig, axes = plt.subplots(1, 3, figsize=(10, 4))\n",
-    "axes[0].imshow(plot.img_to_rgb(source_array, norm=norm))\n",
-    "axes[1].imshow(plot.img_to_rgb(source_in_scene_array, norm=norm))\n",
-    "axes[2].imshow(plot.img_to_rgb(source_as_seen, norm=norm))\n",
+    "axes[0].imshow(sc2.plot.img_to_rgb(source_array, norm=norm))\n",
+    "axes[1].imshow(sc2.plot.img_to_rgb(source_in_scene_array, norm=norm))\n",
+    "axes[2].imshow(sc2.plot.img_to_rgb(source_as_seen, norm=norm))\n",
     "plt.show()"
    ]
   },
@@ -464,15 +488,15 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "plot.sources(\n",
+    "sc2.plot.sources(\n",
     "    scene_,\n",
     "    norm=norm,\n",
     "    observation=obs,\n",
     "    show_model=True,\n",
     "    show_rendered=True,\n",
     "    show_observed=True,\n",
     "    show_spectrum=True,\n",
-    "    add_markers=False,\n",
+    "    add_labels=False,\n",
     "    add_boxes=True,\n",
     ")\n",
     "plt.show()"
@@ -501,7 +525,7 @@
    "source": [
     "print(\"----------------- {}\".format(channels))\n",
     "for k, src in enumerate(scene_.sources):\n",
-    "    print(\"Source {}, Fluxes: {}\".format(k, measure.flux(src)))"
+    "    print(\"Source {}, Fluxes: {}\".format(k, sc2.measure.flux(src)))"
    ]
   },
   {
@@ -517,7 +541,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "g = measure.Moments(scene_.sources[1])\n",
+    "g = sc2.measure.Moments(scene_.sources[1])\n",
     "print(\"Source 1 ellipticity:\", g.ellipticity)"
    ]
   },
@@ -548,11 +572,11 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "import scarlet2.io\n",
+    "import scarlet2.io as io\n",
     "\n",
     "id = 35\n",
     "filename = \"hsc_cosmos.h5\"\n",
-    "scarlet2.io.model_to_h5(scene_, filename, id=id, overwrite=True)"
+    "io.model_to_h5(scene_, filename, id=id, overwrite=True)"
    ]
   },
   {
@@ -568,8 +592,8 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "scene__ = scarlet2.io.model_from_h5(filename, id=id)\n",
-    "plot.scene(scene__, observation=obs, norm=norm, add_boxes=True)\n",
+    "scene__ = io.model_from_h5(filename, id=id)\n",
+    "sc2.plot.scene(scene__, observation=obs, norm=norm, add_boxes=True)\n",
     "plt.show()"
    ]
   },
@@ -592,23 +616,23 @@
     "    yx = [(14.0, 44.0), (42.0, 9.0)]\n",
     "    for center in yx:\n",
     "        center = jnp.array(center)\n",
-    "        spectrum = init.pixel_spectrum(obs, center)\n",
-    "        morph = init.compact_morphology()\n",
-    "        Source(center, spectrum, morph)\n",
+    "        spectrum = sc2.init.pixel_spectrum(obs, center)\n",
+    "        morph = sc2.init.compact_morphology()\n",
+    "        sc2.Source(center, spectrum, morph)\n",
     "\n",
     "# need to remake the parameter structure because we have more free parameters now\n",
-    "with Parameters(scene__) as parameters__:\n",
+    "with sc2.Parameters(scene__) as parameters__:\n",
     "    for i in range(len(scene__.sources)):\n",
-    "        Parameter(\n",
+    "        sc2.Parameter(\n",
     "            scene__.sources[i].spectrum,\n",
     "            name=f\"spectrum:{i}\",\n",
     "            constraint=constraints.positive,\n",
     "            stepsize=spec_step,\n",
     "        )\n",
     "        if i == 0:\n",
-    "            Parameter(scene__.sources[i].center, name=f\"center:{i}\", stepsize=0.1)\n",
+    "            sc2.Parameter(scene__.sources[i].center, name=f\"center:{i}\", stepsize=0.1)\n",
     "        else:\n",
-    "            Parameter(\n",
+    "            sc2.Parameter(\n",
     "                scene__.sources[i].morphology,\n",
     "                name=f\"morph:{i}\",\n",
     "                constraint=constraints.unit_interval,\n",
@@ -632,7 +656,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "plot.scene(\n",
+    "sc2.plot.scene(\n",
     "    scene___,\n",
     "    obs,\n",
     "    norm=norm,\n",

docs/howto/multiresolution.ipynb

@@ -155,6 +155,16 @@
     ")"
    ]
   },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "b6a9d6d9e07722cd",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "model_frame"
+   ]
+  },
   {
    "cell_type": "markdown",
    "id": "abb5bbf9-0eb7-4c37-bb55-43904ec6af48",
@@ -236,6 +246,16 @@
     ");"
    ]
   },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "5af1c3e91450403a",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "obs_hsc.renderer"
+   ]
+  },
   {
    "cell_type": "markdown",
    "id": "5765f3385e73e562",