ExcelFrame Expressions¶

Expr ¶

Bases: ABC

An abstract class that represents a column expression. It'll be evaluated across the row when it's applied to the ExcelFrame.

You can apply arithmetic operations to the expression directly.

Example

>>> import excelify as el
>>> df = el.ExcelFrame({"x": [1, 2, 3]})
>>> df = df.with_columns(
...     (el.col("x") * el.col("x")).alias("x_squared"),
...     (el.col("x") / 2).alias("x_div_2")
... )
>>> df
shape: (3, 3)
+---+-------+---------------+-------------+
|   | x (A) | x_squared (B) | x_div_2 (C) |
+---+-------+---------------+-------------+
| 1 |   1   |    A1 * A1    |   A1 / 2    |
| 2 |   2   |    A2 * A2    |   A2 / 2    |
| 3 |   3   |    A3 * A3    |   A3 / 2    |
+---+-------+---------------+-------------+

alias ¶

alias(name: str) -> Self

Name the column for the given expression.

Parameters:

Name	Type	Description	Default
`name`	`str`	Name of the column	required

Returns:

Type	Description
`Self`	self with name modified.

col ¶

col(col_name: str, *, from_: ExcelFrame | None = None, offset: int = 0)

`Expresses a reference to the cell in a specified column.

Example

>>> import excelify as el
>>> df = el.ExcelFrame({"x": [1, 2], "y": [3, 4]})
>>> df = df.with_columns((el.col("x") + el.col("y")).alias("z"))
>>> df
shape: (2, 3)
+---+-------+-------+---------+
|   | x (A) | y (B) |  z (C)  |
+---+-------+-------+---------+
| 1 |   1   |   3   | A1 + B1 |
| 2 |   2   |   4   | A2 + B2 |
+---+-------+-------+---------+

Parameters:

Name	Type	Description	Default
`col_name`	`str`	Name of the column	required
`from_`	`ExcelFrame \| None`	Which `ExcelFrame` to refer to. If it's None, it'll refer to the column of its own ExcelFrame.	`None`
`offset`	`int`	Relative row offset to refer to different rows.	`0`

map ¶

map(fn: Callable[[int], CellExpr | RawInput | Expr]) -> Map

Creates an expression based on the given function fn per row.

Example

>>> import excelify as el
>>> df = el.ExcelFrame.empty(columns=["x", "y"], height=2)
>>> df = df.with_columns(
...     el.map(lambda idx: idx + 1).alias("x"),
...     el.map(lambda idx: idx * 2).alias("y")
... )
>>> df
shape: (2, 2)
+---+-------+-------+
|   | x (A) | y (B) |
+---+-------+-------+
| 1 |   1   |   0   |
| 2 |   2   |   2   |
+---+-------+-------+

Arguments: fn: A callable that takes row index and returns an expression for the row.

Returns:

Type	Description
`Map`	A `Map` expression.

lit ¶

lit(value: RawInput | Sequence[RawInput | Expr | None]) -> Expr

Expresses a constant value across the rows.

Example

>>> import excelify as el
>>> df = el.ExcelFrame.empty(columns=["x", "y"], height=2)
>>> df = df.with_columns(
...     el.lit(0).alias("x"),
...     el.lit([1, 2]).alias("y")
... )
>>> df
shape: (2, 2)
+---+-------+-------+
|   | x (A) | y (B) |
+---+-------+-------+
| 1 |   0   |   1   |
| 2 |   0   |   2   |
+---+-------+-------+

Parameters:

Name	Type	Description	Default
`value`	`RawInput \| Sequence[RawInput \| Expr \| None]`	A constant value to put in the cell. If it's a scalar value, the value will be broadcasted.	required

sum ¶

sum(col_name: str, *, from_: ExcelFrame | None = None)

Create an expression that represents the sum of the column. The value will be broadcasted across the row.

Example

>>> import excelify as el
>>> df = el.ExcelFrame({"x": [1, 2, 3]})
>>> df = df.with_columns(el.sum("x").alias("x_sum"))
>>> df
shape: (3, 2)
+---+-------+------------+
|   | x (A) | x_sum (B)  |
+---+-------+------------+
| 1 |   1   | SUM(A1:A3) |
| 2 |   2   | SUM(A1:A3) |
| 3 |   3   | SUM(A1:A3) |
+---+-------+------------+
>>> df.evaluate()
shape: (3, 2)
+---+-------+-----------+
|   | x (A) | x_sum (B) |
+---+-------+-----------+
| 1 |   1   |     6     |
| 2 |   2   |     6     |
| 3 |   3   |     6     |
+---+-------+-----------+

Parameters:

Name	Type	Description	Default
`col_name`	`str`	Column name	required
`from_`	`ExcelFrame \| None`	An ExcelFrame to refer to. If None, it'll refer to itself.	`None`

average ¶

average(col_name: str, *, from_: ExcelFrame | None = None)

Create an expression that represents the average of the column. The value will be broadcasted across the row.

Example

>>> import excelify as el
>>> df = el.ExcelFrame({"x": [1, 2, 3]})
>>> df = df.with_columns(el.average("x").alias("x_sum"))
>>> df
shape: (3, 2)
+---+-------+----------------+
|   | x (A) |   x_sum (B)    |
+---+-------+----------------+
| 1 |   1   | AVERAGE(A1:A3) |
| 2 |   2   | AVERAGE(A1:A3) |
| 3 |   3   | AVERAGE(A1:A3) |
+---+-------+----------------+
>>> df.evaluate()
shape: (3, 2)
+---+-------+-----------+
|   | x (A) | x_sum (B) |
+---+-------+-----------+
| 1 |   1   |    2.0    |
| 2 |   2   |    2.0    |
| 3 |   3   |    2.0    |
+---+-------+-----------+

Parameters:

Name	Type	Description	Default
`col_name`	`str`	Column name	required
`from_`	`ExcelFrame \| None`	An ExcelFrame to refer to. If None, it'll refer to itself.	`None`