Skip to content

Reference

polars_pairing.PairingFunctions

Source code in polars_pairing/__init__.py 
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
@pl.api.register_expr_namespace("pairing")
class PairingFunctions:
    def __init__(self, expr: pl.Expr):
        self._expr = expr

    def pair(
        self, other: IntoExpr, method: Literal["hagen", "szudzik", "cantor"] = "hagen"
    ) -> pl.Expr:
        """
        Applies a pairing function to uniquely encode two nonnegative integers
        into a single nonnegative integer.

        Parameters
        ----------
        method
            The method to use for pairing. Either "hagen", "szudzik" or "cantor",
            defaults to "hagen".

        Examples
        --------
        >>> df = pl.DataFrame(
        ...     {
        ...         "n1": [2, 2, 3, 1501],
        ...         "n2": [-6, 7, 8, 10740],
        ...     }
        ... )
        >>> df.select(pl.col("n1").pairing.pair(pl.col("n2")).alias("pair"))
        shape: (4, 1)
        ┌───────────┐
        │ pair      │
        │ ---       │
        │ u64       │
        ╞═══════════╡
        │ null      │
        │ 54        │
        │ 70        │
        │ 115350602 │
        └───────────┘
        >>> df.select(pl.col("n1").pairing.pair(pl.col("n2"), method="szudzik").alias("pair"))
        shape: (4, 1)
        ┌───────────┐
        │ pair      │
        │ ---       │
        │ u64       │
        ╞═══════════╡
        │ null      │
        │ 51        │
        │ 67        │
        │ 115349101 │
        └───────────┘
        """
        return register_plugin(
            args=[self._expr, other],
            kwargs={"method": method},
            symbol="pair",
            is_elementwise=True,
            lib=lib,
        )

    def unpair(
        self, method: Literal["hagen", "szudzik", "cantor"] = "hagen"
    ) -> pl.Expr:
        """
        Applies an unpairing function to uniquely decode a nonnegative integer
        into two nonnegative integers.

        Parameters
        ----------
        method
            The method to use for unpairing. Either "hagen", "szudzik" or "cantor",
            defaults to "hagen".

        Examples
        --------
        >>> df = pl.DataFrame({"pair": [None, 607, -4, 18871362]})
        >>> df.select(pl.col("pair").pairing.unpair().alias("unpair"))
        shape: (4, 1)
        ┌─────────────┐
        │ unpair      │
        │ ---         │
        │ struct[2]   │
        ╞═════════════╡
        │ {null,null} │
        │ {24,15}     │
        │ {null,null} │
        │ {513,4344}  │
        └─────────────┘
        >>> df.select(pl.col("pair").pairing.unpair(method="szudzik").alias("unpair"))
        shape: (4, 1)
        ┌─────────────┐
        │ unpair      │
        │ ---         │
        │ struct[2]   │
        ╞═════════════╡
        │ {null,null} │
        │ {24,7}      │
        │ {null,null} │
        │ {1026,4344} │
        └─────────────┘
        """
        return register_plugin(
            args=[self._expr],
            kwargs={"method": method},
            symbol="unpair",
            is_elementwise=True,
            lib=lib,
        )

pair(other, method='hagen')

Applies a pairing function to uniquely encode two nonnegative integers into a single nonnegative integer.

Parameters:

Name Type Description Default
method Literal['hagen', 'szudzik', 'cantor']

The method to use for pairing. Either "hagen", "szudzik" or "cantor", defaults to "hagen".

 'hagen'

Examples:

