API Reference

Abs

Function to get the absolute value of a number.

Returns

Expr

Returns an expression object denoting the absolute value of the input data. The data type of the resulting expression is same as that of the input.

1from fennel.expr import col
2
3expr = col("x").abs()  # equivalent to col("x").num.abs()
4
5assert expr.typeof(schema={"x": int}) == int
6assert expr.typeof(schema={"x": Optional[int]}) == Optional[int]
7assert expr.typeof(schema={"x": float}) == float
8assert expr.typeof(schema={"x": Optional[float]}) == Optional[float]
9
10# can be evaluated with a dataframe
11df = pd.DataFrame({"x": pd.Series([1, -2, pd.NA], dtype=pd.Int64Dtype())})
12assert expr.eval(df, schema={"x": Optional[int]}).tolist() == [1, 2, pd.NA]
13
14with pytest.raises(ValueError):
15    expr.typeof(schema={"x": str})

Getting absolute value of numeric using abs

python

Errors

Invoking on a non-numeric type:

Error during typeof or eval if the input expression is not of type int, float, optional int or optional float.

Ceil

Function in num namespace to get the ceil of a number.

Returns

Expr

Returns an expression object denoting the ceil of the input data. The data type of the resulting expression is int if the input was int or float or Optional[int] when the input is Optional[int] or Optional[float].

1from fennel.expr import col
2
3expr = col("x").ceil()  # equivalent to col("x").num.ceil()
4assert expr.typeof(schema={"x": int}) == int
5assert expr.typeof(schema={"x": Optional[int]}) == Optional[int]
6assert expr.typeof(schema={"x": float}) == int
7assert expr.typeof(schema={"x": Optional[float]}) == Optional[int]
8
9# can be evaluated with a dataframe
10df = pd.DataFrame({"x": pd.Series([1.1, -2.3, None])})
11assert expr.eval(df, schema={"x": Optional[float]}).tolist() == [
12    2,
13    -2,
14    pd.NA,
15]
16
17with pytest.raises(ValueError):
18    expr.typeof(schema={"x": str})

Getting ceil value of a number

python

Errors

Invoking on a non-numeric type:

Error during typeof or eval if the input expression is not of type int, float, optional int or optional float.

Floor

Function in num namespace to get the floor of a number.

Returns

Expr

Returns an expression object denoting the floor of the input data. The data type of the resulting expression is int if the input was int or float or Optional[int] when the input is Optional[int] or Optional[float].

1from fennel.expr import col
2
3expr = col("x").floor()  # equivalent to col("x").num.floor()
4assert expr.typeof(schema={"x": int}) == int
5assert expr.typeof(schema={"x": Optional[int]}) == Optional[int]
6assert expr.typeof(schema={"x": float}) == int
7assert expr.typeof(schema={"x": Optional[float]}) == Optional[int]
8
9# can be evaluated with a dataframe
10df = pd.DataFrame({"x": pd.Series([1.1, -2.3, None])})
11assert expr.eval(df, schema={"x": Optional[float]}).tolist() == [
12    1,
13    -3,
14    pd.NA,
15]
16
17with pytest.raises(ValueError):
18    expr.typeof(schema={"x": str})

Getting floor value of a number

python

Errors

Invoking on a non-numeric type:

Error during typeof or eval if the input expression is not of type int, float, optional int or optional float.

Log

Function in num namespace to get the logarithm of a number.

Parameters

base:float

Default: 2.718281828459045

