Skip to content

Commit

Permalink
Improve docstring style consistency
Browse files Browse the repository at this point in the history
  • Loading branch information
@nunofachada
nunofachada committed Jun 3, 2024
1 parent 587c6a4 commit cdc8ffa
Show file tree
Hide file tree
Showing 4 changed files with 54 additions and 54 deletions.
30 changes: 15 additions & 15 deletions src/core.jl
View file
Original file line number Diff line number Diff line change
@@ -1,13 +1,13 @@
# Copyright (c) 2020-2023 Nuno Fachada, Diogo de Andrade, and contributors
# Copyright (c) 2020-2024 Nuno Fachada, Diogo de Andrade, and contributors
# Distributed under the MIT License (See accompanying file LICENSE or copy
# at http://opensource.org/licenses/MIT)

"""
points_on_line(
center::AbstractArray{<:Real, 1},
direction::AbstractArray{<:Real, 1},
dist_center::AbstractArray{<:Real, 1}
) -> AbstractArray{<:Real, 2}
center::AbstractArray{<:Real,1},
direction::AbstractArray{<:Real,1},
dist_center::AbstractArray{<:Real,1}
) -> AbstractArray{<:Real,2}
Determine coordinates of points on a line with `center` and `direction`, based
on the distances from the center given in `dist_center`.
Expand All @@ -27,15 +27,15 @@ line, and ``\\mathbf{1}`` is a ``p \\times 1`` vector with all entries equal to
# Examples
```jldoctest
julia> points_on_line([5.0,5.0], [1.0,0.0], -4:2:4) # 2D, 5 points
julia> points_on_line([5.0, 5.0], [1.0, 0.0], -4:2:4) # 2D, 5 points
5×2 Matrix{Float64}:
1.0 5.0
3.0 5.0
5.0 5.0
7.0 5.0
9.0 5.0
julia> points_on_line([-2.0,0,0,2.0], [0,0,-1.0,0], [10,-10]) # 4D, 2 points
julia> points_on_line([-2.0, 0, 0, 2.0], [0, 0, -1.0, 0], [10, -10]) # 4D, 2 points
2×4 Matrix{Float64}:
-2.0 0.0 -10.0 2.0
-2.0 0.0 10.0 2.0
Expand All @@ -51,24 +51,24 @@ end

"""
rand_ortho_vector(
u::AbstractArray{<:Real, 1};
rng::AbstractRNG = Random.GLOBAL_RNG
) -> AbstractArray{<:Real, 1}
u::AbstractArray{<:Real,1};
rng::AbstractRNG=Random.GLOBAL_RNG
) -> AbstractArray{<:Real,1}
Get a random unit vector orthogonal to `u`.
Note that `u` is expected to be a unit vector itself.
# Examples
```jldoctest; setup = :(using LinearAlgebra, Random; Random.seed!(111))
julia> u = normalize([1,2,5.0,-3,-0.2]); # Define a 5D unit vector
julia> u = normalize([1, 2, 5.0, -3, -0.2]); # Define a 5D unit vector
julia> v = rand_ortho_vector(u);
julia> ≈(dot(u, v), 0; atol=1e-15) # Vectors orthogonal? (needs LinearAlgebra package)
true
julia> rand_ortho_vector([1,0,0]; rng=MersenneTwister(567)) # 3D, reproducible
julia> rand_ortho_vector([1, 0, 0]; rng=MersenneTwister(567)) # 3D, reproducible
3-element Vector{Float64}:
0.0
-0.717797705156548
Expand Down Expand Up @@ -111,7 +111,7 @@ end
rand_unit_vector(
num_dims::Integer;
rng::AbstractRNG = Random.GLOBAL_RNG
) -> AbstractArray{<:Real, 1}
) -> AbstractArray{<:Real,1}
Get a random unit vector with `num_dims` dimensions.
Expand Down Expand Up @@ -143,10 +143,10 @@ end

"""
rand_vector_at_angle(
u::AbstractArray{<:Real, 1},
u::AbstractArray{<:Real,1},
angle::Real;
rng::AbstractRNG = Random.GLOBAL_RNG
) -> AbstractArray{<:Real, 1}
) -> AbstractArray{<:Real,1}
Get a random unit vector which is at `angle` radians of vector `u`.
Expand Down
18 changes: 9 additions & 9 deletions src/helper.jl
View file
Original file line number Diff line number Diff line change
@@ -1,9 +1,9 @@
# Copyright (c) 2020-2023 Nuno Fachada, Diogo de Andrade, and contributors
# Copyright (c) 2020-2024 Nuno Fachada, Diogo de Andrade, and contributors
# Distributed under the MIT License (See accompanying file LICENSE or copy
# at http://opensource.org/licenses/MIT)

"""
angle_btw(v1::AbstractArray{<:Real, 1}, v2::AbstractArray{<:Real, 1}) -> Real
angle_btw(v1::AbstractArray{<:Real,1}, v2::AbstractArray{<:Real,1}) -> Real
Angle between two ``n``-dimensional vectors.
Expand Down Expand Up @@ -40,9 +40,9 @@ end

"""
CluGen.clupoints_n_1_template(
projs::AbstractArray{<:Real, 2},
projs::AbstractArray{<:Real,2},
lat_disp::Real,
clu_dir::AbstractArray{<:Real, 1},
clu_dir::AbstractArray{<:Real,1},
dist_fn::Function;
rng::AbstractRNG = Random.GLOBAL_RNG
) -> AbstractArray{<:Real}
Expand Down Expand Up @@ -106,9 +106,9 @@ end

"""
fix_empty!(
clu_num_points::AbstractArray{<:Integer, 1},
allow_empty::Bool = false
) -> AbstractArray{<:Integer, 1}
clu_num_points::AbstractArray{<:Integer,1},
allow_empty::Bool=false
) -> AbstractArray{<:Integer,1}
Certifies that, given enough points, no clusters are left empty. This is done by
removing a point from the largest cluster and adding it to an empty cluster while
Expand Down Expand Up @@ -153,9 +153,9 @@ end

"""
fix_num_points!(
clu_num_points::AbstractArray{<:Integer, 1},
clu_num_points::AbstractArray{<:Integer,1},
num_points::Integer
) -> AbstractArray{<:Integer, 1}
) -> AbstractArray{<:Integer,1}
Certifies that the values in the `clu_num_points` array, i.e. the number of
points in each cluster, add up to `num_points`. If this is not the case, the
Expand Down
26 changes: 13 additions & 13 deletions src/main.jl
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,20 +9,20 @@
num_points::Integer,
direction::AbstractArray{<:Real},
angle_disp::Real,
cluster_sep::AbstractArray{<:Real, 1},
cluster_sep::AbstractArray{<:Real,1},
llength::Real,
llength_disp::Real,
lateral_disp::Real;
# Keyword arguments
allow_empty::Bool = false,
cluster_offset::Union{AbstractArray{<:Real, 1}, Nothing} = nothing,
proj_dist_fn::Union{String, <:Function} = "norm",
point_dist_fn::Union{String, <:Function} = "n-1",
clusizes_fn::Union{<:Function, AbstractArray{<:Real, 1}} = GluGen.clusizes,
clucenters_fn::Union{<:Function, AbstractArray{<:Real}} = GluGen.clucenters,
llengths_fn::Union{<:Function, AbstractArray{<:Real, 1}} = GluGen.llengths,
angle_deltas_fn::Union{<:Function, AbstractArray{<:Real, 1}} = GluGen.angle_deltas,
rng::Union{Integer, AbstractRNG}=Random.GLOBAL_RNG
cluster_offset::Union{AbstractArray{<:Real,1},Nothing} = nothing,
proj_dist_fn::Union{String,<:Function} = "norm",
point_dist_fn::Union{String,<:Function} = "n-1",
clusizes_fn::Union{<:Function,AbstractArray{<:Real,1}} = GluGen.clusizes,
clucenters_fn::Union{<:Function,AbstractArray{<:Real}} = GluGen.clucenters,
llengths_fn::Union{<:Function,AbstractArray{<:Real,1}} = GluGen.llengths,
angle_deltas_fn::Union{<:Function,AbstractArray{<:Real,1}} = GluGen.angle_deltas,
rng::Union{Integer,AbstractRNG}=Random.GLOBAL_RNG
) -> NamedTuple{(
:points, # Array{<:Real,2}
:clusters, # Array{<:Integer,1}
Expand Down Expand Up @@ -145,7 +145,7 @@ possible that `num_points` may have a different value than what was specified in
```jldoctest; setup = :(using Random; Random.seed!(123))
julia> # Create 5 clusters in 3D space with a total of 10000 points...
julia> out = clugen(3, 5, 10000, [0.5, 0.5, 0.5], pi/16, [10, 10, 10], 10, 1, 2);
julia> out = clugen(3, 5, 10000, [0.5, 0.5, 0.5], pi / 16, [10, 10, 10], 10, 1, 2);
julia> out.centers # What are the cluster centers?
5×3 Matrix{Float64}:
Expand All @@ -159,7 +159,7 @@ julia> out.centers # What are the cluster centers?
The following instruction displays a scatter plot of the clusters in 3D space:
```julia-repl
julia> plot(out.points[:,1], out.points[:,2], out.points[:,3], seriestype = :scatter, group=out.point_clusters)
julia> plot(out.points[:, 1], out.points[:, 2], out.points[:, 3], seriestype=:scatter, group=out.point_clusters)
```
Check the [Examples](@ref) section for a number of illustrative examples on how to
Expand Down Expand Up @@ -482,7 +482,7 @@ end
fields::Tuple{Vararg{Symbol}}=(:points, :clusters),
clusters_field::Union{Symbol,Nothing}=:clusters,
output_type::Symbol=:NamedTuple
) -> Union{NamedTuple, Dict}
) -> Union{NamedTuple,Dict}
Merges the fields (specified in `fields`) of two or more `data` sets (named tuples
or dictionaries). The fields to be merged need to have the same number of columns.
Expand Down Expand Up @@ -513,7 +513,7 @@ julia> clu_data = clugen(2, 5, 1000, [1, 1], 0.01, [20, 20], 14, 1.2, 1.5);
julia> # Generate 500 points of random uniform noise
julia> noise = (points=120 * rand(500, 2) .- 60, clusters = ones(Int32, 500));
julia> noise = (points=120 * rand(500, 2) .- 60, clusters=ones(Int32, 500));
julia> # Create a new data set with the clugen()-generated data plus the noise
Expand Down
34 changes: 17 additions & 17 deletions src/module.jl
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@
num_clusters::Integer,
angle_disp::Real;
rng::AbstractRNG = Random.GLOBAL_RNG
) -> AbstractArray{<:Real, 1}
) -> AbstractArray{<:Real,1}
Determine the angles between the average cluster direction and the
cluster-supporting lines. These angles are obtained from a wrapped normal
Expand All @@ -24,14 +24,14 @@ if invoked by user code.
# Examples
```jldoctest; setup = :(using Random; Random.seed!(111))
julia> CluGen.angle_deltas(4, pi/128)
julia> CluGen.angle_deltas(4, pi / 128)
4-element Vector{Float64}:
0.01888791855096079
-0.027851298321307266
0.03274154825228485
-0.004475798744567242
julia> CluGen.angle_deltas(3, pi/32; rng=MersenneTwister(987)) # Reproducible
julia> CluGen.angle_deltas(3, pi / 32; rng=MersenneTwister(987)) # Reproducible
3-element Vector{Float64}:
0.08834204306583336
0.014678748091943444
Expand Down Expand Up @@ -65,8 +65,8 @@ end
"""
clucenters(
num_clusters::Integer,
clu_sep::AbstractArray{<:Real, 1},
clu_offset::AbstractArray{<:Real, 1};
clu_sep::AbstractArray{<:Real,1},
clu_offset::AbstractArray{<:Real,1};
rng::AbstractRNG = Random.GLOBAL_RNG
) -> AbstractArray{<:Real}
Expand Down Expand Up @@ -129,11 +129,11 @@ end

"""
CluGen.clupoints_n_1(
projs::AbstractArray{<:Real, 2},
projs::AbstractArray{<:Real,2},
lat_disp::Real,
line_len::Real,
clu_dir::AbstractArray{<:Real, 1},
clu_ctr::AbstractArray{<:Real, 1};
clu_dir::AbstractArray{<:Real,1},
clu_ctr::AbstractArray{<:Real,1};
rng::AbstractRNG = Random.GLOBAL_RNG
) -> AbstractArray{<:Real}
Expand All @@ -158,15 +158,15 @@ if invoked by user code.
# Examples
```jldoctest; setup = :(using Random)
julia> projs = points_on_line([5.0,5.0], [1.0,0.0], -4:2:4) # Get 5 point projections on a 2D line
julia> projs = points_on_line([5.0, 5.0], [1.0, 0.0], -4:2:4) # Get 5 point projections on a 2D line
5×2 Matrix{Float64}:
1.0 5.0
3.0 5.0
5.0 5.0
7.0 5.0
9.0 5.0
julia> CluGen.clupoints_n_1(projs, 0.5, 1.0, [1,0], [0,0]; rng=MersenneTwister(123))
julia> CluGen.clupoints_n_1(projs, 0.5, 1.0, [1, 0], [0, 0]; rng=MersenneTwister(123))
5×2 Matrix{Float64}:
1.0 5.59513
3.0 3.97591
Expand Down Expand Up @@ -194,11 +194,11 @@ end

