Skip to content

BaseOperableBlock

Bases: BaseBlock

Any object that can be converted into an expression.

Methods:

Name Description
drop_extras

Indicates that labels not present in the other expression should be discarded during joins.
filter

Creates a copy of the object containing only a subset of the original rows.
keep_extras

Indicates that labels not present in the other expression should be kept during joins.
map

Converts the object to an expression (see .to_expr()) and then applies Expression.map.
over

Indicates that the expression can be broadcasted over the given dimensions during addition and subtraction.
pick

Filters elements by the given criteria and then drops the filtered dimensions.
raise_extras

Indicates that labels not present in the other expression should raise an error during joins.
rename

Renames one or several of the object's dimensions.
sum

Converts the object to an expression (see .to_expr()) and then applies Expression.sum.
sum_by

Converts the object to an expression (see .to_expr()) and then applies Expression.sum_by.
to_expr

Converts the object to a Pyoframe Expression.
with_columns

Creates a new object with modified columns.
Source code in pyoframe/_core.py 
73
74
75
76
def __init__(self, *args, **kwargs):
    self._extras_strategy = ExtrasStrategy.UNSET
    self._allowed_new_dims: list[str] = []
    super().__init__(*args, **kwargs)

drop_extras()

Indicates that labels not present in the other expression should be discarded during joins.

Learn more about join modifiers.

See Also

keep_extras.

Source code in pyoframe/_core.py 
102
103
104
105
106
107
108
109
110
111
112
113
114
115
def drop_extras(self):
    """Indicates that labels not present in the other expression should be discarded during joins.

    [Learn more](../../learn/concepts/join_modifiers.md) about join modifiers.

    See Also:
        [`keep_extras`][pyoframe.Expression.keep_extras].
    """
    if self._extras_strategy == ExtrasStrategy.DROP:
        return self
    new = self._new(self.data, name=f"{self.name}.drop_extras()")
    new._copy_flags(self)
    new._extras_strategy = ExtrasStrategy.DROP
    return new

filter(*args, **kwargs)

Creates a copy of the object containing only a subset of the original rows.

Takes the same arguments as polars.DataFrame.filter.

See Also

Expression.pick or Variable.pick if you wish to drop the filtered column in the process.

Source code in pyoframe/_core.py 
208
209
210
211
212
213
214
215
216
217
218
219
@return_new
def filter(self, *args, **kwargs):
    """Creates a copy of the object containing only a subset of the original rows.

    Takes the same arguments as [`polars.DataFrame.filter`](https://docs.pola.rs/api/python/stable/reference/dataframe/api/polars.DataFrame.filter.html).

    See Also:
        [`Expression.pick`][pyoframe.Expression.pick] or [`Variable.pick`][pyoframe.Variable.pick] if you wish to drop the filtered
        column in the process.

    """
    return self.data.filter(*args, **kwargs)

keep_extras()

Indicates that labels not present in the other expression should be kept during joins.

Learn more about join modifiers.

See Also

drop_extras.

Source code in pyoframe/_core.py 
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
def keep_extras(self):
    """Indicates that labels not present in the other expression should be kept during joins.

    [Learn more](../../learn/concepts/join_modifiers.md) about join modifiers.

    See Also:
        [`drop_extras`][pyoframe.Expression.drop_extras].
    """
    if self._extras_strategy == ExtrasStrategy.KEEP:
        return self
    new = self._new(self.data, name=f"{self.name}.keep_extras()")
    new._copy_flags(self)
    new._extras_strategy = ExtrasStrategy.KEEP
    return new

map(*args, **kwargs)

Converts the object to an expression (see .to_expr()) and then applies Expression.map.

Source code in pyoframe/_core.py 
271
272
273
def map(self, *args, **kwargs):
    """Converts the object to an expression (see `.to_expr()`) and then applies [`Expression.map`][pyoframe.Expression.map]."""
    return self.to_expr().map(*args, **kwargs)