The base of the logarithm. By default, the base is set to e (Euler's number).

Returns

Expr

Returns an expression object denoting the logarithm of the input data. The data type of the resulting expression is float if the input was int or float and Optional[float] if the input was Optional[int] or Optional[float].

For negative numbers, the result is NaN (Not a Number).

1from fennel.expr import col
2
3expr = col("x").num.log(base=2.0)
4
5assert expr.typeof(schema={"x": int}) == float
6assert expr.typeof(schema={"x": Optional[int]}) == Optional[float]
7assert expr.typeof(schema={"x": float}) == float
8assert expr.typeof(schema={"x": Optional[float]}) == Optional[float]
9
10df = pd.DataFrame({"x": pd.Series([1.1, -2.3, 4.0])})
11assert expr.eval(df, schema={"x": Optional[float]}).tolist() == [
12    0.13750352374993502,
13    pd.NA,  # nan in pandas, log of negative number
14    2.0,
15]

Computing logarithm of a number

python

Errors

Invoking on a non-numeric type:

Error during typeof or eval if the input expression is not of type int, float, optional int or optional float.

Pow

Function in num namespace to exponentiate a number.

Parameters

exponent:Expr

The exponent to which the base is raised - expected to be a numeric expression.

Returns

Expr

Returns an expression object denoting the result of the exponentiation.

The base data type of the resulting expression is int if both the base and exponent are int, otherwise it is float.

If any of the base or exponent is Optional, the resulting expression is also Optional of the base data type.

1from fennel.expr import col, lit
2
3expr = col("x").num.pow(lit(2))
4
5assert expr.typeof(schema={"x": int}) == int
6assert expr.typeof(schema={"x": Optional[int]}) == Optional[int]
7assert expr.typeof(schema={"x": float}) == float
8assert expr.typeof(schema={"x": Optional[float]}) == Optional[float]
9
10df = pd.DataFrame({"x": pd.Series([1, 2, 4])})
11assert expr.eval(df, schema={"x": int}).tolist() == [
12    1,
13    4,
14    16,
15]
16
17# negative integer exponent raises error if base is also an integer
18with pytest.raises(Exception):
19    expr = lit(2).num.pow(lit(-2))
20    expr.eval(df, schema={"x": int})
21
22# but works if either base or exponent is a float
23expr = lit(2).num.pow(lit(-2.0))
24assert expr.eval(df, schema={"x": int}).tolist() == [
25    0.25,
26    0.25,
27    0.25,
28]

Exponentiating a number

python

Errors

Invoking on a non-numeric type:

Error during typeof or eval if the input expression is not of type int, float, optional int or optional float.

Exponentiation of negative integers:

A runtime error will be raised if the exponent is a negative integer and the base is also an integer.

In such cases, it's advised to convert either the base or the exponent to be a float.

Round

Function in num namespace to round a number.

Parameters

precision:int

Default: 0

The number of the decimal places to round the input to.

Returns

Expr

Returns an expression object denoting the rounded value of the input data. The data type of the resulting expression is int / Optional[int] if precision is set to 0 or float / Optional[int] for precisions > 0.

1from fennel.expr import col
2
3expr = col("x").ceil()  # equivalent to col("x").num.ceil()
4assert expr.typeof(schema={"x": int}) == int
5assert expr.typeof(schema={"x": Optional[int]}) == Optional[int]
6assert expr.typeof(schema={"x": float}) == int
7assert expr.typeof(schema={"x": Optional[float]}) == Optional[int]
8
9# can be evaluated with a dataframe
10df = pd.DataFrame({"x": pd.Series([1.1, -2.3, None])})
11assert expr.eval(df, schema={"x": Optional[float]}).tolist() == [
12    2,
13    -2,
14    pd.NA,
15]
16
17with pytest.raises(ValueError):
18    expr.typeof(schema={"x": str})

Rounding a number using Fennel expressions

python

Errors

Invoking on a non-numeric type:

Error during typeof or eval if the input expression is not of type int, float, optional int or optional float.

Invalid precision:

Precision must be a non-negative integer.

Sqrt

Function in num namespace to get the square root of a number.

Returns

Expr

Returns an expression object denoting the square root of the input data.

The data type of the resulting expression is float if the input is int or float and Optional[float] if the input is Optional[int] or Optional[float].

Note

The square root of a negative number is represented as NaN in the output.

1from fennel.expr import col
2
3expr = col("x").num.sqrt()
4
5assert expr.typeof(schema={"x": int}) == float
6assert expr.typeof(schema={"x": Optional[int]}) == Optional[float]
7assert expr.typeof(schema={"x": float}) == float
8assert expr.typeof(schema={"x": Optional[float]}) == Optional[float]
9
10df = pd.DataFrame({"x": pd.Series([1.1, -2.3, 4.0])})
11assert expr.eval(df, schema={"x": Optional[float]}).tolist() == [
12    1.0488088481701516,
13    pd.NA,  # this is nan in pandas, sqrt of negative number
14    2.0,
15]

Getting square root of a number

python

Errors

Invoking on a non-numeric type:

Error during typeof or eval if the input expression is not of type int, float, optional int or optional float.

To String

Function in num namespace to convert a number to a string.

Returns

Expr

Returns an expression object denoting the string value of the input data. The data type of the resulting expression is str (or Optional[str] if the input is an optional number).

1from fennel.expr import col
2
3expr = col("x").num.to_string()
4
5# type is str or optional str
6assert expr.typeof(schema={"x": int}) == str
7assert expr.typeof(schema={"x": Optional[int]}) == Optional[str]
8assert expr.typeof(schema={"x": float}) == str
9assert expr.typeof(schema={"x": Optional[float]}) == Optional[str]
10
11# can be evaluated with a dataframe
12df = pd.DataFrame({"x": pd.Series([1.1, -2.3, None])})
13assert expr.eval(df, schema={"x": Optional[float]}).tolist() == [
14    "1.1",
15    "-2.3",
16    pd.NA,
17]

Converting a number to a string using Fennel expressions

python

Errors

Invoking on a non-numeric type:

Error during typeof or eval if the input expression is not of type int, float, optional int or optional float.