"""
GluGen.clupoints_n(
projs::AbstractArray{<:Real, 2},
projs::AbstractArray{<:Real,2},
lat_disp::Real,
line_len::Real,
clu_dir::AbstractArray{<:Real, 1},
clu_ctr::AbstractArray{<:Real, 1};
clu_dir::AbstractArray{<:Real,1},
clu_ctr::AbstractArray{<:Real,1};
rng::AbstractRNG = Random.GLOBAL_RNG
) -> AbstractArray{<:Real}
Expand All @@ -223,15 +223,15 @@ if invoked by user code.
# Examples
```jldoctest; setup = :(using Random)
julia> projs = points_on_line([5.0,5.0], [1.0,0.0], -4:2:4) # Get 5 point projections on a 2D line
julia> projs = points_on_line([5.0, 5.0], [1.0, 0.0], -4:2:4) # Get 5 point projections on a 2D line
5×2 Matrix{Float64}:
1.0 5.0
3.0 5.0
5.0 5.0
7.0 5.0
9.0 5.0
julia> CluGen.clupoints_n(projs, 0.5, 1.0, [1,0], [0,0]; rng=MersenneTwister(123))
julia> CluGen.clupoints_n(projs, 0.5, 1.0, [1, 0], [0, 0]; rng=MersenneTwister(123))
5×2 Matrix{Float64}:
1.59513 4.66764
4.02409 5.49048
Expand Down Expand Up @@ -270,7 +270,7 @@ end
num_points::Integer,
allow_empty::Bool;
rng::AbstractRNG = Random.GLOBAL_RNG
) -> AbstractArray{<:Integer, 1}
) -> AbstractArray{<:Integer,1}
Determine cluster sizes, i.e., the number of points in each cluster, using the
normal distribution (μ=`num_points`/`num_clusters`, σ=μ/3), and then assuring
Expand Down Expand Up @@ -352,7 +352,7 @@ end
llength::Real,
llength_disp::Real;
rng::AbstractRNG = Random.GLOBAL_RNG
) -> AbstractArray{<:Real, 1}
) -> AbstractArray{<:Real,1}
Determine length of cluster-supporting lines using the folded normal distribution
(μ=`llength`, σ=`llength_disp`).
Expand Down

0 comments on commit cdc8ffa

Please sign in to comment.