From 1f8456f8716309d8a578434171fbf9f319fa037d Mon Sep 17 00:00:00 2001 From: Michel Pluess Date: Tue, 1 Oct 2024 10:31:34 +0200 Subject: [PATCH] Docstrings :crocodile: --- karabo/imaging/imager_rascil.py | 21 ++++---- karabo/imaging/imager_wsclean.py | 9 ++-- karabo/simulation/interferometer.py | 50 ++++++++------------ karabo/simulation/sample_simulation.py | 16 +++---- karabo/simulation/visibility.py | 16 +++++++ karabo/test/test_sim_format_imager_combos.py | 1 - 6 files changed, 57 insertions(+), 56 deletions(-) diff --git a/karabo/imaging/imager_rascil.py b/karabo/imaging/imager_rascil.py index c061fb7b..967d27d1 100644 --- a/karabo/imaging/imager_rascil.py +++ b/karabo/imaging/imager_rascil.py @@ -320,23 +320,20 @@ def create_cleaned_image_variants( """Creates a clean image from visibilities. Args: - visibility (Visibility): Visibility from which a clean image should be - created. Please note: only MS visibilities supported. - deconvolved_fits_path (Optional[FilePathType], optional): Path to write the - deconvolved image to. Example: /tmp/deconvolved.fits. + visibility: Visibility from which a clean image should be created. + Please note: only MS visibilities supported. + deconvolved_fits_path: Path to write the deconvolved image to. + Example: /tmp/deconvolved.fits. If None, will be set to a temporary directory and a default file name. - Defaults to None. - restored_fits_path (Optional[FilePathType], optional): Path to write the - restored image to. Example: /tmp/restored.fits. + restored_fits_path: Path to write the restored image to. + Example: /tmp/restored.fits. If None, will be set to a temporary directory and a default file name. - Defaults to None. - residual_fits_path (Optional[FilePathType], optional): Path to write the - residual image to. Example: /tmp/residual.fits. + residual_fits_path: Path to write the residual image to. + Example: /tmp/residual.fits. If None, will be set to a temporary directory and a default file name. - Defaults to None. Returns: - Tuple[Image, Image, Image]: Tuple of deconvolved, restored, residual images + A tuple (deconvolved, restored, residual) of images """ if visibility.format != "MS": raise NotImplementedError( diff --git a/karabo/imaging/imager_wsclean.py b/karabo/imaging/imager_wsclean.py index cea717c1..517b9fd1 100644 --- a/karabo/imaging/imager_wsclean.py +++ b/karabo/imaging/imager_wsclean.py @@ -242,20 +242,19 @@ def create_image_custom_command( Use absolute paths to reference files or directories like the measurement set. Args: - command (str): Command to execute. Example: wsclean -size 2048 2048 + command: Command to execute. Example: wsclean -size 2048 2048 -scale 0.0022222222222222222deg -niter 50000 -mgain 0.8 -abs-threshold 100µJy /tmp/measurements.MS - output_filenames (Union[str, List[str]], optional): WSClean output filename(s) + output_filenames: WSClean output filename(s) (relative to the working directory) that should be returned as Image objects. Can be a string for one file or a list of strings for multiple files. Example 1: "wsclean-image.fits" Example 2: ['wsclean-image.fits', 'wsclean-residual.fits'] - Defaults to "wsclean-image.fits". Returns: - Union[Image, List[Image]]: If output_filenames is a string, returns an Image - object of the file output_filenames. + If output_filenames is a string, returns an Image object of the file + output_filenames. If output_filenames is a list of strings, returns a list of Image objects, one object per filename in output_filenames. """ diff --git a/karabo/simulation/interferometer.py b/karabo/simulation/interferometer.py index 3cb16dd9..1d6c45ba 100644 --- a/karabo/simulation/interferometer.py +++ b/karabo/simulation/interferometer.py @@ -360,17 +360,27 @@ def run_simulation( visibility_format: VisibilityFormat = "MS", visibility_path: Optional[FilePathType] = None, ) -> Union[Visibility, List[Visibility]]: + """Run an interferometer simulation, generating simulated visibility data. + + Args: + telescope: Telescope model defining the configuration + sky: sky model defining the sky sources + observation: observation settings + backend: Simulation backend to be used + primary_beam: Primary beam to be included into visibilities. + Currently only relevant for RASCIL. + For OSKAR, use the InterferometerSimulation constructor parameters + instead. + visibility_format: Visibility format in which to write generated data to + disk + visibility_path: Path for the visibility output file. If None, visibility + will be written to short term cache directory. + + Returns: + Visibility object of the generated data or list of Visibility objects + for ObservationParallelized observations. """ - Run a single interferometer simulation with the given sky, telescope and - observation settings. - :param telescope: telescope model defining the configuration - :param sky: sky model defining the sky sources - :param observation: observation settings - :param backend: Backend used to perform calculations (e.g. OSKAR, RASCIL) - :param primary_beam: Primary beam to be included into visibilities. - Currently only relevant for RASCIL. - For OSKAR, use the InterferometerSimulation constructor parameters instead. - """ + if visibility_path is None: visibility_path = self._get_visibility_path_in_tmp_dir(visibility_format) if not is_valid_path_for_format(visibility_path, visibility_format): @@ -443,17 +453,6 @@ def __run_simulation_rascil( visibility_path: FilePathType, primary_beam: Optional[RASCILImage], ) -> Visibility: - """ - Compute visibilities from SkyModel using the RASCIL backend. - - :param telescope: Telescope configuration. - Should be created using the RASCIL backend - :param sky: SkyModel to be used in the simulation. - Will be converted into a RASCIL-compatible list of SkyComponent objects. - :param observation: Observation details - :param visibility_format: visibility format to generate - :param primary_beam: Primary beam to be included into visibilities. - """ # Steps followed in this simulation: # Compute hour angles based on Observation details # Create an empty visibility according to the observation details @@ -527,7 +526,6 @@ def __run_simulation_rascil( ) # Save visibilities to disk - # TODO verify output export_visibility_to_ms(visibility_path, [vis]) return Visibility(visibility_path) @@ -686,14 +684,6 @@ def __run_simulation_oskar( params_total: OskarSettingsTreeType, precision: PrecisionType = "double", ) -> Dict[str, Any]: - """ - Run a single interferometer simulation with a given sky, - telescope and observation settings. - :param params_total: Combined parameters for the interferometer - :param os_sky: OSKAR sky model as np.array or oskar.Sky - :param precision: precision of the simulation - """ - setting_tree = oskar.SettingsTree("oskar_sim_interferometer") setting_tree.from_dict(params_total) diff --git a/karabo/simulation/sample_simulation.py b/karabo/simulation/sample_simulation.py index 303c3206..4a42f178 100644 --- a/karabo/simulation/sample_simulation.py +++ b/karabo/simulation/sample_simulation.py @@ -18,18 +18,18 @@ def run_sample_simulation( ) -> Tuple[ Visibility, IntFloatList, SkyModel, Telescope, Observation, InterferometerSimulation ]: - """ - TODO update - Creates example visibilities for use in tests, experiments and examples. + """Creates example visibilities for use in tests, experiments and examples. Args: - phase_center: ra and dec of the sky. Defaults to [250, -80] if not provided. - verbose: Boolean to decide if console outputs are made during simulation - (e.g. for use in ipynb) + simulator_backend: Backend to use for simulation + visibility_format: Visibility format in which to write generated data to disk + verbose: Enable / disable progress prints Returns: - Visibility: visibilities created by the simulation - SkyModel: Sky model used for the simulation + A tuple (visibility, phase_center, sky, telescope, observation, + interferometer_sim) with the generated visibility data and phase center, + sky model, telescope, observation and interferometer configuration used + to generate it. """ if simulator_backend == SimulatorBackend.RASCIL: raise NotImplementedError( diff --git a/karabo/simulation/visibility.py b/karabo/simulation/visibility.py index 334db9dc..f4c5d1bc 100644 --- a/karabo/simulation/visibility.py +++ b/karabo/simulation/visibility.py @@ -24,10 +24,26 @@ def is_valid_path_for_format(path: FilePathType, format: VisibilityFormat) -> bool: + """Tests if a path is valid for a specific format + + Args: + path: path to visibility + format: visibility format + + Returns: + True if valid, False otherwise + """ return _VISIBILITY_FORMAT_VALIDATORS[format](path) class Visibility: + """Class representing visibility data on the filesystem + + Args: + path: Path to visibility data directory (for MS format) or file. + Visibility format will be inferred from the path. + """ + def __init__(self, path: FilePathType) -> None: if not os.path.exists(path): raise ValueError(f"Path {path} does not exist") diff --git a/karabo/test/test_sim_format_imager_combos.py b/karabo/test/test_sim_format_imager_combos.py index e729299f..d391e415 100644 --- a/karabo/test/test_sim_format_imager_combos.py +++ b/karabo/test/test_sim_format_imager_combos.py @@ -1,4 +1,3 @@ -# TODO files abräumen import os import pytest