Updated website docs, added KDocs and tests for valueCounts - #2031
Updated website docs, added KDocs and tests for valueCounts#2031Allex-Nik wants to merge 3 commits into
valueCounts#2031Conversation
f718b42 to
6fe4698
Compare
6fe4698 to
bb39a6b
Compare
| * Otherwise, the counted values keep the order of their first occurrence. | ||
| * @param [ascending\] The sorting direction. If `false` (default), the most frequent values come first. | ||
| * Only used when [sort\] is `true`. | ||
| * @param [dropNA\] If `true` (default), [`NA`][NA] values (`null`s and `NaN`s) are not counted |
There was a problem hiding this comment.
you can use {@include [NALink]}
There was a problem hiding this comment.
"[NA][NA]" is resolved to the same internal typealias NA = Nothing with its docs, I haven't seen any difference :)
Is using {@include [NALink]} better?
There was a problem hiding this comment.
it indeed resolves the same :) It's just a reusable link. If we ever decide to change the name, the links that are reused will change too
| * and a row is not counted at all if any of its selected values is [`NA`][NA]. | ||
| * | ||
| * See also: | ||
| * - [valueCounts][DataColumn.valueCounts] — counts of unique values in a single [DataColumn]. |
There was a problem hiding this comment.
not 100% whether we should already put the aliases in backticks, but I can do that in my PR if this one is merged first :)
There was a problem hiding this comment.
I've added the backticks to the aliases :)
| * | ||
| * The resulting [DataFrame] contains: | ||
| * - the column with the distinct values of the original [DataColumn] | ||
| * - a new [Int] column ([resultColumn]) with the number of occurrences of each value. |
There was a problem hiding this comment.
I would rewrite this part about "resultColumn" to say that it is named "count" by default unless this name is overridden by resultColumn. Same in CommonValueCountsDocs
There was a problem hiding this comment.
come to think of it... if resultColumn is supplied, the cast to DataFrame<ValueCount> is broken... Maybe it makes sense to add an overload without resultColumn that returns DataFrame<ValueCount> and one with resultColumn that simply returns AnyFrame :) we could make a separate issue for it... but it's a quick fix imo, wdyt?
There was a problem hiding this comment.
We can do that. It also should not break the DataFrame IDEA plugin as far as I see. The only thing that bothers me is that providing resultColumn is not the only way to make the name of the column with counts not "count": if the name of the receiver is the same as the name of the column with counts (so the new column becomes count1), the cast will also break, and another overload will not fix it, right? It's a rare case though
There was a problem hiding this comment.
Damn, you're right. No, only the compiler plugin can fix that :)
There was a problem hiding this comment.
It seems compiler plugin support is missing for both DataColumn<T>.valueCounts and DataFrame<T>.valueCounts(vararg columns: String...)
| * ``` | ||
| * | ||
| * @include [ValueCountsParams] | ||
| * @param [columns] The [ColumnsSelector] used to select the columns whose distinct value combinations |
There was a problem hiding this comment.
'optional [ColumnsSelector]'. I'd repeat here the "if null or not supplied, all columns are selected" statement :)
| * ``` | ||
| * | ||
| * @include [ValueCountsParams] | ||
| * @param [columns] The names of the columns whose distinct value combinations are counted. |
There was a problem hiding this comment.
also optional. If unsupplied, all columns will be selected (yes, it will resolve to the other overload, but to the user will not notice this difference)
There was a problem hiding this comment.
also, this param should be the first :) above ValueCountsParams
| * `dropNA: Boolean = true` — doesn't include counts of [`NA`](nanAndNa.md) values | ||
| * `resultColumn: String = "count"` — name of the column with counts | ||
| * `columns = all` — columns to use when counting unique combinations | ||
|
|
There was a problem hiding this comment.
I'd put a small introduction here. Something like "For example:"
| df | ||
| // SampleEnd | ||
| .format().perRowCol { row, _ -> | ||
| if (row.name == "Alice" && row.age == 15) background(aliceColor) and textColor(black) else null |
There was a problem hiding this comment.
I wonder if it makes sense to give the Alice, null row a different color to annotate it's being considered too, but dropNA makes it be skipped. (The text could be stricken through maybe? Or maybe not since it's used in the second example, let's see what looks best :) )
| df.valueCounts(dropNA = false) | ||
| // SampleEnd | ||
| .format().perRowCol { row, _ -> | ||
| if (row.name == "Alice" && row.age == null) background(aliceColor) and textColor(black) else null |
There was a problem hiding this comment.
Ah yes and then here the Alice, 15 row could be aliceColor and the Alice, null row could be the same color as Alice, null above :)
| private typealias ValueCountsParams = Nothing | ||
|
|
||
| /** | ||
| * Returns a [DataFrame] containing counts of unique rows (or combinations of selected values) in this [DataFrame]. |
| * | ||
| * All summary statistics: {@include [DocumentationUrls.Statistics]} | ||
| * | ||
| * ### This ValueCounts Overload |
There was a problem hiding this comment.
*Value Counts (like a title) or *valueCounts referring to the operation name, the name of the function
2 participants
Fixes #1992
Helps #898