Continue working on docstrings

Author: guilgautier

src/common.jl

@@ -1,12 +1,48 @@
+"""
+    AbstractPointProcess{T}
+
+Abstract type encoding the notion of [point process](https://en.wikipedia.org/wiki/Point_process)
+The type `T` corresponds to the elements' type of the point process (vectors, graph edges, etc.)
+
+**See also**
+- [`PRS.AbstractSpatialPointProcess`](@ref)
+- [`PRS.AbstractGraphPointProcess`](@ref)
+"""
 abstract type AbstractPointProcess{T} end
 Base.eltype(pp::AbstractPointProcess{T}) where {T} = T
 
+@doc raw"""
+    AbstractSpatialPointProcess{T<:Vector{Float64}} <: AbstractPointProcess{T}
+
+Abstract type encoding point processes defined on ``\mathbb{R}^d``.
+
+Concrete instances must have a `window` field of type [`PRS.AbstractSpatialWindow`](@ref)
+"""
 abstract type AbstractSpatialPointProcess{T<:Vector{Float64}} <: AbstractPointProcess{T} end
 
+"""
+    window(pp::AbstractSpatialPointProcess) = pp.window
+"""
 window(pp::AbstractSpatialPointProcess) = pp.window
+
+"""
+    dimension(pp::AbstractSpatialPointProcess) = dimension(window(pp))
+
+**See also**
+    - [`window`](@ref)
+"""
 dimension(pp::AbstractSpatialPointProcess) = dimension(window(pp))
 
 abstract type AbstractGraphPointProcess{T} <: AbstractPointProcess{T} end
 
+# Default methods
+
+"""
+Default exact sampling method
+"""
 function generate_sample end
+
+"""
+Default exact sampling method using Partial Rejection Sampling (PRS, [GuJeLi19](@cite))
+"""
 function generate_sample_prs end

src/dominated_cftp.jl

@@ -28,7 +28,18 @@ Compute an upper bound of [`papangelou_conditional_intensity`](@ref)
 """
 function upper_bound_papangelou_conditional_intensity end
 
+"""
+    isrepulsive
+
+Property of a [`PRS.AbstractSpatialPointProcess`](@ref) used in [`generate_sample_dcftp`](@ref).
+"""
 function isrepulsive end
+
+"""
+    isattractive
+
+Property of a [`PRS.AbstractSpatialPointProcess`](@ref) used in [`generate_sample_dcftp`](@ref).
+"""
 function isattractive end
 
 """
@@ -47,8 +58,8 @@ Generate an exact sample from a spatial point process `pp` on window optional wi
 
 **See also**
 
-    - [KeMo99](@cite), [KeMo00](@cite)
-    - Section 11.2.6 [MoWa04](@cite)
+- [KeMo99](@cite), [KeMo00](@cite)
+- Section 11.2.6 [MoWa04](@cite)
 """
 function generate_sample_dcftp(
     pp::AbstractSpatialPointProcess{T};

src/grid_prs.jl

@@ -2,22 +2,57 @@
 Implementation of Grid Partial Rejection Sampling of [MoKr20](@cite)
 """
 
+"""
+    AbstractCellGridPRS
+
+Abstract type describing a cell used Grid Partial Rejection Sampling of [MoKr20](@cite).
+"""
 abstract type AbstractCellGridPRS end
+
+"""
+    GraphCellGridPRS{T} <: AbstractCellGridPRS
+
+Mutable struct describing a graph node with fields
+    - `window` of type [`PRS.GraphNode`](@ref)`{T}`
+    - `value` of type `T`
+"""
 mutable struct GraphCellGridPRS{T} <: AbstractCellGridPRS
     window::GraphNode{T}
     value::T
 end
+
+"""
+    SpatialCellGridPRS{T<:Vector{Float64}} <: AbstractCellGridPRS
+
+Mutable struct describing a spatial cell with fields
+    - `window` of type `Union{`[`PRS.RectangleWindow`](@ref)`,`[`PRS.RectangleWindow`](@ref)`}``
+    - `value` of type `Vector{T}`
+"""
 mutable struct SpatialCellGridPRS{T<:Vector{Float64}} <: AbstractCellGridPRS
     window::Union{RectangleWindow,SquareWindow}
     value::Vector{T}
 end
 
