程序包 org.hipparchus.stat.descriptive.rank

类 Percentile

java.lang.Object
org.hipparchus.stat.descriptive.AbstractUnivariateStatistic
org.hipparchus.stat.descriptive.rank.Percentile
所有已实现的接口:
Serializable, UnivariateStatistic, MathArrays.Function
public class Percentile extends AbstractUnivariateStatistic implements Serializable
提供百分位数计算。

根据样本数据，有几种常用的估算百分位数（又称分位数）的方法。对于大样本，不同方法的结果非常接近，但是当样本量较小时，不同方法会给出显著不同的结果。这里实现的算法如下：

  1. 设n为（排序后的）数组的长度，0 < p <= 100为所需的百分位数。
  2. 如果n = 1，则返回唯一的数组元素（不考虑p的值）；否则
  3. 计算估算的百分位位置 pos = p * (n + 1) / 100以及d为pos与floor(pos)之间的差值（即pos的小数部分）。
  4. 如果pos < 1，则返回数组中最小的元素。
  5. 否则，如果pos >= n，则返回数组中最大的元素。
  6. 否则，让lower为数组中位置为floor(pos)的元素，让upper为数组中的下一个元素。返回lower + d * (upper - lower)

为了计算百分位数，数据必须至少部分有序。输入数组将被复制并使用排序定义进行递归分区。由Arrays.sort(double[])使用的排序是由Double.compareTo(Double)确定的排序。此排序使得Double.NaN大于任何其他值（包括Double.POSITIVE_INFINITY）。因此，例如，{0, 1, 2, 3, 4, Double.NaN}的中位数（第50百分位数）计算结果为2.5。

由于百分位数估算通常涉及数组元素之间的插值，包含NaN或无限值的数组通常会导致返回NaN或无限值。

此外，为了包含在分位数页面（维基百科）中提到的不同估算类型，使用了一种特定于类型的NaN处理策略，以与从流行工具（如R（R1-R9）、Excel（R7））观察到的结果密切匹配。

百分位数仅使用选择而不是完全排序，并在各种evaluate方法调用之间缓存选择算法状态。这极大地提高了效率，无论是对单个百分位数还是多个百分位数的计算。为了在基于相同数据计算多个百分位数时最大化性能，用户应该使用evaluate(double[], double)或setData(double[])方法之一设置数据数组，然后仅使用提供的百分位数调用evaluate(double)。

请注意，此实现未同步。如果多个线程同时访问此类的实例，并且至少有一个线程调用了increment()或clear()方法，则必须在外部进行同步。

