docstrings

meteor/scripts/compute_difference_map.py

@@ -47,10 +47,39 @@ def __init__(self, *args: Any, **kwargs: Any) -> None:
         )
 
 
-def make_requested_diffmap(
+def kweight_diffmap_according_to_mode(
     *, mapset: DiffMapSet, kweight_mode: WeightMode, kweight_parameter: float | None = None
 ) -> tuple[Map, float | None]:
-    # TODO: docstring
+    """
+    Make and k-weight a difference map using a specified `WeightMode`.
+
+    Three modes are possible to pick the k-parameter:
+      * `WeightMode.optimize`, max-negentropy value will and picked, this may take some time
+      * `WeightMode.fixed`, `kweight_parameter` is used
+      * `WeightMode.none`, then no k-weighting is done (note this is NOT equivalent to
+         kweight_parameter=0.0)
+
+    Parameters
+    ----------
+    mapset: DiffMapSet
+        The set of `derivative`, `native`, `computed` maps to use to compute the diffmap.
+
+    kweight_mode: WeightMode
+        How to set the k-parameter: {optimize, fixed, none}. See above. If `fixed`, then
+        `kweight_parameter` is required.
+
+    kweight_parameter: float | None
+        If kweight_mode == WeightMode.fixed, then this must be a float that specifies the
+        k-parameter to use.
+
+    Returns
+    -------
+    diffmap: meteor.rsmap.Map
+        The difference map, k-weighted if requested.
+
+    kweight_parameter: float | None
+        The `kweight_parameter` used. Only really interesting if WeightMode.optimize.
+    """
     log.info("Computing difference map.")
 
     if kweight_mode == WeightMode.optimize:
@@ -84,13 +113,41 @@ def make_requested_diffmap(
     return diffmap, kweight_parameter
 
 
-def denoise_diffmap(
+def denoise_diffmap_according_to_mode(
     *,
     diffmap: Map,
     tv_denoise_mode: WeightMode,
     tv_weight: float | None = None,
 ) -> tuple[Map, TvDenoiseResult]:
-    # TODO: docstring
+    """
+    Denoise a difference map `diffmap` using a specified `WeightMode`.
+
+    Three modes are possible:
+      * `WeightMode.optimize`, max-negentropy value will and picked, this may take some time
+      * `WeightMode.fixed`, `tv_weight` is used
+      * `WeightMode.none`, then no TV denoising is done (equivalent to weight = 0.0)
+
+    Parameters
+    ----------
+    diffmap: meteor.rsmap.Map
+        The map to denoise.
+
+    tv_denoise_mode: WeightMode
+        How to set the TV weight parameter: {optimize, fixed, none}. See above. If `fixed`, the
+        `tv_weight` parameter is required.
+
+    tv_weight: float | None
+        If tv_denoise_mode == WeightMode.fixed, then this must be a float that specifies the weight
+        to use.
+
+    Returns
+    -------
+    final_map: meteor.rsmap.Map
+        The difference map, denoised if requested
+
+    metadata: meteor.tv.TvDenoiseResult
+        Information regarding the denoising process.
+    """
     if tv_denoise_mode == WeightMode.optimize:
         log.info(
             "Searching for max-negentropy TV denoising weight",
@@ -164,10 +221,10 @@ def main(command_line_arguments: list[str] | None = None) -> None:
     parser.check_output_filepaths(args)
     mapset = parser.load_difference_maps(args)
 
-    diffmap, kparameter_used = make_requested_diffmap(
+    diffmap, kparameter_used = kweight_diffmap_according_to_mode(
         kweight_mode=args.kweight_mode, kweight_parameter=args.kweight_parameter, mapset=mapset
     )
-    final_map, metadata = denoise_diffmap(
+    final_map, metadata = denoise_diffmap_according_to_mode(
         tv_denoise_mode=args.tv_denoise_mode, tv_weight=args.tv_weight, diffmap=diffmap
     )
 

test/functional/test_compute_difference_map.py

@@ -1,20 +1,19 @@
 from pathlib import Path
+from unittest import mock
 
 import numpy as np
 import pytest
 import reciprocalspaceship as rs
 
-from unittest import mock
-
 from meteor.rsmap import Map
 from meteor.scripts import compute_difference_map
 from meteor.scripts.common import WeightMode
 from meteor.tv import TvDenoiseResult
 from meteor.utils import filter_common_indices
 
-
 TV_WEIGHTS_TO_SCAN = np.array([0.005, 0.01, 0.025, 0.5])
 
+
 @mock.patch("meteor.scripts.compute_difference_map.TV_WEIGHTS_TO_SCAN", TV_WEIGHTS_TO_SCAN)
 @pytest.mark.parametrize("kweight_mode", list(WeightMode))
 @pytest.mark.parametrize("tv_weight_mode", list(WeightMode))
@@ -25,7 +24,6 @@ def test_script_produces_consistent_results(
     testing_mtz_file: Path,
     tmp_path: Path,
 ) -> None:
-
     # for when WeightMode.fixed; these maximize negentropy in manual testing
     kweight_parameter = 0.05
     tv_weight = 0.01

test/unit/scripts/test_compute_difference_map.py

@@ -13,8 +13,8 @@
 from meteor.scripts.common import DiffMapSet, WeightMode
 from meteor.scripts.compute_difference_map import (
     TvDiffmapArgParser,
-    denoise_diffmap,
-    make_requested_diffmap,
+    denoise_diffmap_according_to_mode,
+    kweight_diffmap_according_to_mode,
 )
 from meteor.tv import TvDenoiseResult
 
@@ -48,28 +48,28 @@ def test_tv_diffmap_parser(parsed_tv_cli_args: argparse.Namespace) -> None:
 
 
 @pytest.mark.parametrize("mode", list(WeightMode))
-def test_make_requested_diffmap(
+def test_kweight_diffmap_according_to_mode(
     mode: WeightMode, diffmap_set: DiffMapSet, fixed_kparameter: float
 ) -> None:
     # ensure the two maps aren't exactly the same to prevent numerical issues
     diffmap_set.derivative.amplitudes.iloc[0] += 1.0
 
-    diffmap, _ = make_requested_diffmap(
+    diffmap, _ = kweight_diffmap_according_to_mode(
         mapset=diffmap_set, kweight_mode=mode, kweight_parameter=fixed_kparameter
     )
     assert len(diffmap) > 0
     assert isinstance(diffmap, Map)
 
     if mode == WeightMode.fixed:
         with pytest.raises(TypeError):
-            _ = make_requested_diffmap(
+            _ = kweight_diffmap_according_to_mode(
                 mapset=diffmap_set, kweight_mode=mode, kweight_parameter=None
             )
 
 
 @pytest.mark.parametrize("mode", list(WeightMode))
-def test_denoise_diffmap(mode: WeightMode, random_difference_map: Map) -> None:
-    diffmap, metadata = denoise_diffmap(
+def test_denoise_diffmap_according_to_mode(mode: WeightMode, random_difference_map: Map) -> None:
+    diffmap, metadata = denoise_diffmap_according_to_mode(
         diffmap=random_difference_map,
         tv_denoise_mode=mode,
         tv_weight=TV_WEIGHT,
@@ -85,7 +85,7 @@ def test_denoise_diffmap(mode: WeightMode, random_difference_map: Map) -> None:
     elif mode == WeightMode.fixed:
         assert metadata.optimal_weight == TV_WEIGHT
         with pytest.raises(TypeError):
-            _, _ = denoise_diffmap(
+            _, _ = denoise_diffmap_according_to_mode(
                 diffmap=random_difference_map, tv_denoise_mode=mode, tv_weight=None
             )