+"""
+    window(cell::AbstractCellGridPRS) = cell.window
+"""
 window(cell::AbstractCellGridPRS) = cell.window
+
+"""
+    dimension(cell::AbstractCellGridPRS) = dimension(window(cell))
+"""
 dimension(cell::AbstractCellGridPRS) = dimension(window(cell))
 
-Base.isempty(cell::SpatialCellGridPRS) = isempty(cell.value)
+"""
+    Base.iterate(cell::AbstractCellGridPRS, state=1) = iterate(cell.value, state)
+"""
 Base.iterate(cell::AbstractCellGridPRS, state=1) = iterate(cell.value, state)
 
+"""
+    Base.isempty(cell::SpatialCellGridPRS) = isempty(cell.value)
+"""
+Base.isempty(cell::SpatialCellGridPRS) = isempty(cell.value)
+
 """
     generate_sample!(
         cell::AbstractCellGridPRS,
@@ -36,6 +71,16 @@ function generate_sample!(
     cell.value = generate_sample(pp; win=cell.window, rng=rng)
 end
 
+"""
+    generate_sample!(
+        cells::Vector{T},
+        indices,
+        pp::AbstractPointProcess;
+        rng=-1
+    ) where {T<:AbstractCellGridPRS}
+
+Apply [`generate_sample!`](@ref) to each cell of `cells` indexed by `indices`.
+"""
 function generate_sample!(
     cells::Vector{T},
     indices,
@@ -79,7 +124,7 @@ end
         rng=-1
     )::SWG.SimpleWeightedGraph
 
-Construct the weighted interaction graph ([King graph](https://en.wikipedia.org/wiki/King%27s_graph)) used in [`generate_sample_grid_prs`](@ref), to generate exact samples from [`AbstractSpatialPointProcess`](@ref)
+Construct the weighted interaction graph ([King graph](https://en.wikipedia.org/wiki/King%27s_graph)) used in [`PRS.generate_sample_grid_prs`](@ref), to generate exact samples from [`PRS.AbstractSpatialPointProcess`](@ref)
 
 The `pp.window` is divided into cells of length the interaction range `pp.r`.
 Each cell represents a vertex of the interaction (king) graph and each edge carries a uniform random varialble.
@@ -111,6 +156,13 @@ function weighted_interaction_graph(
     return g
 end
 
+"""
+    gibbs_interaction
+
+Compute the pairwise Gibbs interaction for a [`PRS.AbstractPointProcess`](@ref) between two [`PRS.AbstractCellGridPRS`](@ref).
+
+This is a subroutine of [`PRS.generate_sample_grid_prs`](@ref).
+"""
 function gibbs_interaction end
 
 @doc raw"""
@@ -162,9 +214,10 @@ end
 Identify the set of events to be resampled as constructed by Algorithm 5 in [GuJeLi19](@cite) as part of the Partial Rejection Sampling (PRS) method.
 Return the indices of the variables (here cells) involved in the corresponding events.
 
-This function is used as a subroutine of the grid PRS methodology of [MoKr20](@cite), see [`generate_sample_grid_prs`](@ref)
+This function is used as a subroutine of the grid PRS methodology of [MoKr20](@cite), see [`PRS.generate_sample_grid_prs`](@ref).
 
 **Note**
+
 If the event associated to the edge ``\{i,j\}`` of `g` is selected to be resampled, the uniform random variable encoded as the weight of the correspond edge is resampled (hence the "!")
 """
 function find_cells_to_resample_indices!(
@@ -203,9 +256,9 @@ end
         spp::AbstractSpatialPointProcess{T},
     )::Vector{SpatialCellGridPRS{T}} where {T}
 
-The `spp.window` ([`RectangleWindow`](@ref) or [`SquareWindow`](@ref)) is divided into [`SpatialCellGridPRS`](@ref) of length the interaction range `pp.r` following the construction of [MoKr20](@cite) in their grid Partial Rejection Sampling (grid PRS) methodology.
+The `spp.window` ([`PRS.RectangleWindow`](@ref) or [`PRS.SquareWindow`](@ref)) is divided into [`PRS.SpatialCellGridPRS`](@ref) of length the interaction range `pp.r` following the construction of [MoKr20](@cite) in their grid Partial Rejection Sampling (grid PRS) methodology.
 
-This function is used as a subroutine of [`generate_sample_grid_prs`](@ref)
+This function is used as a subroutine of [`PRS.generate_sample_grid_prs`](@ref)
 """
 function initialize_cells(
         spp::AbstractSpatialPointProcess{T},
@@ -236,10 +289,10 @@ end
         cell_j::SpatialCellGridPRS
     ) = false
 
