Make add_segmentation kwarg only (#1687)

Author: h-mayorquin

CHANGELOG.md

@@ -3,6 +3,7 @@
 ## Removals, Deprecations and Changes
 * Removed deprecated wrapper functions from `roiextractors_pending_deprecation.py` (March 2026 deadline): `add_imaging_plane_to_nwbfile`, `add_image_segmentation_to_nwbfile`, `add_photon_series_to_nwbfile`, `add_plane_segmentation_to_nwbfile`, `add_background_plane_segmentation_to_nwbfile`, `add_background_fluorescence_traces_to_nwbfile`, `add_summary_images_to_nwbfile`. [PR #1680](https://github.com/catalystneuro/neuroconv/pull/1680)
 * Added `*args` positional argument deprecation to `add_imaging_to_nwbfile` to enforce keyword-only arguments. Will be enforced on or after September 2026. [PR #1680](https://github.com/catalystneuro/neuroconv/pull/1680)
+* Added `*args` positional argument deprecation to `add_segmentation_to_nwbfile` to enforce keyword-only arguments. Will be enforced on or after September 2026. [PR #1687](https://github.com/catalystneuro/neuroconv/pull/1687)
 * Removed the deprecated `staging` parameter from `automatic_dandi_upload`. Use `sandbox` instead. [PR #1678](https://github.com/catalystneuro/neuroconv/pull/1678)
 * Removed the deprecated `container_name` parameter from `ImageInterface.add_to_nwbfile` and `DeepLabCutInterface.add_to_nwbfile`. Use `metadata_key` in `__init__` instead. [PR #1678](https://github.com/catalystneuro/neuroconv/pull/1678)
 * Removed the deprecated `time_series_name` parameter from `add_recording_as_time_series_to_nwbfile`. Use `metadata_key` instead. [PR #1678](https://github.com/catalystneuro/neuroconv/pull/1678)

src/neuroconv/tools/roiextractors/roiextractors.py

@@ -1911,6 +1911,7 @@ def add_segmentation_to_nwbfile(
     segmentation_extractor: SegmentationExtractor,
     nwbfile: NWBFile,
     metadata: dict | None = None,
+    *args,  # TODO: change to * (keyword only) on or after September 2026
     plane_segmentation_name: str | None = None,
     background_plane_segmentation_name: str | None = None,
     include_background_segmentation: bool = False,
@@ -1950,6 +1951,45 @@ def add_segmentation_to_nwbfile(
     NWBFile
         The NWBFile with the added segmentation data.
     """
+    # TODO: Remove this block in September 2026 or after when positional arguments are no longer supported.
+    if args:
+        parameter_names = [
+            "plane_segmentation_name",
+            "background_plane_segmentation_name",
+            "include_background_segmentation",
+            "include_roi_centroids",
+            "include_roi_acceptance",
+            "mask_type",
+            "iterator_options",
+        ]
+        num_positional_args_before_args = 3  # segmentation_extractor, nwbfile, metadata
+        if len(args) > len(parameter_names):
+            raise TypeError(
+                f"add_segmentation_to_nwbfile() takes at most {len(parameter_names) + num_positional_args_before_args} positional arguments but "
+                f"{len(args) + num_positional_args_before_args} were given. "
+                "Note: Positional arguments are deprecated and will be removed in September 2026 or after. Please use keyword arguments."
+            )
+        positional_values = dict(zip(parameter_names, args))
+        passed_as_positional = list(positional_values.keys())
+        warnings.warn(
+            f"Passing arguments positionally to add_segmentation_to_nwbfile is deprecated "
+            f"and will be removed in September 2026 or after. "
+            f"The following arguments were passed positionally: {passed_as_positional}. "
+            "Please use keyword arguments instead.",
+            FutureWarning,
+            stacklevel=2,
+        )
+        plane_segmentation_name = positional_values.get("plane_segmentation_name", plane_segmentation_name)
+        background_plane_segmentation_name = positional_values.get(
+            "background_plane_segmentation_name", background_plane_segmentation_name
+        )
+        include_background_segmentation = positional_values.get(
+            "include_background_segmentation", include_background_segmentation
+        )
+        include_roi_centroids = positional_values.get("include_roi_centroids", include_roi_centroids)
+        include_roi_acceptance = positional_values.get("include_roi_acceptance", include_roi_acceptance)
+        mask_type = positional_values.get("mask_type", mask_type)
+        iterator_options = positional_values.get("iterator_options", iterator_options)
 
     # Add device:
     _add_devices_to_nwbfile_old_list_format(nwbfile=nwbfile, metadata=metadata)