另请参阅:

  • 构造器详细资料

  • 方法详细资料

    • setData

      public void setData(double[] values)
      设置数据数组。

      存储的值是参数数组的副本，而不是数组本身。

      覆盖:
      setData 在类中 AbstractUnivariateStatistic
      参数:
      values - 要存储的数据数组（可以为null以删除存储的数据）
      另请参阅:

    • setData

      public void setData(double[] values, int begin, int length) throws MathIllegalArgumentException
      设置数据数组。输入数组将被复制，而不是引用。
      覆盖:
      setData 在类中 AbstractUnivariateStatistic
      参数:
      values - 要存储的数据数组
      begin - 要包含的第一个元素的索引
      length - 要包含的元素数量
      抛出:
      MathIllegalArgumentException - 如果values为null或索引无效
      另请参阅:

    • evaluate

      public double evaluate(double p) throws MathIllegalArgumentException
      返回对存储数据计算统计量的结果。

      存储的数组是之前调用setData(double[])设置的数组。

      参数:
      p - 要计算的百分位数值
      返回:
      应用于存储数据的统计量的值
      抛出:
      MathIllegalArgumentException - 如果p不是有效的分位数值（p必须大于0且不大于100）

    • evaluate

      public double evaluate(double[] values, int start, int length) throws MathIllegalArgumentException
      返回values数组中指定值的quantile百分位数的估计值。

      估计的分位数由quantile属性确定。

      • 如果length = 0，则返回Double.NaN
      • 如果length = 1，则返回values[begin]（对于任何quantile值）
      • 如果values为null，或start或length无效，则抛出MathIllegalArgumentException

      有关使用的百分位数估计算法，请参见Percentile。

      指定者:
      evaluate 在接口中 MathArrays.Function
      指定者:
      evaluate 在接口中 UnivariateStatistic
      指定者:
      evaluate 在类中 AbstractUnivariateStatistic
      参数:
      values - 输入数组
      start - 要包含的第一个数组元素的索引
      length - 要包含的元素数量
      返回:
      分位数值
      抛出:
      MathIllegalArgumentException - 如果参数无效

    • evaluate

      public double evaluate(double[] values, double p) throws MathIllegalArgumentException
      返回p值的估计值，该值是values数组中的p百分位数。
      • 如果values的长度为0，则返回Double.NaN
      • 如果values的长度为1，则返回values[0]（对于任何p值）
      • 如果values为null或p不是有效的分位数值（p必须大于0且不大于100），则抛出MathIllegalArgumentException

      默认实现以自然方式委托给evaluate(double[], int, int, double)。

      参数:
      values - 输入值数组
      p - 要计算的百分位数值
      返回:
      百分位数值，如果数组为空则返回Double.NaN
      抛出:
      MathIllegalArgumentException - 如果values为null或p无效

    • evaluate

      public double evaluate(double[] values, int begin, int length, double p) throws MathIllegalArgumentException
      返回p值的估计值，该值是从数组中的第begin位置（基于0）开始并包括length个值的p百分位数。

      调用此方法不会修改此统计量的内部quantile状态。

      • 如果length = 0，则返回Double.NaN
      • 如果length = 1，则返回values[begin]（对于任何p值）
      • 如果values为null，begin或length无效，或p不是有效的分位数值（p必须大于0且不大于100），则抛出MathIllegalArgumentException

      有关使用的百分位数估计算法，请参见Percentile。

      参数:
      values - 输入值数组
      begin - 要包含在计算中的第一个（基于0）元素的索引
      length - 要包含的数组元素数量
      p - 要计算的百分位数
      返回:
      百分位数值
      抛出:
      MathIllegalArgumentException - 如果参数无效或输入数组为null

    • getQuantile

      public double getQuantile()
      返回分位数字段的值（在调用evaluate()时不带分位数参数时确定计算的是哪个百分位数）。
      返回:
      在构造时设置的分位数或setQuantile(double)

    • setQuantile

      public void setQuantile(double p) throws MathIllegalArgumentException
      设置分位数字段的值（在调用evaluate()时不带分位数参数时确定计算的是哪个百分位数）。
      参数:
      p - 0 < p <= 100的值
      抛出:
      MathIllegalArgumentException - 如果p不大于0且不大于100

    • copy

      public Percentile copy()
      返回具有相同内部状态的统计量的副本。
      指定者:
      copy 在接口中 UnivariateStatistic
      指定者:
      copy 在类中 AbstractUnivariateStatistic
      返回:
      统计量的副本

    • getWorkArray

      protected double[] getWorkArray(double[] values, int begin, int length)
      获取用于操作的工作数组。如果存在先前的storedData，则使用它，否则对NaN进行检查并复制由begin和length参数定义的数组的子集。将使用设置的nanStrategy来在返回结果数组之前保留/删除/替换任何NaN。
      参数:
      values - 数组中的数字
      begin - 开始读取数组的索引
      length - 从开始索引开始读取的数组长度
      返回:
      从值中切片的工作数组，范围为[begin, begin+length)
      抛出:
      MathIllegalArgumentException - 如果值或索引无效

    • getEstimationType

      public Percentile.EstimationType getEstimationType()
      获取用于计算的估计类型。
      返回:
      设置的estimationType

    • withEstimationType

      public Percentile withEstimationType(Percentile.EstimationType newEstimationType)
      构建一个类似于当前实例的新实例，除了估计类型。

      此方法旨在作为流畅构建器模式的一部分使用。应按以下方式执行构建精细调整实例：

         Percentile customized = new Percentile(quantile).
                           withEstimationType(estimationType).
                           withNaNStrategy(nanStrategy).
                           withKthSelector(kthSelector);

      如果省略任何withXxx方法，则将使用相应自定义参数的默认值。

      参数:
      newEstimationType - 新实例的估计类型
      返回:
      一个新实例，带有更改后的估计类型
      抛出:
      NullArgumentException - 当newEstimationType为null时

    • getNaNStrategy

      public NaNStrategy getNaNStrategy()
      获取用于计算的NaN处理策略。
      返回:
      在构造过程中设置的NaN处理策略

    • withNaNStrategy

      public Percentile withNaNStrategy(NaNStrategy newNaNStrategy)
      构建一个类似于当前实例的新实例，除了NaN处理策略。

      此方法旨在作为流畅构建器模式的一部分使用。应按以下方式执行构建精细调整实例：

         Percentile customized = new Percentile(quantile).
                           withEstimationType(estimationType).
                           withNaNStrategy(nanStrategy).
                           withKthSelector(kthSelector);

      如果省略任何withXxx方法，则将使用相应自定义参数的默认值。

      参数:
      newNaNStrategy - 新实例的NaN策略
      返回:
      一个新实例，带有更改后的NaN处理策略
      抛出:
      NullArgumentException - 当newNaNStrategy为null时

    • getKthSelector

      public KthSelector getKthSelector()
      获取用于计算的kthSelector。
      返回:
      设置的kthSelector

    • getPivotingStrategy

      public PivotingStrategy getPivotingStrategy()
      获取在KthSelector中用于计算的枢轴策略。
      返回:
      设置的枢轴策略

    • withKthSelector

      public Percentile withKthSelector(KthSelector newKthSelector)
      构建一个类似于当前实例的新实例，除了专门设置的kthSelector实例。

      此方法旨在作为流畅构建器模式的一部分使用。应按以下方式执行构建精细调整实例：

         Percentile customized = new Percentile(quantile).
                           withEstimationType(estimationType).
                           withNaNStrategy(nanStrategy).
                           withKthSelector(newKthSelector);

      如果省略任何withXxx方法，则将使用相应自定义参数的默认值。

      参数:
      newKthSelector - 新实例的KthSelector
      返回:
      一个新实例，带有更改后的KthSelector
      抛出:
      NullArgumentException - 当newKthSelector为null时