-Assume `cell_i` and `cell_j` are neighboring cells in the weighted interaction graph constructed by [`weighted_interaction_graph`](@ref) from `spp` and already identified in the set of variables to be resampled in [`generate_sample_grid_prs`](@ref)
+Assume `cell_i` and `cell_j` are neighboring cells in the weighted interaction graph constructed by [`weighted_interaction_graph`](@ref) from `spp` and already identified in the set of variables to be resampled in [`PRS.generate_sample_grid_prs`](@ref)
 Since the configuration of points in the corresponding cells and the uniform random variable associated to the event `\{i,j\}` are considered fixed, there is no degree of freedom to make the interaction between `cell_i` and `cell_j` possible.
 
-This function is used as a subroutine of [`generate_sample_grid_prs`](@ref)
+This function is used as a subroutine of [`PRS.generate_sample_grid_prs`](@ref)
 """
 function is_inner_interaction_possible(
         spp::AbstractSpatialPointProcess,
@@ -259,7 +312,7 @@ end
 Assume `cell_i` and `cell_j` are neighboring cells in the weighted interaction graph constructed by [`weighted_interaction_graph`](@ref) from `spp`.
 Given the configuration of points in `cell_i`, check whether a realization of `spp` in `cell_j` can induce a bad event.
 
-This function is used as a subroutine of [`generate_sample_grid_prs`](@ref)
+This function is used as a subroutine of [`PRS.generate_sample_grid_prs`](@ref)
 """
 function is_outer_interaction_possible(
         spp::AbstractSpatialPointProcess,

src/hard_core_graph.jl

@@ -32,7 +32,7 @@ end
         β::Real
     ) where {T<:Integer}
 
-Construct a [`HardCoreGraph`](@ref) model on `graph` with parameter `β≥0`
+Construct a [`HardCoreGraph`](@ref)
 """
 function HardCoreGraph(
     graph::LG.SimpleGraph{T},
@@ -48,9 +48,8 @@ end
 
 """
     generate_sample_prs(
-            pp::HardCoreGraph{T};
-            win::Union{Nothing,AbstractWindow}=nothing,
-            rng=-1
+        hcg::HardCoreGraph{T};
+        rng=-1
     )::Vector{T} where {T}
 
 Sample from [`PRS.HardCoreGraph`](@ref) using Partial Rejection Sampling (PRS), see Section 7.2 of [GuJeLi19](@cite)

src/hard_core_spatial.jl

