feat(ordinal): add index_start to OrdinalEncoder for zero-indexed labels (#291) (#479)

Author: SAY-5

category_encoders/ordinal.py

@@ -48,6 +48,11 @@ class OrdinalEncoder( util.UnsupervisedTransformerMixin,util.BaseEncoder):
         options are 'error', 'return_nan', and 'value, default to 'value',
         which treat nan as a category at fit time,
         or -2 at transform time if nan is not a category during fit.
+    index_start: int
+        integer at which to start labelling the categories. Defaults to 1.
+        Set to 0 for zero-indexed labels, which can be convenient when feeding
+        the encoded values into models that expect zero-indexed inputs such as
+        embedding layers.
 
     Example
     -------
@@ -107,6 +112,7 @@ def __init__(
         return_df: bool = True,
         handle_unknown: str = 'value',
         handle_missing: str = 'value',
+        index_start: int = 1,
     ):
         super().__init__(
             verbose=verbose,
@@ -120,6 +126,7 @@ def __init__(
         if self.mapping_supplied:
             mapping = self._validate_supplied_mapping(mapping)
         self.mapping = mapping
+        self.index_start = index_start
 
     @property
     def category_mapping(self) -> list[dict[str, str | dict | pd.Series]] | None:
@@ -136,6 +143,7 @@ def _fit(self, X: pd.DataFrame, y: pd.Series | None = None, **kwargs) -> None:
             cols=self.cols,
             handle_unknown=self.handle_unknown,
             handle_missing=self.handle_missing,
+            index_start=self.index_start,
         )
         self.mapping = categories
 
@@ -146,6 +154,7 @@ def _transform(self, X: pd.DataFrame) -> pd.DataFrame:
             cols=self.cols,
             handle_unknown=self.handle_unknown,
             handle_missing=self.handle_missing,
+            index_start=self.index_start,
         )
         return X
 
@@ -217,6 +226,7 @@ def ordinal_encoding(
         cols: list[str] = None,
         handle_unknown: str = 'value',
         handle_missing: str = 'value',
+        index_start: int = 1,
     ) -> tuple[pd.DataFrame, list[dict]]:
         """Ordinal encoding uses a single column of integers to represent the classes.
 
@@ -286,7 +296,10 @@ def ordinal_encoding(
 
                 index = pd.Series(categories).fillna(nan_identity).unique()
 
-                data = pd.Series(index=index, data=range(1, len(index) + 1))
+                data = pd.Series(
+                    index=index,
+                    data=range(index_start, len(index) + index_start),
+                )
 
                 if handle_missing == 'value' and ~data.index.isna().any():
                     data.loc[nan_identity] = -2

tests/test_ordinal.py

@@ -244,6 +244,25 @@ def test_no_gaps(self):
             expected_mapping_return_nan, enc_return_nan.mapping[0]['mapping']
         )
 
+    def test_default_index_start_is_one(self):
+        """Test that the default ordinal labels start at 1 (issue #291)."""
+        train = pd.DataFrame({'city': ['chicago', 'st louis', 'detroit']})
+        enc = encoders.OrdinalEncoder(cols=['city'])
+        result = enc.fit_transform(train)['city'].tolist()
+        self.assertEqual([1, 2, 3], result)
+
+    def test_index_start_zero(self):
+        """Test that index_start=0 produces zero-indexed ordinal labels (issue #291)."""
+        train = pd.DataFrame({'city': ['chicago', 'st louis', 'detroit']})
+        enc = encoders.OrdinalEncoder(cols=['city'], index_start=0)
+        result = enc.fit_transform(train)['city'].tolist()
+        self.assertEqual([0, 1, 2], result)
+
+        expected_mapping = pd.Series(
+            [0, 1, 2, -2], index=['chicago', 'st louis', 'detroit', np.nan]
+        )
+        pd.testing.assert_series_equal(expected_mapping, enc.mapping[0]['mapping'])
+
     def test_nan_and_none_is_encoded_the_same(self):
         """Test that NaN and None are encoded the same."""
         train = pd.DataFrame({'city': [np.nan, None]})