Github user aray commented on a diff in the pull request:
https://github.com/apache/spark/pull/18307#discussion_r125053122
--- Diff: sql/core/src/main/scala/org/apache/spark/sql/Dataset.scala ---
@@ -2205,37 +2205,170 @@ class Dataset[T] private[sql](
* // max 92.0 192.0
* }}}
*
+ * See also [[describeExtended]] and [[describeAdvanced]]
+ *
+ * @param cols Columns to compute statistics on.
+ *
* @group action
* @since 1.6.0
*/
@scala.annotation.varargs
- def describe(cols: String*): DataFrame = withPlan {
+ def describe(cols: String*): DataFrame =
+ describeAdvanced(Array("count", "mean", "stddev", "min", "max"), cols:
_*)
+
+ /**
+ * Computes statistics for numeric and string columns, including count,
mean, stddev, min,
+ * approximate quartiles, and max. If no columns are given, this
function computes
+ * statistics for all numerical or string columns.
+ *
+ * This function is meant for exploratory data analysis, as we make no
guarantee about the
+ * backward compatibility of the schema of the resulting Dataset. If you
want to
+ * programmatically compute summary statistics, use the `agg` function
instead.
+ *
+ * {{{
+ * ds.describeExtended("age", "height").show()
+ *
+ * // output:
+ * // summary age height
+ * // count 10.0 10.0
+ * // mean 53.3 178.05
+ * // stddev 11.6 15.7
+ * // min 18.0 163.0
+ * // 25% 24.0 176.0
+ * // 50% 24.0 176.0
+ * // 75% 32.0 180.0
+ * // max 92.0 192.0
+ * }}}
+ *
+ * To specify which statistics or percentiles are desired see
[[describeAdvanced]]
+ *
+ * @param cols Columns to compute statistics on.
+ *
+ * @group action
+ * @since 2.3.0
+ */
+ @scala.annotation.varargs
+ def describeExtended(cols: String*): DataFrame =
+ describeAdvanced(Array("count", "mean", "stddev", "min", "25%", "50%",
"75%", "max"), cols: _*)
+
+ /**
+ * Computes specified statistics for numeric and string columns.
Available statistics are:
+ *
+ * - count
+ * - mean
+ * - stddev
+ * - min
+ * - max
+ * - arbitrary approximate percentiles specifid as a percentage (eg, 75%)
+ *
+ * If no columns are given, this function computes statistics for all
numerical or string
+ * columns.
+ *
+ * This function is meant for exploratory data analysis, as we make no
guarantee about the
+ * backward compatibility of the schema of the resulting Dataset. If you
want to
+ * programmatically compute summary statistics, use the `agg` function
instead.
+ *
+ * {{{
+ * ds.describeAdvanced(Array("count", "min", "25%", "75%", "max"),
"age", "height").show()
+ *
+ * // output:
+ * // summary age height
+ * // count 10.0 10.0
+ * // min 18.0 163.0
+ * // 25% 24.0 176.0
+ * // 75% 32.0 180.0
+ * // max 92.0 192.0
+ * }}}
+ *
+ * @param statistics Statistics from above list to be computed.
+ * @param cols Columns to compute statistics on.
+ *
+ * @group action
+ * @since 2.3.0
+ */
+ @scala.annotation.varargs
+ def describeAdvanced(statistics: Array[String], cols: String*):
DataFrame = withPlan {
--- End diff --
Good point @rxin. With that in mind we can slim down the Scala API change
to just add one method taking varargs of statistics with default no arge
functionality of all statistics. As to the method name, although we can't use
"summarize" as pointed out by @felixcheung as its currently a synonym for
`agg`, we can use "**summary**". In SparkR `summary` is currently a synonym for
`describe` but without the ability to specify columns (see
https://github.com/apache/spark/blob/master/R/pkg/R/DataFrame.R#L2953).
Therefore we can repurpose it to work as desired without breaking the API. So
roughly:
- Scala/Java/Python: `df.summary()` and `df.summary("sum", "50%")`
- R: `summary(df)` and `summary(df, "sum", "50%")`
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at [email protected] or file a JIRA ticket
with INFRA.
---
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