@@ -7,16 +7,18 @@ Spatial point process with density (w.r.t. the homogenous Poisson point process
     \prod_{x \in X}
         \beta
     \prod_{\{x, y\} \subseteq X}
-        1_{ \left\| x - y \right\|_2 > r }
+        1_{ \left\| x - y \right\|_2 > r },
 ```
 
 where ``\beta > 0`` is called the background intensity and ``r > 0`` the interaction range.
 
-[`PRS.HardCorePointProcess`](@ref) can be viewed as a [`PRS.StraussPointProcess`](@ref) with interaction coefficient ``\gamma=0``.
+[`PRS.HardCorePointProcess`](@ref) can be viewed as
+- [`PRS.HomogeneousPoissonPointProcess`](@ref) conditioned to having no pair of points at distance less than ``r``,
+- [`PRS.StraussPointProcess`](@ref) with interaction coefficient ``\gamma=0``.
 
 **See also**
 
-- [`PRS.HardCoreGraph`](@ref)
+- [`PRS.HardCoreGraph`](@ref), the graph counterpart of [`PRS.HardCorePointProcess`](@ref)
 """
 struct HardCorePointProcess{T<:Vector{Float64}} <: AbstractSpatialPointProcess{T}
     "Intensity"
@@ -29,53 +31,92 @@ end
 @doc raw"""
     HardCorePointProcess(β::Real, r::Real, window::AbstractSpatialWindow)
 
-Construct a [`PRS.HardCorePointProcess`](@ref) with intensity ``\beta > 0`` and interaction range ``r > 0``, restricted to `window`.
+Construct a [`PRS.HardCorePointProcess`](@ref) with intensity `β` and interaction range `r`, restricted to `window`.
 """
 function HardCorePointProcess(β::Real, r::Real, window::AbstractSpatialWindow)
     @assert β > 0
     @assert r > 0
     return HardCorePointProcess{Vector{Float64}}(β, r, window)
 end
 
+"""
+    intensity(pp::HardCorePointProcess) = pp.β
+"""
 intensity(pp::HardCorePointProcess) = pp.β
+
+"""
+    interaction_coefficient(pp::HardCorePointProcess) = 0.0
+"""
 interaction_coefficient(pp::HardCorePointProcess) = 0.0
+
+"""
+    interaction_range(pp::HardCorePointProcess) = pp.r
+"""
 interaction_range(pp::HardCorePointProcess) = pp.r
 
 ## Sampling
 
 """
     generate_sample(
-            pp::HardCorePointProcess{T};
-            win::Union{Nothing,AbstractWindow}=nothing,
-            rng=-1
+        pp::HardCorePointProcess{T};
+        win::Union{Nothing,AbstractWindow}=nothing,
+        rng=-1
     )::Vector{T} where {T}
 
 Generate an exact sample from the [`PRS.HardCorePointProcess`](@ref).
-Default sampler is [`PRS.generate_sample_prs`](@ref), see also [`PRS.generate_sample_dcftp`](@ref) and [`PRS.generate_sample_grid_prs`](@ref).
+Default sampler is [`PRS.generate_sample_prs`](@ref).
+
+**See also**
+- [`PRS.generate_sample_dcftp`](@ref)
+- [`PRS.generate_sample_grid_prs`](@ref).
 """
 function generate_sample(
-        pp::HardCorePointProcess{T};
-        win::Union{Nothing,AbstractWindow}=nothing,
-        rng=-1
+    pp::HardCorePointProcess{T};
+    win::Union{Nothing,AbstractWindow}=nothing,
+    rng=-1
 )::Vector{T} where {T}
     return generate_sample_prs(pp; win=win, rng=rng)
 end
 
 ### dominated CFTP, see dominated_cftp.jl
 
+"""
+    isrepulsive(pp::HardCorePointProcess) = true
+"""
 isrepulsive(pp::HardCorePointProcess) = true
+
+"""
+    isattractive(pp::HardCorePointProcess) = false
+"""
 isattractive(pp::HardCorePointProcess) = false
 
-function papangelou_conditional_intensity(
+@doc raw"""
+    papangelou_conditional_intensity(
         pp::HardCorePointProcess{Vector{T}},
         x::AbstractVector{T},
         X::Union{AbstractVector{Vector{T}},AbstractSet{Vector{T}}}
+    )::Real where {T}
+
+Compute
+```math
+    \beta
+    \prod_{y\in X} 1_{\left\| x - y \right\|_2 > r\}},
+```
+where ``\beta=`` `pp.β`` and ``r=`` `pp.r`.
+"""
+function papangelou_conditional_intensity(
+    pp::HardCorePointProcess{Vector{T}},
+    x::AbstractVector{T},
+    X::Union{AbstractVector{Vector{T}},AbstractSet{Vector{T}}}
 )::Real where {T}
     x in X && return 0.0
     β, r = intensity(pp), interaction_range(pp)
     return β * !any(Distances.euclidean(x, y) <= r for y in X)
 end
 
+"""
+    upper_bound_papangelou_conditional_intensity(pp::HardCorePointProcess) = intensity(pp)
+"""
 upper_bound_papangelou_conditional_intensity(pp::HardCorePointProcess) = intensity(pp)
 
 ### Partial Rejection Sampling
@@ -126,9 +167,9 @@ Compute the pairwise Gibbs interaction for a [`PRS.HardCorePointProcess`](@ref)
 ```
 """
 function gibbs_interaction(
-        pp::HardCorePointProcess{T},
-        cell1::SpatialCellGridPRS{T},
-        cell2::SpatialCellGridPRS{T},
+    pp::HardCorePointProcess{T},
+    cell1::SpatialCellGridPRS{T},
+    cell2::SpatialCellGridPRS{T},
 )::Real where {T}
     (isempty(cell1) || isempty(cell2)) && return 1.0
     r = interaction_range(pp)