You are viewing a plain text version of this content. The canonical link for it is here.
Posted to reviews@spark.apache.org by "LuciferYang (via GitHub)" <gi...@apache.org> on 2024/01/19 05:37:51 UTC
[PR] [SPARK-46767][PYTHON][DOCS] Refine docstring of `abs/acos/acosh` [spark]
LuciferYang opened a new pull request, #44794:
URL: https://github.com/apache/spark/pull/44794
### 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
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For additional commands, e-mail: reviews-help@spark.apache.org
Re: [PR] [SPARK-46767][PYTHON][DOCS] Refine docstring of `abs/acos/acosh` [spark]
Posted by "LuciferYang (via GitHub)" <gi...@apache.org>.
LuciferYang closed pull request #44794: [SPARK-46767][PYTHON][DOCS] Refine docstring of `abs/acos/acosh`
URL: https://github.com/apache/spark/pull/44794
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For additional commands, e-mail: reviews-help@spark.apache.org
Re: [PR] [SPARK-46767][PYTHON][DOCS] Refine docstring of `abs/acos/acosh` [spark]
Posted by "zhengruifeng (via GitHub)" <gi...@apache.org>.
zhengruifeng commented on code in PR #44794:
URL: https://github.com/apache/spark/pull/44794#discussion_r1458881539
##########
python/pyspark/sql/functions/builtin.py:
##########
@@ -1488,31 +1533,66 @@ 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.substring(sf.acos("value"), 0, 15).alias("ACOS(value)"),
+ ... sf.substring(sf.degrees(sf.acos("value")), 0, 5).alias("DEGREES(ACOS(value))")
+ ... ).show()
+ +-----+---------------+--------------------+
+ |value| ACOS(value)|DEGREES(ACOS(value))|
+ +-----+---------------+--------------------+
+ | -1.0|3.1415926535897| 180.0|
+ | -0.5|2.0943951023931| 120.0|
+ | 0.0|1.5707963267948| 90.0|
Review Comment:
```suggestion
| 0.0|1.5707963267...| 90.0|
```
and other similar places.
To make the result more stable: e.g. the doctest won't fail when we change jdk version/python version/underlying engineer/etc.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For additional commands, e-mail: reviews-help@spark.apache.org
Re: [PR] [SPARK-46767][PYTHON][DOCS] Refine docstring of `abs/acos/acosh` [spark]
Posted by "LuciferYang (via GitHub)" <gi...@apache.org>.
LuciferYang commented on code in PR #44794:
URL: https://github.com/apache/spark/pull/44794#discussion_r1458475678
##########
python/pyspark/sql/functions/builtin.py:
##########
@@ -1488,31 +1533,75 @@ 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.5), (2, -0.5), (3, 1.0)], ["id", "value"])
+ >>> df.select(sf.acos(df.value)).show()
+ +------------------+
+ | ACOS(value)|
+ +------------------+
+ |1.0471975511965979|
Review Comment:
OK
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For additional commands, e-mail: reviews-help@spark.apache.org
Re: [PR] [SPARK-46767][PYTHON][DOCS] Refine docstring of `abs/acos/acosh` [spark]
Posted by "zhengruifeng (via GitHub)" <gi...@apache.org>.
zhengruifeng commented on code in PR #44794:
URL: https://github.com/apache/spark/pull/44794#discussion_r1458893184
##########
python/pyspark/sql/functions/builtin.py:
##########
@@ -1488,31 +1533,66 @@ 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.substring(sf.acos("value"), 0, 15).alias("ACOS(value)"),
+ ... sf.substring(sf.degrees(sf.acos("value")), 0, 5).alias("DEGREES(ACOS(value))")
Review Comment:
or let's simply remove the degrees column
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For additional commands, e-mail: reviews-help@spark.apache.org
Re: [PR] [SPARK-46767][PYTHON][DOCS] Refine docstring of `abs/acos/acosh` [spark]
Posted by "zhengruifeng (via GitHub)" <gi...@apache.org>.
zhengruifeng commented on code in PR #44794:
URL: https://github.com/apache/spark/pull/44794#discussion_r1458467248
##########
python/pyspark/sql/functions/builtin.py:
##########
@@ -1488,31 +1533,75 @@ 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.5), (2, -0.5), (3, 1.0)], ["id", "value"])
+ >>> df.select(sf.acos(df.value)).show()
+ +------------------+
+ | ACOS(value)|
+ +------------------+
+ |1.0471975511965979|
Review Comment:
for trigonometric functions' example, what about making them use or return some special values? e.g.
```
In [26]: df = spark.createDataFrame([(-1.0, 0.5), (-0.5, -0.5), (0.0, 1.0), (0.5, 0.0), (1.0, 1.0)], ["v1", "v2"])
In [27]: df.select("v1", sf.acos("v1"), sf.degrees(sf.acos("v1"))).show()
+----+------------------+------------------+
| v1| ACOS(v1)| DEGREES(ACOS(v1))|
+----+------------------+------------------+
|-1.0| 3.141592653589...| 180.0|
|-0.5|2.0943951023931...|120.00000000000...|
| 0.0|1.5707963267948...| 90.0|
| 0.5|1.0471975511965...| 60.00000000000...|
| 1.0| 0.0| 0.0|
+----+------------------+------------------+
```
and we'd better use `...` at the last of numbers, since the computation may vary slightly on different envs.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For additional commands, e-mail: reviews-help@spark.apache.org
Re: [PR] [SPARK-46767][PYTHON][DOCS] Refine docstring of `abs/acos/acosh` [spark]
Posted by "zhengruifeng (via GitHub)" <gi...@apache.org>.
zhengruifeng commented on code in PR #44794:
URL: https://github.com/apache/spark/pull/44794#discussion_r1458879184
##########
python/pyspark/sql/functions/builtin.py:
##########
@@ -1488,31 +1533,66 @@ 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.substring(sf.acos("value"), 0, 15).alias("ACOS(value)"),
+ ... sf.substring(sf.degrees(sf.acos("value")), 0, 5).alias("DEGREES(ACOS(value))")
Review Comment:
thanks, this looks pretty good.
btw, I guess we can use `sf.round` to make the result more stable.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For additional commands, e-mail: reviews-help@spark.apache.org
Re: [PR] [SPARK-46767][PYTHON][DOCS] Refine docstring of `abs/acos/acosh` [spark]
Posted by "zhengruifeng (via GitHub)" <gi...@apache.org>.
zhengruifeng commented on code in PR #44794:
URL: https://github.com/apache/spark/pull/44794#discussion_r1458467248
##########
python/pyspark/sql/functions/builtin.py:
##########
@@ -1488,31 +1533,75 @@ 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.5), (2, -0.5), (3, 1.0)], ["id", "value"])
+ >>> df.select(sf.acos(df.value)).show()
+ +------------------+
+ | ACOS(value)|
+ +------------------+
+ |1.0471975511965979|
Review Comment:
for trigonometric functions' example, what about making them use or return some special values? e.g.
```
In [26]: df = spark.createDataFrame([(-1.0, 0.5), (-0.5, -0.5), (0.0, 1.0), (0.5, 0.0), (1.0, 1.0)], ["v1", "v2"])
In [27]: df.select("v1", sf.acos("v1"), sf.degrees(sf.acos("v1"))).show()
+----+------------------+------------------+
| v1| ACOS(v1)| DEGREES(ACOS(v1))|
+----+------------------+------------------+
|-1.0| 3.141592653589...| 180.0|
|-0.5|2.0943951023931...|120.00000000000...|
| 0.0|1.5707963267948...| 90.0|
| 0.5|1.0471975511965...| 60.00000000000...|
| 1.0| 0.0| 0.0|
+----+------------------+------------------+
```
and we'd better use `...` at the last of numbers, since the computation result may vary slightly on different envs.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For additional commands, e-mail: reviews-help@spark.apache.org
Re: [PR] [SPARK-46767][PYTHON][DOCS] Refine docstring of `abs/acos/acosh` [spark]
Posted by "LuciferYang (via GitHub)" <gi...@apache.org>.
LuciferYang commented on PR #44794:
URL: https://github.com/apache/spark/pull/44794#issuecomment-1902038392
Merged into master. Thanks @zhengruifeng
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For additional commands, e-mail: reviews-help@spark.apache.org