From cdc8ffac03297add180d392499cffa8cdf339d4d Mon Sep 17 00:00:00 2001 From: Nuno Fachada Date: Mon, 3 Jun 2024 18:56:38 +0100 Subject: [PATCH] Improve docstring style consistency --- src/core.jl | 30 +++++++++++++++--------------- src/helper.jl | 18 +++++++++--------- src/main.jl | 26 +++++++++++++------------- src/module.jl | 34 +++++++++++++++++----------------- 4 files changed, 54 insertions(+), 54 deletions(-) diff --git a/src/core.jl b/src/core.jl index 69a46fe..3570b30 100644 --- a/src/core.jl +++ b/src/core.jl @@ -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`. @@ -27,7 +27,7 @@ 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 @@ -35,7 +35,7 @@ julia> points_on_line([5.0,5.0], [1.0,0.0], -4:2:4) # 2D, 5 points 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 @@ -51,9 +51,9 @@ 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`. @@ -61,14 +61,14 @@ 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 @@ -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. @@ -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`. diff --git a/src/helper.jl b/src/helper.jl index 330ca2b..d74cf11 100644 --- a/src/helper.jl +++ b/src/helper.jl @@ -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. @@ -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} @@ -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 @@ -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 diff --git a/src/main.jl b/src/main.jl index 4a13231..3686468 100644 --- a/src/main.jl +++ b/src/main.jl @@ -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} @@ -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}: @@ -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 @@ -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. @@ -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 diff --git a/src/module.jl b/src/module.jl index 590a749..dc3e60f 100644 --- a/src/module.jl +++ b/src/module.jl @@ -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 @@ -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 @@ -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} @@ -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} @@ -158,7 +158,7 @@ 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 @@ -166,7 +166,7 @@ julia> projs = points_on_line([5.0,5.0], [1.0,0.0], -4:2:4) # Get 5 point projec 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 @@ -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} @@ -223,7 +223,7 @@ 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 @@ -231,7 +231,7 @@ julia> projs = points_on_line([5.0,5.0], [1.0,0.0], -4:2:4) # Get 5 point projec 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 @@ -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 @@ -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`).