sprinkling around the term "mutually comparable"

Author: Jolanrensen

core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/DataColumnType.kt

@@ -76,7 +76,7 @@ public fun AnyCol.isList(): Boolean = typeClass == List::class
 public fun AnyCol.isComparable(): Boolean = valuesAreComparable()
 
 /**
- * Returns `true` if [this] column is intra-comparable, i.e.
+ * Returns `true` if [this] column is intra-comparable (mutually comparable), i.e.,
  * its values can be compared with each other and thus ordered.
  *
  * If true, operations like [`min()`][AnyCol.min], [`max()`][AnyCol.max], [`median()`][AnyCol.median], etc.

core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/impl/TypeUtils.kt

@@ -696,7 +696,7 @@ internal fun Iterable<Any?>.types(): Set<KType> =
     }
 
 /**
- * Checks whether this KType adheres to `T : Comparable<T & Any>?`, aka, it is comparable with itself.
+ * Checks whether this KType adheres to `T : Comparable<T & Any>?`, aka, it is mutually comparable with itself.
  */
 internal fun KType.isIntraComparable(): Boolean =
     this.isSubtypeOf(

core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/impl/aggregation/getColumns.kt

@@ -18,7 +18,7 @@ internal inline fun <T> Aggregatable<T>.remainingColumns(
 ): ColumnsSelector<T, Any?> = remainingColumnsSelector().filter { predicate(it.data) }
 
 /**
- * Emulates selecting all columns whose values are comparable to each other.
+ * Emulates selecting all columns whose values are mutually comparable to each other.
  * These are columns of type `R` where `R : Comparable<R>`.
  *
  * There is no way to denote this generically in types, however,

core/src/test/kotlin/org/jetbrains/kotlinx/dataframe/samples/api/Analyze.kt

@@ -179,7 +179,7 @@ class Analyze : TestBase() {
     @TransformDataFrameExpressions
     fun minmaxModes() {
         // SampleStart
-        df.min() // min of values per every comparable column
+        df.min() // min of values for every comparable column with mutually comparable values
         df.min { age and weight } // min of all values in `age` and `weight`
         df.minFor(skipNaN = true) { age and name.firstName } // min of values per `age` and `firstName` separately
         df.minOf { (weight ?: 0) / age } // min of expression evaluated for every row
@@ -203,7 +203,7 @@ class Analyze : TestBase() {
     @TransformDataFrameExpressions
     fun medianModes() {
         // SampleStart
-        df.median() // median of values per every comparable column
+        df.median() // median of values for every column with mutually comparable values
         df.median { age and weight } // median of all values in `age` and `weight`
         df.medianFor(skipNaN = true) { age and name.firstName } // median of values per `age` and `firstName` separately
         df.medianOf { (weight ?: 0) / age } // median of expression evaluated for every row
@@ -227,7 +227,7 @@ class Analyze : TestBase() {
     @TransformDataFrameExpressions
     fun percentileModes() {
         // SampleStart
-        df.percentile(25.0) // 25th percentile of values per every comparable column
+        df.percentile(25.0) // 25th percentile of values for every column with mutually comparable values
         df.percentile(75.0) { age and weight } // 75th percentile of all values in `age` and `weight`
         df.percentileFor(50.0, skipNaN = true) { age and name.firstName } // 50th percentile of values per `age` and `firstName` separately
         df.percentileOf(75.0) { (weight ?: 0) / age } // 75th percentile of expression evaluated for every row
@@ -638,7 +638,7 @@ class Analyze : TestBase() {
     @TransformDataFrameExpressions
     fun groupByDirectAggregations_properties() {
         // SampleStart
-        df.groupBy { city }.max() // max for every comparable column
+        df.groupBy { city }.max() // max for every column with mutually comparable values
         df.groupBy { city }.mean() // mean for every numeric column
         df.groupBy { city }.max { age } // max age into column "age"
         df.groupBy { city }.sum("total weight") { weight } // sum of weights into column "total weight"
@@ -657,7 +657,7 @@ class Analyze : TestBase() {
     @TransformDataFrameExpressions
     fun groupByDirectAggregations_strings() {
         // SampleStart
-        df.groupBy("city").max() // max for every comparable column
+        df.groupBy("city").max() // max for every column with mutually comparable values
         df.groupBy("city").mean() // mean for every numeric column
         df.groupBy("city").max("age") // max age into column "age"
         df.groupBy("city").sum("weight", name = "total weight") // sum of weights into column "total weight"

docs/StardustDocs/topics/median.md

@@ -17,7 +17,7 @@ In these cases, the return type is always `Double?`.
 When the number of values is even, the median is the average of the two middle values.
 
 The operation is also available for self-comparable columns
-(so columns of type `T : Comparable<T>`, like `DateTime`, `String`, etc.)
+(so columns of type `T : Comparable<T>`, whose values are mutually comparable, like `DateTime`, `String`, etc.)
 In this case, the return type remains `T?`.
 When the number of values is even, the median is the low of the two middle values.
 NOTE: This logic also applies to other self-comparable `Number` types, like `BigDecimal`.

docs/StardustDocs/topics/minmax.md

@@ -9,7 +9,7 @@ The operations either throw an exception when the input is empty (after filterin
 or they return `null` when using the `-orNull` overloads.
 
 They are available for self-comparable columns
-(so columns of type `T : Comparable<T>`, like `DateTime`, `String`, `Int`, etc.)
+(so columns of type `T : Comparable<T>`, whose values are mutually comparable, like `DateTime`, `String`, etc.)
 which includes all primitive number columns, but no mix of different number types.
 
 All operations on `Double`/`Float` have the `skipNaN` option, which is

docs/StardustDocs/topics/percentile.md

@@ -21,7 +21,7 @@ The results of the operation on these types are interpolated using
 [Quantile Estimation Method](#quantile-estimation-methods) R8.
 
 The operation is also available for self-comparable columns
-(so columns of type `T : Comparable<T>`, like `DateTime`, `String`, etc.)
+(so columns of type `T : Comparable<T>`, whose values are mutually comparable, like `DateTime`, `String`, etc.)
 In this case, the return type remains `T?`.
 The index of the result of the operation on these types is rounded using
 [Quantile Estimation Method](#quantile-estimation-methods) R3.

docs/StardustDocs/topics/summaryStatistics.md

@@ -36,8 +36,8 @@ df.pivot { city }.groupBy { name.lastName }.std()
 [sum](sum.md), [mean](mean.md), [std](std.md) are available for (primitive) number columns of types 
 `Int`, `Double`, `Float`, `Long`, `Byte`, `Short`, and any mix of those.
 
-[min/max](minmax.md), [median](median.md), and [percentile](percentile.md) are available for self-comparable columns 
-(so columns of type `T : Comparable<T>`, like `DateTime`, `String`, `Int`, etc.)
+[min/max](minmax.md), [median](median.md), and [percentile](percentile.md) are available for self-comparable columns
+(so columns of type `T : Comparable<T>`, whose values are mutually comparable, like `DateTime`, `String`, etc.)
 which includes all primitive number columns, but no mix of different number types.
 
 In all cases, `null` values are ignored.