viscube 0.3.0__tar.gz → 0.4.2__tar.gz

{viscube-0.3.0/viscube.egg-info → viscube-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: viscube
-Version: 0.3.0
+Version: 0.4.2
 Summary: Visibility-space gridder for image cubes
 Home-page: 
 Author: Michael James Yantovski Barth

viscube-0.4.2/docs/source/api.rst

@@ -0,0 +1,43 @@
+VisCube API
+===========
+
+The complete VisCube application programming interface, organized by
+module. Everything documented here (except the low-level gridding engines
+and window functions) is also re-exported at the package top level, so
+``from viscube import grid_cube_all_stats_nonoverlap`` and
+``viscube.grid_cube.grid_cube_all_stats_nonoverlap`` are equivalent.
+
+High-level gridding: ``viscube.grid_cube``
+------------------------------------------
+
+.. automodule:: viscube.grid_cube
+    :members:
+    :member-order: bysource
+
+Low-level gridding engines: ``viscube.gridder``
+-----------------------------------------------
+
+.. automodule:: viscube.gridder
+    :members:
+    :member-order: bysource
+
+Gridding kernels: ``viscube.windows``
+-------------------------------------
+
+.. automodule:: viscube.windows
+    :members:
+    :member-order: bysource
+
+Noise estimation: ``viscube.sigma_per_baseline``
+------------------------------------------------
+
+.. automodule:: viscube.sigma_per_baseline
+    :members:
+    :member-order: bysource
+
+Image-plane tapers: ``viscube.deapodization``
+---------------------------------------------
+
+.. automodule:: viscube.deapodization
+    :members:
+    :member-order: bysource

{viscube-0.3.0 → viscube-0.4.2}/docs/source/intro.md

@@ -13,6 +13,7 @@ To learn how to use VisCube, I suggest following the documentation in the follow
 1. Run the ["Beginner's Guide"](https://viscube.readthedocs.io/en/latest/notebooks/example_basic.html) on your local machine to get acquainted with VisCube's functionality and make sure your installation is functional
 2. Read through the ["How-to Guide: Extracting data from Measurement Sets"](https://viscube.readthedocs.io/en/latest/extracting_ms_to_py.html) to learn how to prepare your own measurement sets for VisCube
 3. Once you have learnt one of the methods taught in the "extraction How-to Guides", you can run the code from the Beginner's guide on your own data (with modifications as needed). 
+4. For the full list of functions and their parameters (gridding variants, kernels, noise estimation, image-plane tapers), consult the [API reference](https://viscube.readthedocs.io/en/latest/api.html).
 
 This project is a spinoff of a continuum-only gridder I worked on with Noé Dia and Alexandre Adam; that gridder has been released as part of the [IRIS interferometric imaging pipeline.](https://github.com/enceladecandy/iris)
 

{viscube-0.3.0 → viscube-0.4.2}/docs/source/notebooks/casa_io_basic.ipynb

@@ -224,7 +224,7 @@
    "id": "bc68bc83-c0cf-4914-bfda-73cdf45c21d5",
    "metadata": {},
    "source": [
-    "**Helpful tip: If you find that your kernel is dying during the above cell due to memory limitations, it may be helpful to iterate through the measurement set using `ms.selectchannel(nchan=nch, start=ch0, width=1, inc=1)` and a for loop over `nch`**. For a tutorial on how to do that, visit [this page]()"
+    "**Helpful tip: If you find that your kernel is dying during the above cell due to memory limitations, it may be helpful to iterate through the measurement set using `ms.selectchannel(nchan=nch, start=ch0, width=1, inc=1)` and a for loop over `nch`**. For a tutorial on how to do that, visit [this page](https://viscube.readthedocs.io/en/latest/notebooks/casa_io_large_ms_bychan.html)"
    ]
   },
   {

{viscube-0.3.0 → viscube-0.4.2}/docs/source/notebooks/casa_io_large_ms_bychan.ipynb

@@ -365,6 +365,16 @@
     "print(\"  weight:\", weight_all.shape, weight_all.dtype)"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "be21175e",
+   "metadata": {},
+   "source": [
+    "### Next step: per-visibility uncertainties\n",
+    "\n",
+    "The file saved above contains no `sigma_re`/`sigma_im` arrays, but VisCube's gridding functions require per-visibility inverse variances (`invvar_group_re`/`invvar_group_im`) for their hybrid uncertainty estimation. To compute them, also extract the `TIME` and `SCAN_NUMBER` columns (add them to the static per-row read above — they are per-row, so they fit in memory even for large measurement sets) and run `viscube.sigma_by_baseline_scan_time_diff` on the extracted cube, exactly as in Step 9 of the [intro CASA tutorial](https://viscube.readthedocs.io/en/latest/notebooks/casa_io_basic.html)."
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,

{viscube-0.3.0 → viscube-0.4.2}/docs/source/notebooks/combining_low_high_res_casa.ipynb

@@ -899,22 +899,36 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 22,
+   "execution_count": null,
    "id": "c7eccc3d-a81d-4600-9df8-aa36bc7a48e8",
    "metadata": {},
    "outputs": [],
    "source": [
-    "frequencies, u0, v0, vis0, weight0 = load_and_mask(freq, u_raw, v_raw, vis_raw, weight_raw, mask)"
+    "# Approximate per-visibility noise from the MS weights (weight = 1/sigma^2).\n",
+    "# For a data-driven, publication-grade estimate, extract TIME/SCAN_NUMBER as\n",
+    "# well and use viscube.sigma_by_baseline_scan_time_diff instead (see Step 9 of\n",
+    "# the intro CASA tutorial).\n",
+    "sigma_est = 1.0 / np.sqrt(np.maximum(weight_raw, 1e-30))\n",
+    "\n",
+    "frequencies, u0, v0, vis0, weight0, sigma_re0, sigma_im0 = load_and_mask(\n",
+    "    freq, u_raw, v_raw, vis_raw, weight_raw, sigma_est, sigma_est, mask\n",
+    ")"
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": 23,
+   "execution_count": null,
    "id": "0f96f8ce-6965-4a70-8b27-9633f36f0be4",
    "metadata": {},
    "outputs": [],
    "source": [
-    "uu, vv, vis_re, vis_imag, wt = hermitian_augment(u0, v0, vis0, weight0)"
+    "uu, vv, vis_re, vis_imag, wt, sigma_re_aug, sigma_im_aug = hermitian_augment(\n",
+    "    u0, v0, vis0, weight0, sigma_re0, sigma_im0\n",
+    ")\n",
+    "\n",
+    "# Inverse variances for the low-info std fallback\n",
+    "invvar_group_re = 1.0 / np.maximum(sigma_re_aug, 1e-12)**2\n",
+    "invvar_group_im = 1.0 / np.maximum(sigma_im_aug, 1e-12)**2"
    ]
   },
   {
@@ -973,23 +987,17 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 27,
+   "execution_count": null,
    "id": "d39887e5-da1b-40d7-b545-61ba5421ba01",
    "metadata": {},
-   "outputs": [
-    {
-     "name": "stderr",
-     "output_type": "stream",
-     "text": [
-      "100%|████████████| 80/80 [12:53<00:00,  9.66s/channel, coarse_std_im=74, coarse_std_re=74]\n"
-     ]
-    }
-   ],
+   "outputs": [],
    "source": [
     "mean_re, mean_im, std_re, std_im, counts, u_edges, v_edges = grid_cube_all_stats(\n",
     "    frequencies=freq, uu=uu, vv=vv, vis_re=vis_re, vis_imag=vis_imag, weight=wt,\n",
-    "    npix = npix, window_name=\"kaiser_bessel\",\n",
-    "    window_kwargs={\"m\": 6}  # only KB will use beta; m/normalize optional\n",
+    "    invvar_group_re=invvar_group_re,\n",
+    "    invvar_group_im=invvar_group_im,\n",
+    "    npix=npix, window_name=\"kaiser_bessel\",\n",
+    "    window_kwargs={\"m\": 6},\n",
     ")"
    ]
   },

{viscube-0.3.0 → viscube-0.4.2}/docs/source/notebooks/example_basic.ipynb

@@ -25,7 +25,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 12,
+   "execution_count": 2,
    "id": "f71e6ac3-4a0e-4d6e-82b0-3a30192d35ea",
    "metadata": {},
    "outputs": [],
@@ -53,7 +53,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 13,
+   "execution_count": 3,
    "id": "3691fd24-4111-41f9-bf53-7af8b271caaf",
    "metadata": {},
    "outputs": [],
@@ -80,7 +80,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 14,
+   "execution_count": 5,
    "id": "48998306-1637-493a-8d75-296036baae84",
    "metadata": {},
    "outputs": [],
@@ -103,7 +103,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 15,
+   "execution_count": 6,
    "id": "470ae46e-bc02-4f55-9463-2e64be61d97f",
    "metadata": {},
    "outputs": [],
@@ -135,12 +135,14 @@
     "\n",
     "`counts`: number of visibilities in each grid cell (can be useful for creating a mask also)\n",
     "\n",
-    "`u_edges, v_edges`: the edges of the grid in U,V coordinates"
+    "`u_edges, v_edges`: the edges of the grid in U,V coordinates\n",
+    "\n",
+    "VisCube also provides `grid_cube_all_stats_nonoverlap`, a much faster drop-in alternative in which each visibility lands in exactly one uv cell — see the optional alternative step below. For the full list of gridding options and their parameters, see the [API reference](https://viscube.readthedocs.io/en/latest/api.html)."
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": 16,
+   "execution_count": 7,
    "id": "69430ae6-82f9-4286-929c-bc6de1c133ec",
    "metadata": {},
    "outputs": [],
@@ -153,7 +155,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 17,
+   "execution_count": 8,
    "id": "cd89f0e2-e3bb-4050-bab6-08b148ee20a7",
    "metadata": {},
    "outputs": [
@@ -161,7 +163,7 @@
      "name": "stderr",
      "output_type": "stream",
      "text": [
-      "100%|█| 80/80 [03:45<00:00,  2.82s/channel, fallback_pix_im=744, fallback_pix_re\n"
+      "100%|███████████| 80/80 [02:55<00:00,  2.19s/channel, fallback_pix_im=808, fallback_pix_re=808]\n"
      ]
     }
    ],
@@ -184,6 +186,48 @@
     ")"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "7b6da4a7",
+   "metadata": {},
+   "source": [
+    "### Step 3 (alternative): Fast non-overlapping gridding\n",
+    "\n",
+    "`grid_cube_all_stats_nonoverlap` returns the exact same output tuple as `grid_cube_all_stats`, but each visibility contributes to exactly ONE uv cell (with a within-bin Kaiser–Bessel weighting), which makes it much faster than the kernel-overlap path above. Two things to know:\n",
+    "\n",
+    "1. Because our inputs are hermitian-augmented, we pass `n_aug` (the number of *original*, pre-augmentation visibilities per channel) so that conjugate copies landing in the DC cell are dropped.\n",
+    "2. If you forward-model these gridded visibilities (FFT a model image and compare), multiply your model image by the matching analytic taper from `viscube.make_kb_taper_map` (same `m` and `beta`) before the FFT.\n",
+    "\n",
+    "It also warns loudly if any visibility falls outside the uv grid (such visibilities are dropped)."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "a21e909e",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from viscube import grid_cube_all_stats_nonoverlap\n",
+    "\n",
+    "mean_re_no, mean_im_no, std_re_no, std_im_no, counts_no, u_edges_no, v_edges_no = \\\n",
+    "    grid_cube_all_stats_nonoverlap(\n",
+    "        frequencies=freq,\n",
+    "        uu=uu,\n",
+    "        vv=vv,\n",
+    "        vis_re=vis_re,\n",
+    "        vis_imag=vis_imag,\n",
+    "        weight=wt,\n",
+    "        invvar_group_re=invvar_group_re,\n",
+    "        invvar_group_im=invvar_group_im,\n",
+    "        npix=501,\n",
+    "        m=1,      # kernel support = one uv cell\n",
+    "        beta=2.0, # beta=0 would be a plain pillbox\n",
+    "        std_min_effective=std_min_effective,\n",
+    "        n_aug=u0.shape[1],  # pre-augmentation visibility count per channel\n",
+    "    )"
+   ]
+  },
   {
    "cell_type": "markdown",
    "id": "33e43b9b-bfd8-4b12-bc90-18678eaddc56",
@@ -196,7 +240,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 19,
+   "execution_count": 9,
    "id": "ccc6f374-bc87-457e-b048-6b7fa873bfe3",
    "metadata": {},
    "outputs": [],
@@ -222,7 +266,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 20,
+   "execution_count": 10,
    "id": "b9bff9b6-86b5-4735-ae8b-b7211a548f65",
    "metadata": {},
    "outputs": [