From 52dae44e9c0af91f5d2adf9bead37eec4a0c4cbf Mon Sep 17 00:00:00 2001 From: Jimmy M Andersson Date: Sun, 24 May 2026 11:25:46 +0200 Subject: [PATCH] docs: prepare documentation and README for 0.8.0 release - Bump SPM install example to 0.8.0 in README - Remove runtime complexity estimates from all doc comments - Rename 'Combinatorial Extensions' catalog page to 'Mathematical Functions' and add missing beta and gamma function entries - Fix 'Centeral Tendency' filename typo - Remove empty topic sections from StatKit.md and Distributions.md - Move FiskDistribution to a dedicated Type Aliases group - Expand RankingStrategy case doc comments with examples - Add missing doc comment to NormalDistribution.init(mean:standardDeviation:) - Add deprecation note to GammaDistribution.init(alpha:beta:) --- README.md | 2 +- .../Association/Correlation.swift | 3 --- .../Central Tendency/Averages.swift | 5 ---- .../Central Tendency/MeanStrategy.swift | 1 - .../Central Tendency/MedianStrategy.swift | 2 -- .../Dispersion/Range.swift | 1 - .../Dispersion/Variability.swift | 5 ---- .../Continuous/GammaDistribution.swift | 2 ++ .../Continuous/NormalDistribution.swift | 3 +++ .../Ranking/Ranking.swift | 2 -- .../Ranking/RankingStrategy.swift | 26 +++++++++++++++---- .../Summation/Summation.swift | 2 -- ...nteral Tendency.md => Central Tendency.md} | 0 .../StatKit.docc/Combinatorial Extensions.md | 14 ---------- Sources/StatKit/StatKit.docc/Distributions.md | 7 ++--- .../StatKit.docc/Mathematical Functions.md | 24 +++++++++++++++++ Sources/StatKit/StatKit.docc/Ranking.md | 2 +- Sources/StatKit/StatKit.docc/StatKit.md | 7 ++--- Sources/StatKit/StatKit.docc/Summation.md | 8 +++--- 19 files changed, 59 insertions(+), 57 deletions(-) rename Sources/StatKit/StatKit.docc/{Centeral Tendency.md => Central Tendency.md} (100%) delete mode 100644 Sources/StatKit/StatKit.docc/Combinatorial Extensions.md create mode 100644 Sources/StatKit/StatKit.docc/Mathematical Functions.md diff --git a/README.md b/README.md index 018d329..461e8ed 100644 --- a/README.md +++ b/README.md @@ -130,7 +130,7 @@ To install StatKit using the [Swift Package Manager](https://swift.org/package-m let package = Package( ... dependencies: [ - .package(url: "https://github.com/JimmyMAndersson/StatKit.git", from: "0.6.0") + .package(url: "https://github.com/JimmyMAndersson/StatKit.git", from: "0.8.0") ], ... ) diff --git a/Sources/StatKit/Descriptive Statistics/Association/Correlation.swift b/Sources/StatKit/Descriptive Statistics/Association/Correlation.swift index 9e7e9be..b9243e0 100644 --- a/Sources/StatKit/Descriptive Statistics/Association/Correlation.swift +++ b/Sources/StatKit/Descriptive Statistics/Association/Correlation.swift @@ -8,7 +8,6 @@ public extension Collection { /// /// Since there is no notion of correlation in collections with less than two elements, /// this method returns NaN if the array count is less than two. - /// The time complexity of this method is O(n). @inlinable func pearsonR( of X: KeyPath, @@ -52,7 +51,6 @@ public extension Collection { /// Since there is no notion of correlation in collections with less than two /// elements or when one of the variables are constant, /// this method returns NaN if the array count is less than two. - /// The time complexity of this method is O(n). @inlinable func spearmanR( of X: KeyPath, @@ -119,7 +117,6 @@ public extension Collection { /// /// Since there is no notion of correlation in collections with less than two elements, /// this method returns NaN if the array count is less than two. - /// The time complexity of this method is O(n). func kendallTau( of X: KeyPath, and Y: KeyPath, diff --git a/Sources/StatKit/Descriptive Statistics/Central Tendency/Averages.swift b/Sources/StatKit/Descriptive Statistics/Central Tendency/Averages.swift index 7090739..99fe797 100644 --- a/Sources/StatKit/Descriptive Statistics/Central Tendency/Averages.swift +++ b/Sources/StatKit/Descriptive Statistics/Central Tendency/Averages.swift @@ -5,7 +5,6 @@ public extension Collection { /// - returns: The mean of all items. /// /// Since the arithmetic mean has no meaning on an empty set, this method returns a NaN if the collection is empty. - /// The time complexity of this method is O(n). @inlinable func mean( variable: KeyPath, @@ -24,8 +23,6 @@ public extension Collection { /// /// - important: This method has undefined behavior on collections containing elements that are incomparable. /// For example, an array containing NaN's will produce unpredictable results. - /// - /// - complexity: O(n log n), where n is the length of the collection. @inlinable func median( variable: KeyPath, @@ -49,8 +46,6 @@ public extension Collection { /// /// - important: This method has undefined behavior on collections containing elements that are incomparable. /// For example, an array containing NaN's will produce unpredictable results. - /// - /// - complexity: O(n), where n is the length of the collection. @inlinable func mode( variable: KeyPath diff --git a/Sources/StatKit/Descriptive Statistics/Central Tendency/MeanStrategy.swift b/Sources/StatKit/Descriptive Statistics/Central Tendency/MeanStrategy.swift index d24236c..80f9ed9 100644 --- a/Sources/StatKit/Descriptive Statistics/Central Tendency/MeanStrategy.swift +++ b/Sources/StatKit/Descriptive Statistics/Central Tendency/MeanStrategy.swift @@ -17,7 +17,6 @@ extension MeanStrategy { /// - parameter variable: The random variable for which to calculate the mean. /// - parameter collection: The collection of values. /// - returns: The specified mean value. - /// The time complexity of this method is O(n). @usableFromInline internal func compute( for variable: KeyPath, diff --git a/Sources/StatKit/Descriptive Statistics/Central Tendency/MedianStrategy.swift b/Sources/StatKit/Descriptive Statistics/Central Tendency/MedianStrategy.swift index 8ef6598..497e4cd 100644 --- a/Sources/StatKit/Descriptive Statistics/Central Tendency/MedianStrategy.swift +++ b/Sources/StatKit/Descriptive Statistics/Central Tendency/MedianStrategy.swift @@ -13,8 +13,6 @@ extension MedianStrategy { /// - parameter variable: The random variable for which to calculate the mean. /// - parameter collection: The collection of values. /// - returns: The specified mean value. - /// - /// - complexity: O(n log n), where n is the length of the collection. @usableFromInline internal func compute( for variable: KeyPath, diff --git a/Sources/StatKit/Descriptive Statistics/Dispersion/Range.swift b/Sources/StatKit/Descriptive Statistics/Dispersion/Range.swift index b58c463..07c591f 100644 --- a/Sources/StatKit/Descriptive Statistics/Dispersion/Range.swift +++ b/Sources/StatKit/Descriptive Statistics/Dispersion/Range.swift @@ -6,7 +6,6 @@ public extension Collection { /// - returns: The range of the selected variable. /// /// The range is the difference between the lowest and highest number in a collection. - /// The time complexity of this method is O(n). func range( of variable: KeyPath ) -> Double { diff --git a/Sources/StatKit/Descriptive Statistics/Dispersion/Variability.swift b/Sources/StatKit/Descriptive Statistics/Dispersion/Variability.swift index db1068f..a76862d 100644 --- a/Sources/StatKit/Descriptive Statistics/Dispersion/Variability.swift +++ b/Sources/StatKit/Descriptive Statistics/Dispersion/Variability.swift @@ -5,8 +5,6 @@ public extension Collection { /// - parameter variable: The variable over which to calculate the variance. /// - parameter composition: The composition of the collection. /// - returns: The variance of the collection. - /// - /// The time complexity of this method is O(n). @inlinable func variance( variable: KeyPath, @@ -39,8 +37,6 @@ public extension Collection { /// - parameter variable: The variable over which to calculate the standard deviation. /// - parameter composition: The composition of the collection. /// - returns: The standard deviation of the collection, rounded to a representable value. - /// - /// The time complexity of this method is O(n). @inlinable func standardDeviation( variable: KeyPath, @@ -57,7 +53,6 @@ public extension Collection { /// /// Since there is no notion of covariance in collections with less than two elements, /// this method returns NaN if the array count is less than two. - /// The time complexity of this method is O(n). @inlinable func covariance( of X: KeyPath, diff --git a/Sources/StatKit/Descriptive Statistics/Distribution/Continuous/GammaDistribution.swift b/Sources/StatKit/Descriptive Statistics/Distribution/Continuous/GammaDistribution.swift index ffd01e1..2a72138 100644 --- a/Sources/StatKit/Descriptive Statistics/Distribution/Continuous/GammaDistribution.swift +++ b/Sources/StatKit/Descriptive Statistics/Distribution/Continuous/GammaDistribution.swift @@ -14,6 +14,8 @@ public struct GammaDistribution: ContinuousDistribution, UnivariateDistribution /// Creates a Gamma Distribution with a specified alpha and beta parameters. /// - parameter alpha: The distribution alpha parameter. /// - parameter beta: The distribution beta parameter. + /// + /// - important: This initializer is deprecated. Use ``init(shape:scale:)`` or ``init(shape:rate:)`` instead. @available(*, deprecated, renamed: "init(shape:scale:)") public init(alpha: Double, beta: Double) { precondition(0 < alpha, "The shape parameter needs to be greater than 0.") diff --git a/Sources/StatKit/Descriptive Statistics/Distribution/Continuous/NormalDistribution.swift b/Sources/StatKit/Descriptive Statistics/Distribution/Continuous/NormalDistribution.swift index d0428d2..24afb10 100644 --- a/Sources/StatKit/Descriptive Statistics/Distribution/Continuous/NormalDistribution.swift +++ b/Sources/StatKit/Descriptive Statistics/Distribution/Continuous/NormalDistribution.swift @@ -18,6 +18,9 @@ public struct NormalDistribution: ContinuousDistribution, UnivariateDistribution self.variance = variance } + /// Create a Normal Distribution with a specified mean and standard deviation. + /// - parameter mean: The mean value of this distribution. + /// - parameter standardDeviation: The standard deviation for this distribution. public init(mean: Double, standardDeviation: Double) { precondition( 0 < standardDeviation, diff --git a/Sources/StatKit/Descriptive Statistics/Ranking/Ranking.swift b/Sources/StatKit/Descriptive Statistics/Ranking/Ranking.swift index 193168d..66e25f9 100644 --- a/Sources/StatKit/Descriptive Statistics/Ranking/Ranking.swift +++ b/Sources/StatKit/Descriptive Statistics/Ranking/Ranking.swift @@ -9,8 +9,6 @@ public extension Collection { /// - important: This method triggers a precondition failure if attempting to rank a collection /// of instances that do not compare equal to themselves. For example, attempting to rank a collection /// of floating point numbers that contain NaN's will fail, since `Double.nan == Double.nan` is false. - /// - /// The time complexity of this method is O(n). func rank( variable: KeyPath, by order: @escaping (_ lhs: T, _ rhs: T) -> Bool, diff --git a/Sources/StatKit/Descriptive Statistics/Ranking/RankingStrategy.swift b/Sources/StatKit/Descriptive Statistics/Ranking/RankingStrategy.swift index 74bbb6d..4808059 100644 --- a/Sources/StatKit/Descriptive Statistics/Ranking/RankingStrategy.swift +++ b/Sources/StatKit/Descriptive Statistics/Ranking/RankingStrategy.swift @@ -19,15 +19,31 @@ protocol RankingStrategyProtocol { /// A calculation strategy for ranking comparable variables. public enum RankingStrategy: CaseIterable, Sendable { - /// The Fractional ranking strategy. + /// Tied elements receive the average of the ranks they would otherwise occupy. + /// + /// For example, two elements tied for 2nd place both receive rank 2.5, and the next element receives rank 4. case fractional - /// The Standard Competition ranking strategy. + + /// Tied elements share the lowest rank in their group, and the next rank skips over the tie count. + /// + /// For example, two elements tied for 2nd place both receive rank 2, and the next element receives rank 4. case standardCompetition - /// The Modified Competition ranking strategy. + + /// Tied elements share the highest rank in their group. + /// + /// For example, two elements tied for 2nd place both receive rank 3, and the next element receives rank 4. case modifiedCompetition - /// The Ordinal ranking strategy. + + /// Tied elements are assigned consecutive ranks based on their order in the collection, with no averaging. + /// + /// For example, two elements tied for 2nd place receive ranks 2 and 3 respectively, + /// and the next element receives rank 4. case ordinal - /// The Dense ranking strategy. + + /// Tied elements share the same rank, and the next distinct rank is always incremented by one + /// regardless of tie count. + /// + /// For example, two elements tied for 2nd place both receive rank 2, and the next element receives rank 3. case dense /// A calculator object that can be used to compute the specified rank. diff --git a/Sources/StatKit/Descriptive Statistics/Summation/Summation.swift b/Sources/StatKit/Descriptive Statistics/Summation/Summation.swift index e91cbd6..25b365e 100644 --- a/Sources/StatKit/Descriptive Statistics/Summation/Summation.swift +++ b/Sources/StatKit/Descriptive Statistics/Summation/Summation.swift @@ -2,8 +2,6 @@ public extension Collection { /// Calculates the sum of all contained elements. /// - parameter variable: The variable over which to calculate the sum. /// - returns: The sum of the variable in the collection. - /// - /// - complexity: O(n), where n is the length of the collection. @inlinable func sum( over variable: KeyPath diff --git a/Sources/StatKit/StatKit.docc/Centeral Tendency.md b/Sources/StatKit/StatKit.docc/Central Tendency.md similarity index 100% rename from Sources/StatKit/StatKit.docc/Centeral Tendency.md rename to Sources/StatKit/StatKit.docc/Central Tendency.md diff --git a/Sources/StatKit/StatKit.docc/Combinatorial Extensions.md b/Sources/StatKit/StatKit.docc/Combinatorial Extensions.md deleted file mode 100644 index 14765d5..0000000 --- a/Sources/StatKit/StatKit.docc/Combinatorial Extensions.md +++ /dev/null @@ -1,14 +0,0 @@ -# Combinatorial Extensions - -Compute combinatorial numbers and other related functions. - -## Overview - -StatKit allows developers to compute different extensions of combinatorial numbers. - -## Topics - -### Functions - -- ``choose(n:k:)`` -- ``beta(alpha:beta:logarithmic:)`` diff --git a/Sources/StatKit/StatKit.docc/Distributions.md b/Sources/StatKit/StatKit.docc/Distributions.md index 745f401..cd302d9 100644 --- a/Sources/StatKit/StatKit.docc/Distributions.md +++ b/Sources/StatKit/StatKit.docc/Distributions.md @@ -30,15 +30,12 @@ These types define common distributions used to make theoretical calculations or - ``ExponentialDistribution`` - ``LogisticDistribution`` - ``LogLogisticDistribution`` -- ``FiskDistribution`` - ``NormalDistribution`` - ``BetaDistribution`` - ``GammaDistribution`` - ``ChiSquaredDistribution`` - ``ErlangDistribution`` -### Discrete Multivariate Distributions - - -### Continuous Multivariate Distributions +### Type Aliases +- ``FiskDistribution`` diff --git a/Sources/StatKit/StatKit.docc/Mathematical Functions.md b/Sources/StatKit/StatKit.docc/Mathematical Functions.md new file mode 100644 index 0000000..5146333 --- /dev/null +++ b/Sources/StatKit/StatKit.docc/Mathematical Functions.md @@ -0,0 +1,24 @@ +# Mathematical Functions + +Compute special mathematical functions used in probability and statistics. + +## Overview + +StatKit exposes a set of special mathematical functions that are commonly used in probability theory and statistics. + +## Topics + +### Binomial Coefficients + +- ``choose(n:k:)`` + +### Beta Functions + +- ``beta(alpha:beta:logarithmic:)`` +- ``regularizedIncompleteBeta(x:alpha:beta:)`` + +### Gamma Functions + +- ``incompleteGamma(lower:upper:alpha:logarithmic:)`` +- ``incompleteGamma(lower:upper:alpha:)`` +- ``regularizedIncompleteGamma(lower:upper:alpha:logarithmic:)`` diff --git a/Sources/StatKit/StatKit.docc/Ranking.md b/Sources/StatKit/StatKit.docc/Ranking.md index deb9731..c63421e 100644 --- a/Sources/StatKit/StatKit.docc/Ranking.md +++ b/Sources/StatKit/StatKit.docc/Ranking.md @@ -4,7 +4,7 @@ Put rankings on data points such that, for any two items, they are either ranked ## Overview -There are several ways of ranking items. The most common ones are implemented as a `RankingStrategy`, allowing for immediate use. +There are several ways of ranking items. The most common ones are implemented as a `RankingStrategy`, allowing for immediate use. The strategies differ in how they handle tied observations, so choose the one that matches the convention expected by your analysis. ## Topics diff --git a/Sources/StatKit/StatKit.docc/StatKit.md b/Sources/StatKit/StatKit.docc/StatKit.md index 81ffca3..cb17c54 100644 --- a/Sources/StatKit/StatKit.docc/StatKit.md +++ b/Sources/StatKit/StatKit.docc/StatKit.md @@ -10,17 +10,14 @@ StatKit provides Swift developers with tools to describe data sets and make pred ### Descriptive Statistics -- +- - - - - - - -- - -### Inferential Statistics - +- ### Module Specific Protocols - ``ConvertibleToReal`` diff --git a/Sources/StatKit/StatKit.docc/Summation.md b/Sources/StatKit/StatKit.docc/Summation.md index 11708d2..82fc939 100644 --- a/Sources/StatKit/StatKit.docc/Summation.md +++ b/Sources/StatKit/StatKit.docc/Summation.md @@ -2,11 +2,9 @@ Sum over variables in a data set. -@Comment { - ## Overview - - Maybe we don't need an overview for this? -} +## Overview + +Summation is a fundamental building block in statistical computation, underpinning everything from means to more complex aggregations. ## Topics