over(*dims: str)

Indicates that the expression can be broadcasted over the given dimensions during addition and subtraction.

Source code in pyoframe/_core.py 
134
135
136
137
138
139
def over(self, *dims: str):
    """Indicates that the expression can be broadcasted over the given dimensions during addition and subtraction."""
    new = self._new(self.data, name=f"{self.name}.over(…)")
    new._copy_flags(self)
    new._allowed_new_dims.extend(dims)
    return new

pick(**kwargs)

Filters elements by the given criteria and then drops the filtered dimensions.

Examples:

>>> m = pf.Model()
>>> m.v = pf.Variable(
...     [
...         {"hour": ["00:00", "06:00", "12:00", "18:00"]},
...         {"city": ["Toronto", "Berlin", "Paris"]},
...     ]
... )
>>> m.v.pick(hour="06:00")
<Expression (linear) height=3 terms=3>
┌─────────┬──────────────────┐
│ city    ┆ expression       │
│ (3)     ┆                  │
╞═════════╪══════════════════╡
│ Toronto ┆ v[06:00,Toronto] │
│ Berlin  ┆ v[06:00,Berlin]  │
│ Paris   ┆ v[06:00,Paris]   │
└─────────┴──────────────────┘
>>> m.v.pick(hour="06:00", city="Toronto")
<Expression (linear) terms=1>
v[06:00,Toronto]
See Also

Expression.filter or Variable.filter if you don't wish to drop the filtered column.

Source code in pyoframe/_core.py 
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
@return_new
def pick(self, **kwargs):
    """Filters elements by the given criteria and then drops the filtered dimensions.

    Examples:
        >>> m = pf.Model()
        >>> m.v = pf.Variable(
        ...     [
        ...         {"hour": ["00:00", "06:00", "12:00", "18:00"]},
        ...         {"city": ["Toronto", "Berlin", "Paris"]},
        ...     ]
        ... )
        >>> m.v.pick(hour="06:00")
        <Expression (linear) height=3 terms=3>
        ┌─────────┬──────────────────┐
        │ city    ┆ expression       │
        │ (3)     ┆                  │
        ╞═════════╪══════════════════╡
        │ Toronto ┆ v[06:00,Toronto] │
        │ Berlin  ┆ v[06:00,Berlin]  │
        │ Paris   ┆ v[06:00,Paris]   │
        └─────────┴──────────────────┘
        >>> m.v.pick(hour="06:00", city="Toronto")
        <Expression (linear) terms=1>
        v[06:00,Toronto]

    See Also:
        [`Expression.filter`][pyoframe.Expression.filter] or [`Variable.filter`][pyoframe.Variable.filter] if you don't wish to drop the filtered column.
    """
    return self.data.filter(**kwargs).drop(kwargs.keys())

raise_extras()

Indicates that labels not present in the other expression should raise an error during joins.

This is the default behavior and, as such, this join modifier should only be used in the rare cases where you want to override a previous use of keep_extras() or drop_extras().

Learn more about join modifiers.

See Also

keep_extras and drop_extras.

Source code in pyoframe/_core.py 
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
def raise_extras(self):
    """Indicates that labels not present in the other expression should raise an error during joins.

    This is the default behavior and, as such, this join modifier should only be used in the rare cases where you want to override a previous use of `keep_extras()` or `drop_extras()`.

    [Learn more](../../learn/concepts/join_modifiers.md) about join modifiers.

    See Also:
        [`keep_extras`][pyoframe.Expression.keep_extras] and [`drop_extras`][pyoframe.Expression.drop_extras].
    """
    if self._extras_strategy == ExtrasStrategy.UNSET:
        return self
    new = self._new(self.data, name=f"{self.name}.raise_extras()")
    new._copy_flags(self)
    new._extras_strategy = ExtrasStrategy.UNSET
    return new

rename(*args, **kwargs)

Renames one or several of the object's dimensions.

