Merge pull request #80 from JuliaAI/dev

For a 0.2.0 release

Author: ablaom

.github/codecov.yml

@@ -3,6 +3,7 @@ coverage:
     project:
       default:
         threshold: 0.5%
+        removed_code_behavior: fully_covered_patch
     patch:
       default:
-        target: 80%
+        target: 80

.github/dependabot.yml

@@ -0,0 +1,7 @@
+# https://docs.github.com/github/administering-a-repository/configuration-options-for-dependency-updates
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/" # Location of package manifests
+    schedule:
+      interval: "monthly"

.github/workflows/CompatHelper.yml

@@ -7,10 +7,12 @@ jobs:
   CompatHelper:
     runs-on: ubuntu-latest
     steps:
-      - name: Pkg.add("CompatHelper")
-        run: julia -e 'using Pkg; Pkg.add("CompatHelper")'
-      - name: CompatHelper.main()
+      - name: Install CompatHelper
+        shell: julia --color=yes {0}
+        run: using Pkg; Pkg.add("CompatHelper")
+      - name: Run CompatHelper
+        shell: julia --color=yes {0}
+        run: using CompatHelper; CompatHelper.main()
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           COMPATHELPER_PRIV: ${{ secrets.COMPATHELPER_PRIV}}
-        run: julia -e 'using CompatHelper; CompatHelper.main()'

.github/workflows/ci.yml

@@ -17,7 +17,7 @@ jobs:
       fail-fast: false
       matrix:
         version:
-          - '1.6'
+          - '1.10'
           - '1' # automatically expands to the latest stable 1.x release of Julia.
         os:
           - ubuntu-latest
@@ -28,12 +28,12 @@ jobs:
             version: '1'
             arch: x86
     steps:
-      - uses: actions/checkout@v2
-      - uses: julia-actions/setup-julia@v1
+      - uses: actions/checkout@v5
+      - uses: julia-actions/setup-julia@v2
         with:
           version: ${{ matrix.version }}
           arch: ${{ matrix.arch }}
-      - uses: actions/cache@v1
+      - uses: julia-actions/cache@v2
         env:
           cache-name: cache-artifacts
         with:
@@ -48,6 +48,6 @@ jobs:
         env:
           JULIA_NUM_THREADS: 2
       - uses: julia-actions/julia-processcoverage@v1
-      - uses: codecov/codecov-action@v1
+      - uses: codecov/codecov-action@v5
         with:
-          file: lcov.info
+          files: lcov.info

Project.toml

@@ -1,14 +1,15 @@
 name = "CategoricalDistributions"
 uuid = "af321ab8-2d2e-40a6-b165-3d674595d28e"
 authors = ["Anthony D. Blaom <[email protected]>"]
-version = "0.1.15"
+version = "0.2.0"
 
 [deps]
 CategoricalArrays = "324d7699-5711-5eae-9e2f-1d82baa6b597"
 Distributions = "31c24e10-a181-5473-b8eb-7969acd0382f"
 Missings = "e1d29d7a-bbdc-5cf2-9ac0-f12de2c33e28"
 OrderedCollections = "bac558e1-5e72-5ebc-8fee-abe8a469f55d"
 Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
+Reexport = "189a3867-3050-52da-a836-e630ba90ab69"
 ScientificTypes = "321657f4-b219-11e9-178b-2701a2544e81"
 UnicodePlots = "b8865327-cd53-5732-bb35-84acbb429228"
 
@@ -20,21 +21,24 @@ UnivariateFiniteDisplayExt = "UnicodePlots"
 
 [compat]
 BenchmarkTools = "1.3.2"
-CategoricalArrays = "0.9, 0.10"
+CategoricalArrays = "1"
 Distributions = "0.25"
 Missings = "0.4, 1"
 OrderedCollections = "1.1"
+Reexport = "1.2.2"
 ScientificTypes = "3.0"
+Suppressor = "0.2.8"
 UnicodePlots = "2, 3"
-julia = "1.6"
+julia = "1.10"
 
 [extras]
 BenchmarkTools = "6e4b80f9-dd63-53aa-95a3-0cdb28fa8baf"
 FillArrays = "1a297f60-69ca-5386-bcde-b61e274b549b"
 Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
 StableRNGs = "860ef19b-820b-49d6-a774-d7a799459cd3"
