Update Docu (#636)

* Scripts fetches and converts ALMA config files into OSKAR files 📟 * Latest configs for ALMA cycles 9, 10, 11 🚑 * Resolved type conflict (was complained about by mypy) 😕 * Updated documentation as suggested in comments to PR #634 ♍ * Adding link to Karabo workshop on Renkulab 📃 * Section 'Show telescope config' belongs to basic examples * Revert "Section 'Show telescope config' belongs to basic examples ". The changes were made in the wrong file. This reverts commit 50e885f. * Moved section up because it's of general interest and not only SRC related. 🍕 * Fixed more formatting issues 📁 * Added module descriptions 👶 * Fixed formatting issues 👅 * Rewritten docu for imaging module 🚻 * Added a link in README and documentation to the Karabo Workshop on Renkulab ⚡ * Added note to limited server resources on Renkulab.
i4Ds · Dec 18, 2024 · 1da8116 · 1da8116
1 parent 30fa377
commit 1da8116
Show file tree

Hide file tree

Showing 21 changed files with 479 additions and 294 deletions.
diff --git a/README.md b/README.md
@@ -28,6 +28,17 @@ for the full installation instructions.
 
 We also offer [Docker](https://i4ds.github.io/Karabo-Pipeline/container.html) images.
 
+
+Quick Look with no Installation
+-------------------------------
+
+If you are curious to see whether Karabo is for you or if you want to try it out before you install something, then this is for you: we offer a demo installation on Renkulab. This demo was created for a workshop at Swiss SKA Days in September 2024. It has been kept up to date ever since.
+
+The demo installation can be found as [SwissSKADays-Karabo-Workshop](https://renkulab.io/projects/menkalinan56/swissskadays-karabo-workshop). You can start a server (free of cost) and start using the Karabo pipeline without an account. However, if you want to save your work, you need to log in using your GitHub account, your ORCID id, or your edu-ID. You then fork the project. Changes you make will be saved to your GitLab repository linked to your Renkulab accout.
+
+A good starting point may be the slide deck of the workshop. You can find it in the folder `documents`. The code in the slides is available as Jupyter notebooks in the folder `notebooks`. Those help you get started.
+
+
 Contribute to Karabo
 ---------------------
 We are very happy to accept contributions, either as code or even just bug reports! When writing code,

diff --git a/doc/src/conf.py b/doc/src/conf.py
@@ -25,7 +25,7 @@
 
 project = "Karabo-Pipeline"
 copyright = "2024, i4ds"
-author = "i4ds, ETH"
+author = "i4ds, ETHZ"
 
 # The full version, including alpha/beta/rc tags
 release = __version__

diff --git a/doc/src/examples/example_structure.md b/doc/src/examples/example_structure.md
@@ -8,6 +8,12 @@ The following example showcases a simple telescope simulation using the main pip
 <example_interfe_simu.py>
 ```
 
+## Show telescope config
+
+```python
+<example_tel_set.py>
+```
+
 ## Imaging
 
 The notebook [imaging.ipynb](https://github.com/i4Ds/Karabo-Pipeline/blob/main/karabo/examples/imaging.ipynb), shows how to use different dirty imaging and image cleaning algorithms.
@@ -44,11 +50,7 @@ See the script [line_emission.py](https://github.com/i4Ds/Karabo-Pipeline/blob/m
 
 This simulation begins with a `SkyModel` instance, and with the definition of the desired `Observation` and `Telescope` details. Then, the `InterferometerSimulation` instance uses the requested backend (OSKAR and RASCIL are currently supported) to compute the corresponding visibilities, and the desired `DirtyImager` instance is used to convert the visibilities into dirty images. Optionally, we can include primary beam effects and correct for such effects in the final dirty images. Finally, we can mosaic different dirty images into one larger image using the `ImageMosaicker` class.
 
-## Show telescope config
 
-```python
-<example_tel_set.py>
-```
 
 ![Image](../images/telescope.png)
 
@@ -60,3 +62,13 @@ The name of the directory is given the name of the telescope followed by configu
 
 More details can be find in the OSKAR documentation and source code: https://ska-telescope.gitlab.io/sim/oskar/telescope_model/telescope_model.html
 
+## Using our Demo Installation
+We offer an always up-to-date demo installation for Karabo on Renkulab. This demo was created for a workshop at Swiss SKA Days in September 2024. It can be found here:
+
+[SwissSKADays-Karabo-Workshop](https://renkulab.io/projects/menkalinan56/swissskadays-karabo-workshop)
+
+You do not need an account to use the demo. Just hit the green 'Start' button in the top right corner. However, if you want to save your work you need to log in using your GitHub account, your ORCID id, or your edu-ID. Then fork the project. Now changes you make will be saved to your GitLab repository linked to your Renkulab accout.
+
+The free server on Renkulab has limited resources. You will not be able to run much larger simulations than those provided in the demo notebooks. 
+
+A good starting point may be the slide deck of the workshop. You can find it in the folder documents. The code in the slides is available as Jupyter notebooks in the folder notebooks. Those help you get started.
diff --git a/doc/src/examples/examples.md b/doc/src/examples/examples.md
@@ -44,6 +44,15 @@ observation = Observation(
 simulation.run_simulation(telescope, sky, observation)
 ```
 
+## Show telescope config
+
+```python
+from karabo.simulation.telescope import Telescope
+
+telescope = Telescope.constructor("EXAMPLE")
+telescope.plot_telescope(file="example_telescope.png")
+```
+
 ## Imaging
 
 The notebook [imaging.ipynb](https://github.com/i4Ds/Karabo-Pipeline/blob/main/karabo/examples/imaging.ipynb), shows how to use different dirty imaging and image cleaning algorithms.
@@ -80,14 +89,7 @@ See the script [line_emission.py](https://github.com/i4Ds/Karabo-Pipeline/blob/m
 
 This simulation begins with a `SkyModel` instance, and with the definition of the desired `Observation` and `Telescope` details. Then, the `InterferometerSimulation` instance uses the requested backend (OSKAR and RASCIL are currently supported) to compute the corresponding visibilities, and the desired `DirtyImager` instance is used to convert the visibilities into dirty images. Optionally, we can include primary beam effects and correct for such effects in the final dirty images. Finally, we can mosaic different dirty images into one larger image using the `ImageMosaicker` class.
 
-## Show telescope config
-
-```python
-from karabo.simulation.telescope import Telescope
 
-telescope = Telescope.constructor("EXAMPLE")
-telescope.plot_telescope(file="example_telescope.png")
-```
 
 ![Image](../images/telescope.png)
 
@@ -99,3 +101,13 @@ The name of the directory is given the name of the telescope followed by configu
 
 More details can be find in the OSKAR documentation and source code: https://ska-telescope.gitlab.io/sim/oskar/telescope_model/telescope_model.html
 
+## Using our Demo Installation
+We offer an always up-to-date demo installation for Karabo on Renkulab. This demo was created for a workshop at Swiss SKA Days in September 2024. It can be found here:
+
+[SwissSKADays-Karabo-Workshop](https://renkulab.io/projects/menkalinan56/swissskadays-karabo-workshop)
+
+You do not need an account to use the demo. Just hit the green 'Start' button in the top right corner. However, if you want to save your work you need to log in using your GitHub account, your ORCID id, or your edu-ID. Then fork the project. Now changes you make will be saved to your GitLab repository linked to your Renkulab accout.
+
+The free server on Renkulab has limited resources. You will not be able to run much larger simulations than those provided in the demo notebooks. 
+
+A good starting point may be the slide deck of the workshop. You can find it in the folder documents. The code in the slides is available as Jupyter notebooks in the folder notebooks. Those help you get started.
diff --git a/doc/src/images/telescope.png b/doc/src/images/telescope.png
diff --git a/doc/src/index.rst b/doc/src/index.rst
@@ -16,8 +16,9 @@ Karabo is a starting point for the `Square Kilometer Array <https://www.skateles
    examples/examples.md
    parallel_processing
 
-Main Modules
-==================
+
+Modules
+===============
 .. toctree::
    :maxdepth: 2
    :caption: Simulation
@@ -26,24 +27,25 @@ Main Modules
 
 .. toctree::
    :maxdepth: 2
-   :caption: Source Detection
+   :caption: Imaging
+
+   main_features/imaging.rst
+   main_features/base_imaging.rst
+   main_features/oskar_imaging.rst
+   main_features/rascil_imaging.rst
 
-   main_features/sourcedetection.rst
-
 
-Modules
-==================
 .. toctree::
-   :maxdepth: 1
-   :caption: Modules
+   :maxdepth: 2
+   :caption: Source Detection
+
+   main_features/sourcedetection.rst
 
-   modules.rst
 
 Development
-==================
+===========
 .. toctree::
    :maxdepth: 2
    :caption: Developers
 
    development.md
-   installation_no_conda
diff --git a/doc/src/main_features/base_imaging.rst b/doc/src/main_features/base_imaging.rst
@@ -0,0 +1,36 @@
+karabo.imaging.imager_base
+==========================
+
+Overview
+------------
+This package defines base classes from which the 
+specialised image classes are derived.
+
+
+Classes
+-------
+
+.. autoclass:: karabo.imaging.imager_base.DirtyImagerConfig
+   :members:
+   :special-members: __init__
+   :exclude-members: 
+
+.. autoclass:: karabo.imaging.imager_base.DirtyImager
+   :members:
+   :special-members: __init__
+   :exclude-members: 
+
+.. autoclass:: karabo.imaging.imager_base.DirtyImagerConfig
+   :members:
+   :special-members: __init__
+   :exclude-members: 
+
+.. autoclass:: karabo.imaging.imager_base.ImageCleanerConfig
+   :members:
+   :special-members: __init__
+   :exclude-members: 
+
+.. autoclass:: karabo.imaging.imager_base.ImageCleaner
+   :members:
+   :special-members: __init__
+   :exclude-members: 
diff --git a/doc/src/main_features/imaging.rst b/doc/src/main_features/imaging.rst
@@ -0,0 +1,22 @@
+karabo.imaging.image
+====================
+
+Overview
+------------
+This package provides the Image base class. It is used in the Karabo 
+package to store and manipulate image data.
+
+
+Classes
+-------
+
+.. autoclass:: karabo.imaging.image.Image
+   :members:
+   :special-members: __init__
+   :exclude-members: _update_header_after_resize
+
+.. autoclass:: karabo.imaging.image.ImageMosaicker
+   :members:
+   :special-members: __init__
+   :exclude-members: _update_header_after_resize
+
diff --git a/doc/src/main_features/oskar_imaging.rst b/doc/src/main_features/oskar_imaging.rst
@@ -0,0 +1,23 @@
+karabo.imaging.imager_oskar
+=================
+
+Overview
+------------
+This package summerizes tools and functions to be used with the imager
+from the OSKAR backend. This backend does not offer functionality to
+calculate a cleaned image. You must use RASCIL or WSClean.
+
+
+Classes
+-------
+
+.. autoclass:: karabo.imaging.imager_oskar.OskarDirtyImagerConfig
+   :members:
+   :special-members: __init__
+   :exclude-members: 
+
+
+.. autoclass:: karabo.imaging.imager_oskar.OskarDirtyImager
+   :members:
+   :special-members: __init__
+   :exclude-members:
diff --git a/doc/src/main_features/rascil_imaging.rst b/doc/src/main_features/rascil_imaging.rst
@@ -0,0 +1,35 @@
+karabo.imaging.imager_rascil
+============================
+
+Overview
+------------
+This package summerizes tools and functions to be used with the imager
+from the RASCIL backend. This backend allows both calculating a dirty
+images and a cleaned image, respoectivley.
+
+
+Classes
+-------
+
+.. autoclass:: karabo.imaging.imager_rascil.RascilDirtyImagerConfig
+   :members:
+   :special-members: __init__
+   :exclude-members:
+
+
+.. autoclass:: karabo.imaging.imager_rascil.RascilDirtyImager
+   :members:
+   :special-members: __init__
+   :exclude-members: _update_header_after_resize
+
+
+.. autoclass:: karabo.imaging.imager_rascil.RascilImageCleanerConfig
+   :members:
+   :special-members: __init__
+   :exclude-members: _update_header_after_resize
+
+
+.. autoclass:: karabo.imaging.imager_rascil.RascilImageCleaner
+   :members:
+   :special-members: __init__
+   :exclude-members: _compute
diff --git a/doc/src/main_features/simulation.rst b/doc/src/main_features/simulation.rst
@@ -1,5 +1,12 @@
 karabo.simulation
-============
+=================
+
+Overview
+------------
+This module contains the functionality required for an interferometer simulation. This includes defining a sky model and selecting a telescope. 
+
+Classes
+-------
 
 .. autoclass:: karabo.simulation.sky_model.SkyModel
    :members:

diff --git a/doc/src/main_features/sourcedetection.rst b/doc/src/main_features/sourcedetection.rst
@@ -1,6 +1,14 @@
 karabo.sourcedetection
 ======================
 
+Overview
+---------
+Karabo comes with a source detection algorithm basesd on `PyBDSF`. 
+This module offers wrappers around `PyBDSF` and allows for automatic 
+source detection.
+
+Classes
+-------
 .. autoclass:: karabo.sourcedetection.evaluation.SourceDetectionEvaluation
    :members:
    :special-members: __init__

diff --git a/karabo/imaging/image.py b/karabo/imaging/image.py
@@ -681,11 +681,12 @@ def get_power_spectrum(
         Calculate the power spectrum of this image.
 
         :param resolution: Resolution in radians needed for conversion from Jy to Kelvin
-        :param signal_channel: channel containing both signal and noise
+        :param signal_channel: channel containing both signal and noise \
         (arr of same shape as nchan of Image), optional
-        :return (profile, theta_axis)
-            profile: Brightness temperature for each angular scale in Kelvin
-            theta_axis: Angular scale data in degrees
+
+        :return (profile, theta_axis):
+            - profile: Brightness temperature for each angular scale in Kelvin
+            - theta_axis: Angular scale data in degrees
         """
         profile, theta = power_spectrum(self.path, resolution, signal_channel)
         return profile, theta
@@ -701,7 +702,7 @@ def plot_power_spectrum(
         Plot the power spectrum of this image.
 
         :param resolution: Resolution in radians needed for conversion from Jy to Kelvin
-        :param signal_channel: channel containing both signal and noise
+        :param signal_channel: channel containing both signal and noise \
         (arr of same shape as nchan of Image), optional
         :param save_png: True if result should be saved, default = False
         :param block: Whether plotting should block the remaining of the script

diff --git a/karabo/imaging/imager_base.py b/karabo/imaging/imager_base.py
@@ -105,7 +105,7 @@ def create_cleaned_image(
     ) -> Image:
         """Creates a clean image from a dirty image or from visibilities.
 
-        Args:
+        Arguments:
             visibility: Visibility from which a clean image should be created.
             dirty_fits_path: Path to dirty image FITS file that
                 should be reused to create a clean image. If None, dirty image will be