BaseOperableBlock

Bases: BaseBlock

Any object that can be converted into an expression.

Methods:

Name	Description
add_dim	Deprecated, use over instead.
drop_extras	Indicates that labels not present in the other expression should be discarded during addition, subtraction, or constraint creation.
drop_unmatched	Deprecated, use drop_extras instead.
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 addition, subtraction, or constraint creation.
keep_unmatched	Deprecated, use keep_extras instead.
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 addition, subtraction, or constraint creation.
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

def __init__(self, *args, **kwargs):
    self._extras_strategy = ExtrasStrategy.UNSET
    self._allowed_new_dims: list[str] = []
    super().__init__(*args, **kwargs)

add_dim(*dims: str)

Deprecated, use over instead.

Source code in pyoframe/_core.py

def add_dim(self, *dims: str):  # pragma: no cover
    """Deprecated, use [`over`][pyoframe.Expression.over] instead."""
    warnings.warn(
        "'add_dim' has been renamed to 'over'. Please use 'over' instead.",
        DeprecationWarning,
    )
    return self.over(*dims)

drop_extras()

Indicates that labels not present in the other expression should be discarded during addition, subtraction, or constraint creation.

Learn more about addition modifiers.

See Also

keep_extras.

Source code in pyoframe/_core.py

def drop_extras(self):
    """Indicates that labels not present in the other expression should be discarded during addition, subtraction, or constraint creation.

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

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

drop_unmatched()

Deprecated, use drop_extras instead.

Source code in pyoframe/_core.py

def drop_unmatched(self):  # pragma: no cover
    """Deprecated, use [`drop_extras`][pyoframe.Expression.drop_extras] instead."""
    warnings.warn(
        "'drop_unmatched' has been renamed to 'drop_extras'. Please use 'drop_extras' instead.",
        DeprecationWarning,
    )
    return self.drop_extras()

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

@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 addition, subtraction, or constraint creation.

Learn more about addition modifiers.

See Also

drop_extras.

Source code in pyoframe/_core.py

def keep_extras(self):
    """Indicates that labels not present in the other expression should be kept during addition, subtraction, or constraint creation.

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

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

keep_unmatched()

Deprecated, use keep_extras instead.

Source code in pyoframe/_core.py

def keep_unmatched(self):  # pragma: no cover
    """Deprecated, use [`keep_extras`][pyoframe.Expression.keep_extras] instead."""
    warnings.warn(
        "'keep_unmatched' has been renamed to 'keep_extras'. Please use 'keep_extras' instead.",
        DeprecationWarning,
    )
    return self.keep_extras()

map(*args, **kwargs)

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

Source code in pyoframe/_core.py

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

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 height=3 terms=3 type=linear>
┌─────────┬──────────────────┐
│ 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 terms=1 type=linear>
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

@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 height=3 terms=3 type=linear>
        ┌─────────┬──────────────────┐
        │ 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 terms=1 type=linear>
        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 addition, subtraction, or constraint creation.

This is the default behavior and, as such, this addition 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 addition modifiers.

See Also

keep_extras and drop_extras.

Source code in pyoframe/_core.py

def raise_extras(self):
    """Indicates that labels not present in the other expression should raise an error during addition, subtraction, or constraint creation.

    This is the default behavior and, as such, this addition 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/addition.md) about addition modifiers.

    See Also:
        [`keep_extras`][pyoframe.Expression.keep_extras] and [`drop_extras`][pyoframe.Expression.drop_extras].
    """
    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 height=12 terms=12 type=linear>
┌───────┬──────────┬──────────────────┐
│ 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

@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 height=12 terms=12 type=linear>
        ┌───────┬──────────┬──────────────────┐
        │ 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

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

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

@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

@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)

Comments