+Suppressor = "fd094767-a336-5f1f-9728-57cf17d0bbfb"
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 UnicodePlots = "b8865327-cd53-5732-bb35-84acbb429228"
 
 [targets]
-test = ["BenchmarkTools", "FillArrays", "Random", "StableRNGs", "Test", "UnicodePlots"]
+test = ["BenchmarkTools", "FillArrays", "Random", "StableRNGs", "Suppressor", "Test", "UnicodePlots"]

README.md

@@ -4,10 +4,10 @@ Probability distributions and measures for finite sample spaces whose
 elements are *labeled* (consist of the class pool of a
 `CategoricalArray`).
 
-Designed for performance in machine learning applications. For
+Designed for performance in machine learning applications, where one is constructing large arrays of such distributions. For
 example, probabilistic classifiers in
 [MLJ](https://alan-turing-institute.github.io/MLJ.jl/dev/) typically
-predict the `UnivariateFiniteVector` objects defined in this package.
+predict the `UnivariateFiniteArray` objects defined in this package.
 
 For probability distributions over integers see the
 [Distributions.jl](https://juliastats.org/Distributions.jl/stable/univariate/#Discrete-Distributions)
@@ -50,6 +50,16 @@ julia> mode(d)
 CategoricalValue{String, UInt32} "no"
 ```
 
+Of course, a `UnivariateFinite` object can be sampled:
+
+```julia
+julia> rand(d, 5)
+3-element Vector{CategoricalValue{String, UInt32}}:
+ "no"
+ "no"
+ "maybe"
+```
+
 A `UnivariateFinite` distribution can also be constructed directly
 from a probability vector:
 
@@ -62,11 +72,11 @@ julia> d2 = UnivariateFinite(["no", "yes"], [0.15, 0.85], pool=data)
        └                                        ┘
 ```
 
-A `UnivariateFinite` distribution tracks all classes in the pool:
+A `UnivariateFinite` distribution tracks all classes (levels) in the pool:
 
 ```julia
 levels(d2)
-3-element Vector{String}:
+3-element CategoricalArray{String,1,UInt32}:
  "maybe"
  "no"
  "yes"
@@ -106,7 +116,7 @@ probability array:
 
 ```julia
 julia> L = levels(data)
-3-element Vector{String}:
+3-element CategoricalArray{String,1,UInt32}:
  "maybe"
  "no"
  "yes"
@@ -121,26 +131,28 @@ julia> pdf(v, L)
 
 ## Measures over finite labeled sets
 
-There is, in fact, no enforcement that probabilities in a
-`UnivariateFinite` distribution sum to one, only that they be belong
-to a type `T` for which `zero(T)` is defined. In particular
-`UnivariateFinite` objects implement arbitrary non-negative, signed,
-or complex measures over a finite labeled set.
+There is, in fact, no enforcement that probabilities in a `UnivariateFinite` distribution
+sum to one, only that they be belong to a type `T` for which `zero(T)` is defined. In
+particular `UnivariateFinite` objects implement arbitrary non-negative, signed, or complex
+measures over a finite labeled set. 
+
+However, you cannot sample using `pdf` unless "probabilities" are non-negative (their type
+`T` must support `>` and addition).
 
 ## What does this package provide?
 
-- A new type `UnivariateFinite{S}` for representing probability
-  distributions over the pool of a `CategoricalArray`, that is, over
-  finite *labeled* sets. Here `S` is a subtype of `OrderedFactor`
-  from ScientificTypesBase.jl, if the pool is ordered, or of
-  `Multiclass` if the pool is unordered.
+- A new type `UnivariateFinite{S}` for representing probability distributions over the
+  pool of a `CategoricalArray`, that is, over finite *labeled* sets. Here `S` is a subtype
+  of `OrderedFactor` from
+  [ScientificTypesBase.jl](https://github.com/JuliaAI/ScientificTypesBase.jl), if the pool
+  is ordered, or of `Multiclass` if the pool is unordered.
 
 - A new array type `UnivariateFiniteArray{S} <:
   AbstractArray{<:UnivariateFinite{S}}` for efficiently manipulating
   arrays of `UnivariateFinite` distributions.
 
-- Implementations of `rand` for generating random samples of a
-  `UnivariateFinite` distribution.
+- Implementations of `rand` for generating random samples of a `UnivariateFinite`
+  distribution, in the case that "probabilities" come from an ordered field.
 
 - Implementations of the `pdf`, `logpdf`, `mode` and `modes` methods of
   Distributions.jl, with efficient broadcasting over the new array

ext/UnivariateFiniteDisplayExt.jl

@@ -8,9 +8,11 @@ import UnicodePlots
 import ScientificTypes.Finite
 
 # The following is a specialization of a `show` method already in /src/ for the common
-# case of `Real` probabilities.
+# case of certain numerical  probabilities.
+
+const Numerical = Union{AbstractFloat,Integer}
 function Base.show(io::IO, mime::MIME"text/plain",
-                   d::UnivariateFinite{<:Finite{K},V,R,P}) where {K,V,R,P<:Real}
+                   d::UnivariateFinite{<:Finite{K},V,R,P}) where {K,V,R,P<:Numerical}
     show_bars = false
     if K <= MAX_NUM_LEVELS_TO_SHOW_BARS &&
         all(>=(0), values(d.prob_given_ref))

src/CategoricalDistributions.jl

@@ -1,5 +1,6 @@
 module CategoricalDistributions
 
+using Reexport
 import Distributions
 import ScientificTypes:
     Finite,
@@ -10,7 +11,7 @@ import ScientificTypes:
     ScientificTypesBase
 
 using OrderedCollections
-using CategoricalArrays
+@reexport using CategoricalArrays
 import Missings
 using Random
 
@@ -24,6 +25,7 @@ include("scitypes.jl")
 include("methods.jl")
 include("arrays.jl")
 include("arithmetic.jl")
+include("deprecated.jl")
 
 export UnivariateFinite, UnivariateFiniteArray, UnivariateFiniteVector
 
@@ -33,9 +35,4 @@ export pdf, logpdf, support, mode, modes
 # re-export from ScientificTypesBase:
 export Multiclass, OrderedFactor
 
-# for julia < 1.9
-if !isdefined(Base, :get_extension)
-  include("../ext/UnivariateFiniteDisplayExt.jl")
-end
-
 end

src/arithmetic.jl

@@ -10,13 +10,13 @@ pdf_matrix(d::UnivariateFinite, L) = pdf.(d, L)
 pdf_matrix(d::AbstractArray{<:UnivariateFinite}, L) = pdf(d, L)
 
 function +(d1::UnivariateFinite{S, V}, d2::UnivariateFinite{S, V}) where {S, V}
-    L = classes(d1)
-    L == classes(d2) || throw(ERR_DIFFERENT_SAMPLE_SPACES)
+    L = levels(d1)
+    L == levels(d2) || throw(ERR_DIFFERENT_SAMPLE_SPACES)
     return UnivariateFinite(L, pdf_matrix(d1, L) + pdf_matrix(d2, L))
 end
 function +(d1::UnivariateFiniteArray{S, V}, d2::UnivariateFiniteArray{S, V}) where {S, V}
-    L = classes(d1)
-    L == classes(d2) || throw(ERR_DIFFERENT_SAMPLE_SPACES)
+    L = CategoricalDistributions.element_levels(d1)
+    L == CategoricalDistributions.element_levels(d2) || throw(ERR_DIFFERENT_SAMPLE_SPACES)
     return UnivariateFinite(L, pdf_matrix(d1, L) + pdf_matrix(d2, L))
 end
 
@@ -33,13 +33,13 @@ end
 -(d::UnivariateFiniteArray) = _minus(d, UnivariateFiniteArray)
 
 function -(d1::UnivariateFinite{S, V}, d2::UnivariateFinite{S, V}) where {S, V}
-    L = classes(d1)
-    L == classes(d2) || throw(ERR_DIFFERENT_SAMPLE_SPACES)
+    L = levels(d1)
+    L == levels(d2) || throw(ERR_DIFFERENT_SAMPLE_SPACES)
     return UnivariateFinite(L, pdf_matrix(d1, L) - pdf_matrix(d2, L))
 end
 function -(d1::UnivariateFiniteArray{S, V}, d2::UnivariateFiniteArray{S, V}) where {S, V}
-    L = classes(d1)
-    L == classes(d2) || throw(ERR_DIFFERENT_SAMPLE_SPACES)
+    L = CategoricalDistributions.element_levels(d1)
+    L == CategoricalDistributions.element_levels(d2) || throw(ERR_DIFFERENT_SAMPLE_SPACES)
     return UnivariateFinite(L, pdf_matrix(d1, L) - pdf_matrix(d2, L))
 end