Takes the same arguments as polars.DataFrame.rename.

See the portfolio optimization example for a usage example.

Examples:

>>> m = pf.Model()
>>> m.v = pf.Variable(
...     {"hour": ["00:00", "06:00", "12:00", "18:00"]},
...     {"city": ["Toronto", "Berlin", "Paris"]},
... )
>>> m.v
<Variable 'v' height=12>
┌───────┬─────────┬──────────────────┐
│ hour  ┆ city    ┆ variable         │
│ (4)   ┆ (3)     ┆                  │
╞═══════╪═════════╪══════════════════╡
│ 00:00 ┆ Toronto ┆ v[00:00,Toronto] │
│ 00:00 ┆ Berlin  ┆ v[00:00,Berlin]  │
│ 00:00 ┆ Paris   ┆ v[00:00,Paris]   │
│ 06:00 ┆ Toronto ┆ v[06:00,Toronto] │
│ 06:00 ┆ Berlin  ┆ v[06:00,Berlin]  │
│ …     ┆ …       ┆ …                │
│ 12:00 ┆ Berlin  ┆ v[12:00,Berlin]  │
│ 12:00 ┆ Paris   ┆ v[12:00,Paris]   │
│ 18:00 ┆ Toronto ┆ v[18:00,Toronto] │
│ 18:00 ┆ Berlin  ┆ v[18:00,Berlin]  │
│ 18:00 ┆ Paris   ┆ v[18:00,Paris]   │
└───────┴─────────┴──────────────────┘

>>> m.v.rename({"city": "location"})
<Expression (linear) height=12 terms=12>
┌───────┬──────────┬──────────────────┐
│ hour  ┆ location ┆ expression       │
│ (4)   ┆ (3)      ┆                  │
╞═══════╪══════════╪══════════════════╡
│ 00:00 ┆ Toronto  ┆ v[00:00,Toronto] │
│ 00:00 ┆ Berlin   ┆ v[00:00,Berlin]  │
│ 00:00 ┆ Paris    ┆ v[00:00,Paris]   │
│ 06:00 ┆ Toronto  ┆ v[06:00,Toronto] │
│ 06:00 ┆ Berlin   ┆ v[06:00,Berlin]  │
│ …     ┆ …        ┆ …                │
│ 12:00 ┆ Berlin   ┆ v[12:00,Berlin]  │
│ 12:00 ┆ Paris    ┆ v[12:00,Paris]   │
│ 18:00 ┆ Toronto  ┆ v[18:00,Toronto] │
│ 18:00 ┆ Berlin   ┆ v[18:00,Berlin]  │
│ 18:00 ┆ Paris    ┆ v[18:00,Paris]   │
└───────┴──────────┴──────────────────┘
Source code in pyoframe/_core.py 
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
@return_new
def rename(self, *args, **kwargs):
    """Renames one or several of the object's dimensions.

    Takes the same arguments as [`polars.DataFrame.rename`](https://docs.pola.rs/api/python/stable/reference/dataframe/api/polars.DataFrame.rename.html).

    See the [portfolio optimization example](../../examples/portfolio_optimization.md) for a usage example.

    Examples:
        >>> m = pf.Model()
        >>> m.v = pf.Variable(
        ...     {"hour": ["00:00", "06:00", "12:00", "18:00"]},
        ...     {"city": ["Toronto", "Berlin", "Paris"]},
        ... )
        >>> m.v
        <Variable 'v' height=12>
        ┌───────┬─────────┬──────────────────┐
        │ hour  ┆ city    ┆ variable         │
        │ (4)   ┆ (3)     ┆                  │
        ╞═══════╪═════════╪══════════════════╡
        │ 00:00 ┆ Toronto ┆ v[00:00,Toronto] │
        │ 00:00 ┆ Berlin  ┆ v[00:00,Berlin]  │
        │ 00:00 ┆ Paris   ┆ v[00:00,Paris]   │
        │ 06:00 ┆ Toronto ┆ v[06:00,Toronto] │
        │ 06:00 ┆ Berlin  ┆ v[06:00,Berlin]  │
        │ …     ┆ …       ┆ …                │
        │ 12:00 ┆ Berlin  ┆ v[12:00,Berlin]  │
        │ 12:00 ┆ Paris   ┆ v[12:00,Paris]   │
        │ 18:00 ┆ Toronto ┆ v[18:00,Toronto] │
        │ 18:00 ┆ Berlin  ┆ v[18:00,Berlin]  │
        │ 18:00 ┆ Paris   ┆ v[18:00,Paris]   │
        └───────┴─────────┴──────────────────┘

        >>> m.v.rename({"city": "location"})
        <Expression (linear) height=12 terms=12>
        ┌───────┬──────────┬──────────────────┐
        │ hour  ┆ location ┆ expression       │
        │ (4)   ┆ (3)      ┆                  │
        ╞═══════╪══════════╪══════════════════╡
        │ 00:00 ┆ Toronto  ┆ v[00:00,Toronto] │
        │ 00:00 ┆ Berlin   ┆ v[00:00,Berlin]  │
        │ 00:00 ┆ Paris    ┆ v[00:00,Paris]   │
        │ 06:00 ┆ Toronto  ┆ v[06:00,Toronto] │
        │ 06:00 ┆ Berlin   ┆ v[06:00,Berlin]  │
        │ …     ┆ …        ┆ …                │
        │ 12:00 ┆ Berlin   ┆ v[12:00,Berlin]  │
        │ 12:00 ┆ Paris    ┆ v[12:00,Paris]   │
        │ 18:00 ┆ Toronto  ┆ v[18:00,Toronto] │
        │ 18:00 ┆ Berlin   ┆ v[18:00,Berlin]  │
        │ 18:00 ┆ Paris    ┆ v[18:00,Paris]   │
        └───────┴──────────┴──────────────────┘

    """
    return self.data.rename(*args, **kwargs)