>>> df = pl.DataFrame(
...     {
...         "n1": [2, 2, 3, 1501],
...         "n2": [-6, 7, 8, 10740],
...     }
... )
>>> df.select(pl.col("n1").pairing.pair(pl.col("n2")).alias("pair"))
shape: (4, 1)
┌───────────┐
│ pair      │
│ ---       │
│ u64       │
╞═══════════╡
│ null      │
│ 54        │
│ 70        │
│ 115350602 │
└───────────┘
>>> df.select(pl.col("n1").pairing.pair(pl.col("n2"), method="szudzik").alias("pair"))
shape: (4, 1)
┌───────────┐
│ pair      │
│ ---       │
│ u64       │
╞═══════════╡
│ null      │
│ 51        │
│ 67        │
│ 115349101 │
└───────────┘
Source code in polars_pairing/__init__.py 
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
def pair(
    self, other: IntoExpr, method: Literal["hagen", "szudzik", "cantor"] = "hagen"
) -> pl.Expr:
    """
    Applies a pairing function to uniquely encode two nonnegative integers
    into a single nonnegative integer.

    Parameters
    ----------
    method
        The method to use for pairing. Either "hagen", "szudzik" or "cantor",
        defaults to "hagen".

    Examples
    --------
    >>> df = pl.DataFrame(
    ...     {
    ...         "n1": [2, 2, 3, 1501],
    ...         "n2": [-6, 7, 8, 10740],
    ...     }
    ... )
    >>> df.select(pl.col("n1").pairing.pair(pl.col("n2")).alias("pair"))
    shape: (4, 1)
    ┌───────────┐
    │ pair      │
    │ ---       │
    │ u64       │
    ╞═══════════╡
    │ null      │
    │ 54        │
    │ 70        │
    │ 115350602 │
    └───────────┘
    >>> df.select(pl.col("n1").pairing.pair(pl.col("n2"), method="szudzik").alias("pair"))
    shape: (4, 1)
    ┌───────────┐
    │ pair      │
    │ ---       │
    │ u64       │
    ╞═══════════╡
    │ null      │
    │ 51        │
    │ 67        │
    │ 115349101 │
    └───────────┘
    """
    return register_plugin(
        args=[self._expr, other],
        kwargs={"method": method},
        symbol="pair",
        is_elementwise=True,
        lib=lib,
    )

unpair(method='hagen')

Applies an unpairing function to uniquely decode a nonnegative integer into two nonnegative integers.

Parameters:

Name Type Description Default
method Literal['hagen', 'szudzik', 'cantor']

The method to use for unpairing. Either "hagen", "szudzik" or "cantor", defaults to "hagen".

 'hagen'

Examples:

>>> df = pl.DataFrame({"pair": [None, 607, -4, 18871362]})
>>> df.select(pl.col("pair").pairing.unpair().alias("unpair"))
shape: (4, 1)
┌─────────────┐
│ unpair      │
│ ---         │
│ struct[2]   │
╞═════════════╡
│ {null,null} │
│ {24,15}     │
│ {null,null} │
│ {513,4344}  │
└─────────────┘
>>> df.select(pl.col("pair").pairing.unpair(method="szudzik").alias("unpair"))
shape: (4, 1)
┌─────────────┐
│ unpair      │
│ ---         │
│ struct[2]   │
╞═════════════╡
│ {null,null} │
│ {24,7}      │
│ {null,null} │
│ {1026,4344} │
└─────────────┘
Source code in polars_pairing/__init__.py 
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
def unpair(
    self, method: Literal["hagen", "szudzik", "cantor"] = "hagen"
) -> pl.Expr:
    """
    Applies an unpairing function to uniquely decode a nonnegative integer
    into two nonnegative integers.

    Parameters
    ----------
    method
        The method to use for unpairing. Either "hagen", "szudzik" or "cantor",
        defaults to "hagen".

    Examples
    --------
    >>> df = pl.DataFrame({"pair": [None, 607, -4, 18871362]})
    >>> df.select(pl.col("pair").pairing.unpair().alias("unpair"))
    shape: (4, 1)
    ┌─────────────┐
    │ unpair      │
    │ ---         │
    │ struct[2]   │
    ╞═════════════╡
    │ {null,null} │
    │ {24,15}     │
    │ {null,null} │
    │ {513,4344}  │
    └─────────────┘
    >>> df.select(pl.col("pair").pairing.unpair(method="szudzik").alias("unpair"))
    shape: (4, 1)
    ┌─────────────┐
    │ unpair      │
    │ ---         │
    │ struct[2]   │
    ╞═════════════╡
    │ {null,null} │
    │ {24,7}      │
    │ {null,null} │
    │ {1026,4344} │
    └─────────────┘
    """
    return register_plugin(
        args=[self._expr],
        kwargs={"method": method},
        symbol="unpair",
        is_elementwise=True,
        lib=lib,
    )