This is an automated email from the ASF dual-hosted git repository.
yangjie01 pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/spark.git
The following commit(s) were added to refs/heads/master by this push:
new dceb8bdc72ef [SPARK-46767][PYTHON][DOCS] Refine docstring of
`abs/acos/acosh`
dceb8bdc72ef is described below
commit dceb8bdc72ef24ffa1eb5c1820e6350207f042f5
Author: yangjie01 <[email protected]>
AuthorDate: Sat Jan 20 17:39:01 2024 +0800
[SPARK-46767][PYTHON][DOCS] Refine docstring of `abs/acos/acosh`
### What changes were proposed in this pull request?
This pr refine docstring of `abs/acos/acosh` and add some new examples.
### Why are the changes needed?
To improve PySpark documentation
### Does this PR introduce _any_ user-facing change?
No
### How was this patch tested?
Pass Github Actions
### Was this patch authored or co-authored using generative AI tooling?
No
Closes #44794 from LuciferYang/math-functions-1.
Authored-by: yangjie01 <[email protected]>
Signed-off-by: yangjie01 <[email protected]>
---
python/pyspark/sql/functions/builtin.py | 169 ++++++++++++++++++++++++++------
1 file changed, 137 insertions(+), 32 deletions(-)
diff --git a/python/pyspark/sql/functions/builtin.py
b/python/pyspark/sql/functions/builtin.py
index 1f6d86de28dc..62400accba10 100644
--- a/python/pyspark/sql/functions/builtin.py
+++ b/python/pyspark/sql/functions/builtin.py
@@ -734,7 +734,7 @@ def try_sum(col: "ColumnOrName") -> Column:
@_try_remote_functions
def abs(col: "ColumnOrName") -> Column:
"""
- Computes the absolute value.
+ Mathematical Function: Computes the absolute value of the given column or
expression.
.. versionadded:: 1.3.0
@@ -744,22 +744,66 @@ def abs(col: "ColumnOrName") -> Column:
Parameters
----------
col : :class:`~pyspark.sql.Column` or str
- target column to compute on.
+ The target column or expression to compute the absolute value on.
Returns
-------
:class:`~pyspark.sql.Column`
- column for computed results.
+ A new column object representing the absolute value of the input.
Examples
--------
- >>> df = spark.range(1)
- >>> df.select(abs(lit(-1))).show()
- +-------+
- |abs(-1)|
- +-------+
- | 1|
- +-------+
+ Example 1: Compute the absolute value of a negative number
+
+ >>> from pyspark.sql import functions as sf
+ >>> df = spark.createDataFrame([(1, -1), (2, -2), (3, -3)], ["id",
"value"])
+ >>> df.select(sf.abs(df.value)).show()
+ +----------+
+ |abs(value)|
+ +----------+
+ | 1|
+ | 2|
+ | 3|
+ +----------+
+
+ Example 2: Compute the absolute value of an expression
+
+ >>> from pyspark.sql import functions as sf
+ >>> df = spark.createDataFrame([(1, 1), (2, -2), (3, 3)], ["id", "value"])
+ >>> df.select(sf.abs(df.id - df.value)).show()
+ +-----------------+
+ |abs((id - value))|
+ +-----------------+
+ | 0|
+ | 4|
+ | 0|
+ +-----------------+
+
+ Example 3: Compute the absolute value of a column with null values
+
+ >>> from pyspark.sql import functions as sf
+ >>> df = spark.createDataFrame([(1, None), (2, -2), (3, None)], ["id",
"value"])
+ >>> df.select(sf.abs(df.value)).show()
+ +----------+
+ |abs(value)|
+ +----------+
+ | NULL|
+ | 2|
+ | NULL|
+ +----------+
+
+ Example 4: Compute the absolute value of a column with double values
+
+ >>> from pyspark.sql import functions as sf
+ >>> df = spark.createDataFrame([(1, -1.5), (2, -2.5), (3, -3.5)], ["id",
"value"])
+ >>> df.select(sf.abs(df.value)).show()
+ +----------+
+ |abs(value)|
+ +----------+
+ | 1.5|
+ | 2.5|
+ | 3.5|
+ +----------+
"""
return _invoke_function_over_columns("abs", col)
@@ -1478,7 +1522,8 @@ def product(col: "ColumnOrName") -> Column:
@_try_remote_functions
def acos(col: "ColumnOrName") -> Column:
"""
- Computes inverse cosine of the input column.
+ Mathematical Function: Computes the inverse cosine (also known as
arccosine)
+ of the given column or expression.
.. versionadded:: 1.4.0
@@ -1488,23 +1533,54 @@ def acos(col: "ColumnOrName") -> Column:
Parameters
----------
col : :class:`~pyspark.sql.Column` or str
- target column to compute on.
+ The target column or expression to compute the inverse cosine on.
Returns
-------
:class:`~pyspark.sql.Column`
- inverse cosine of `col`, as if computed by `java.lang.Math.acos()`
+ A new column object representing the inverse cosine of the input.
Examples
--------
- >>> df = spark.range(1, 3)
- >>> df.select(acos(df.id)).show()
- +--------+
- |ACOS(id)|
- +--------+
- | 0.0|
- | NaN|
- +--------+
+ Example 1: Compute the inverse cosine of a column of numbers
+
+ >>> from pyspark.sql import functions as sf
+ >>> df = spark.createDataFrame([(-1.0,), (-0.5,), (0.0,), (0.5,), (1.0,)],
["value"])
+ >>> df.select("value", sf.acos("value")).show()
+ +-----+------------------+
+ |value| ACOS(value)|
+ +-----+------------------+
+ | -1.0| 3.141592653589...|
+ | -0.5|2.0943951023931...|
+ | 0.0|1.5707963267948...|
+ | 0.5|1.0471975511965...|
+ | 1.0| 0.0|
+ +-----+------------------+
+
+ Example 2: Compute the inverse cosine of a column with null values
+
+ >>> from pyspark.sql import functions as sf
+ >>> from pyspark.sql.types import StructType, StructField, IntegerType
+ >>> schema = StructType([StructField("value", IntegerType(), True)])
+ >>> df = spark.createDataFrame([(None,)], schema=schema)
+ >>> df.select(sf.acos(df.value)).show()
+ +-----------+
+ |ACOS(value)|
+ +-----------+
+ | NULL|
+ +-----------+
+
+ Example 3: Compute the inverse cosine of a column with values outside the
valid range
+
+ >>> from pyspark.sql import functions as sf
+ >>> df = spark.createDataFrame([(2,), (-2,)], ["value"])
+ >>> df.select(sf.acos(df.value)).show()
+ +-----------+
+ |ACOS(value)|
+ +-----------+
+ | NaN|
+ | NaN|
+ +-----------+
"""
return _invoke_function_over_columns("acos", col)
@@ -1512,7 +1588,8 @@ def acos(col: "ColumnOrName") -> Column:
@_try_remote_functions
def acosh(col: "ColumnOrName") -> Column:
"""
- Computes inverse hyperbolic cosine of the input column.
+ Mathematical Function: Computes the inverse hyperbolic cosine (also known
as arcosh)
+ of the given column or expression.
.. versionadded:: 3.1.0
@@ -1522,23 +1599,51 @@ def acosh(col: "ColumnOrName") -> Column:
Parameters
----------
col : :class:`~pyspark.sql.Column` or str
- target column to compute on.
+ The target column or expression to compute the inverse hyperbolic
cosine on.
Returns
-------
:class:`~pyspark.sql.Column`
- the column for computed results.
+ A new column object representing the inverse hyperbolic cosine of the
input.
Examples
--------
- >>> df = spark.range(2)
- >>> df.select(acosh(col("id"))).show()
- +---------+
- |ACOSH(id)|
- +---------+
- | NaN|
- | 0.0|
- +---------+
+ Example 1: Compute the inverse hyperbolic cosine of a column of numbers
+
+ >>> from pyspark.sql import functions as sf
+ >>> df = spark.createDataFrame([(1,), (2,)], ["value"])
+ >>> df.select("value", sf.acosh(df.value)).show()
+ +-----+------------------+
+ |value| ACOSH(value)|
+ +-----+------------------+
+ | 1| 0.0|
+ | 2|1.3169578969248...|
+ +-----+------------------+
+
+ Example 2: Compute the inverse hyperbolic cosine of a column with null
values
+
+ >>> from pyspark.sql import functions as sf
+ >>> from pyspark.sql.types import StructType, StructField, IntegerType
+ >>> schema = StructType([StructField("value", IntegerType(), True)])
+ >>> df = spark.createDataFrame([(None,)], schema=schema)
+ >>> df.select(sf.acosh(df.value)).show()
+ +------------+
+ |ACOSH(value)|
+ +------------+
+ | NULL|
+ +------------+
+
+ Example 3: Compute the inverse hyperbolic cosine of a column with values
less than 1
+
+ >>> from pyspark.sql import functions as sf
+ >>> df = spark.createDataFrame([(0.5,), (-0.5,)], ["value"])
+ >>> df.select(sf.acosh(df.value)).show()
+ +------------+
+ |ACOSH(value)|
+ +------------+
+ | NaN|
+ | NaN|
+ +------------+
"""
return _invoke_function_over_columns("acosh", col)
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