sum(*args, **kwargs)

Converts the object to an expression (see .to_expr()) and then applies Expression.sum.

Source code in pyoframe/_core.py 
263
264
265
def sum(self, *args, **kwargs):
    """Converts the object to an expression (see `.to_expr()`) and then applies [`Expression.sum`][pyoframe.Expression.sum]."""
    return self.to_expr().sum(*args, **kwargs)

sum_by(*args, **kwargs)

Converts the object to an expression (see .to_expr()) and then applies Expression.sum_by.

Source code in pyoframe/_core.py 
267
268
269
def sum_by(self, *args, **kwargs):
    """Converts the object to an expression (see `.to_expr()`) and then applies [`Expression.sum_by`][pyoframe.Expression.sum_by]."""
    return self.to_expr().sum_by(*args, **kwargs)

to_expr() -> Expression

Converts the object to a Pyoframe Expression.

Source code in pyoframe/_core.py 
258
259
260
261
@abstractmethod
def to_expr(self) -> Expression:
    """Converts the object to a Pyoframe Expression."""
    ...

with_columns(*args, **kwargs)

Creates a new object with modified columns.

Takes the same arguments as polars.DataFrame.with_columns.

Warning

Only use this function if you know what you're doing. It is not recommended to manually modify the columns within a Pyoframe object.

Source code in pyoframe/_core.py 
196
197
198
199
200
201
202
203
204
205
206
@return_new
def with_columns(self, *args, **kwargs):
    """Creates a new object with modified columns.

    Takes the same arguments as [`polars.DataFrame.with_columns`](https://docs.pola.rs/api/python/stable/reference/dataframe/api/polars.DataFrame.with_columns.html).

    !!! warning
        Only use this function if you know what you're doing. It is not recommended to manually modify the columns
        within a Pyoframe object.
    """
    return self.data.with_columns(*args, **kwargs)