feat(api): Add pointwise_conditional_loglikelihoods. Deprecate pointwise_loglikelihoods. (#88)

* docs: Don't recommend overloading pointwise_loglikelihoods

Author: sethaxen

CHANGELOG.md

@@ -12,6 +12,12 @@
 
 ### Documentation
 
+## v0.4.6 (2026-02-03)
+
+### Features
+
+- Add `pointwise_conditional_loglikelihoods`. Deprecate `pointwise_loglikelihoods`. ([#88](https://github.com/arviz-devs/PosteriorStats.jl/pull/88))
+
 ## v0.4.5 (2026-02-03)
 
 ### Maintenance

Project.toml

@@ -1,7 +1,7 @@
 name = "PosteriorStats"
 uuid = "7f36be82-ad55-44ba-a5c0-b8b5480d7aa5"
 authors = ["Seth Axen <seth@sethaxen.com> and contributors"]
-version = "0.4.5"
+version = "0.4.6"
 
 [deps]
 Distributions = "31c24e10-a181-5473-b8eb-7969acd0382f"

docs/src/api.md

@@ -58,11 +58,5 @@ r2_score
 
 ```@docs
 PosteriorStats.kde_reflected
-PosteriorStats.pointwise_loglikelihoods
-PosteriorStats.pointwise_loglikelihoods(
-    y::AbstractArray{<:Real,N},
-    dists::AbstractArray{
-        <:Distributions.Distribution{<:Distributions.ArrayLikeVariate{N}},M
-    },
-) where {M,N}
+PosteriorStats.pointwise_conditional_loglikelihoods
 ```

src/pointwise_loglikelihoods.jl

@@ -1,24 +1,7 @@
-"""
-    pointwise_loglikelihoods
-
-Compute pointwise conditional log-likelihoods for ELPD-based model comparison/validation.
-
-Given model parameters ``\\theta`` and observations ``y``, the pointwise conditional
-log-likelihood of ``y_i`` given ``y_{-i}`` (the elements of ``y`` excluding ``y_i``) and
-``\\theta`` is defined as
-```math
-\\log p(y_i \\mid y_{-i}, \\theta)
-```
-
-This method is a utility function that dependant packages can override to provide pointwise
-conditional log-likelihoods for their own models/distributions.
-
-See also: [`loo`](@ref)
-"""
-pointwise_loglikelihoods
+@deprecate pointwise_loglikelihoods(y, dists) pointwise_conditional_loglikelihoods(y, dists)
 
 @doc """
-    pointwise_loglikelihoods(y, dists)
+    pointwise_conditional_loglikelihoods(y, dists)
 
 Compute pointwise conditional log-likelihoods of `y` for non-factorized distributions.
 
@@ -52,7 +35,7 @@ PPL. This utility function computes ``\\log p(y_i \\mid y_{-i}, \\theta)`` terms
 - [LOOFactorized](@cite) Vehtari et al. Leave-one-out cross-validation for non-factorized
     models
 """
-function pointwise_loglikelihoods(
+function pointwise_conditional_loglikelihoods(
     y::AbstractArray{<:Real,N},
     dists::AbstractArray{
         <:Distributions.Distribution{<:Distributions.ArrayLikeVariate{N}},M
@@ -62,13 +45,13 @@ function pointwise_loglikelihoods(
     sample_dims = ntuple(identity, M)
     log_like = similar(y, T, (axes(dists)..., axes(y)...))
     for (dist, ll) in zip(dists, eachslice(log_like; dims=sample_dims))
-        pointwise_loglikelihoods!(ll, y, dist)
+        pointwise_conditional_loglikelihoods!(ll, y, dist)
     end
     return log_like
 end
 
 # Array-variate normal distribution
-function pointwise_loglikelihoods!(
+function pointwise_conditional_loglikelihoods!(
     log_like::AbstractVector{<:Real},
     y::AbstractVector{<:Real},
     dist::Distributions.MvNormal,
@@ -78,7 +61,7 @@ function pointwise_loglikelihoods!(
     g = Σ \ (y - μ)
     return @. log_like = (log(λ) - g^2 / λ - log2π) / 2
 end
-function pointwise_loglikelihoods!(
+function pointwise_conditional_loglikelihoods!(
     log_like::AbstractVector{<:Real},
     y::AbstractVector{<:Real},
     dist::Distributions.MvNormalCanon,
@@ -88,7 +71,7 @@ function pointwise_loglikelihoods!(
     cov_inv_y = _pdmul(J, y)
     return @. log_like = (log(λ) - (cov_inv_y - h)^2 / λ - log2π) / 2
 end
-function pointwise_loglikelihoods!(
+function pointwise_conditional_loglikelihoods!(
     log_like::AbstractMatrix{<:Real},
     y::AbstractMatrix{<:Real},
     dist::Distributions.MatrixNormal,
@@ -101,19 +84,19 @@ function pointwise_loglikelihoods!(
 end
 
 # Multivariate log-normal distribution
-function pointwise_loglikelihoods!(
+function pointwise_conditional_loglikelihoods!(
     log_like::AbstractVector{<:Real},
     y::AbstractVector{<:Real},
     dist::Distributions.MvLogNormal,
 )
     logy = log.(y)
-    pointwise_loglikelihoods!(log_like, logy, dist.normal)
+    pointwise_conditional_loglikelihoods!(log_like, logy, dist.normal)
     log_like .-= logy
     return log_like
 end
 
 # Array-variate t-distribution
-function pointwise_loglikelihoods!(
+function pointwise_conditional_loglikelihoods!(
     log_like::AbstractVector{T},
     y::AbstractVector{<:Real},
     dist::Distributions.GenericMvTDist,

test/pointwise_loglikelihoods.jl

@@ -155,14 +155,14 @@ end
 
         test_factorized = !(dist_type <: Distributions.GenericMvTDist)
 
-        @testset "pointwise_loglikelihoods!" begin
+        @testset "pointwise_conditional_loglikelihoods!" begin
             @testset "consistent with conditional distributions" begin
                 dist = rand_dist(dist_type, T, sz)
                 y = convert(Array{T}, rand(dist))
                 @assert eltype(y) == T
                 log_like = similar(y)
                 y_inds = ndims(y) > 1 ? CartesianIndices(y) : eachindex(y)
-                PosteriorStats.pointwise_loglikelihoods!(log_like, y, dist)
+                PosteriorStats.pointwise_conditional_loglikelihoods!(log_like, y, dist)
                 conditional_dists = conditional_distribution.(Ref(dist), Ref(y), y_inds)
                 log_like_ref = loglikelihood.(conditional_dists, y)
                 @test log_like ≈ log_like_ref
@@ -173,14 +173,14 @@ end
                 y = convert(Array{T}, rand(dist))
                 @assert eltype(y) == T
                 log_like = similar(y)
-                PosteriorStats.pointwise_loglikelihoods!(log_like, y, dist)
+                PosteriorStats.pointwise_conditional_loglikelihoods!(log_like, y, dist)
                 factorized_dists = factorized_distributions(dist)
                 log_like_ref = loglikelihood.(factorized_dists, y)
                 @test log_like ≈ log_like_ref
             end
         end
 
-        @testset "pointwise_loglikelihoods" begin
+        @testset "pointwise_conditional_loglikelihoods" begin
             ndraws, nchains = 7, 3
             @testset for dim_type in (UnitRange, DimensionalData.Dim)
                 if dim_type <: UnitRange
@@ -207,7 +207,9 @@ end
                 @assert size(dists) == (ndraws, nchains)
                 y = zeros(T, y_dims...)
                 rand!(first(dists), y)
-                log_like = @inferred PosteriorStats.pointwise_loglikelihoods(y, dists)
+                log_like = @inferred PosteriorStats.pointwise_conditional_loglikelihoods(
+                    y, dists
+                )
                 @test size(log_like) == (ndraws, nchains, sz...)
                 @test eltype(log_like) == T
                 @test all(isfinite, log_like)