deprecate sprandbool + add new syntax for creating random sparse matrix (#16098)

* deprecate sprandbool and add new syntax for creating random sparse matrix

* remove documentation for sprandbool

Author: KristofferC

base/deprecated.jl

@@ -1075,6 +1075,13 @@ end
 @deprecate copy(x::AbstractString)  identity(x)
 @deprecate copy(x::Tuple)  identity(x)
 
+@deprecate sprandbool(m::Integer, n::Integer, density::AbstractFloat) sprand(Bool, m, n, density)
+@deprecate sprandbool(r::AbstractRNG, m::Integer, n::Integer, density::AbstractFloat) sprand(r, Bool, m, n, density)
+@deprecate sprandbool(n::Integer, density::AbstractFloat) sprand(Bool, n, density)
+@deprecate sprandbool(r::AbstractRNG, n::Integer, density::AbstractFloat) sprand(r, Bool, n, density)
+@deprecate sprand{T}(n::Integer, density::AbstractFloat, ::Type{T}) sprand(T, n, density)
+@deprecate sprand{T}(r::AbstractRNG, n::Integer, density::AbstractFloat, ::Type{T}) sprand(r, T, n, density)
+
 # During the 0.5 development cycle, do not add any deprecations below this line
 # To be deprecated in 0.6
 

base/exports.jl

@@ -1459,7 +1459,6 @@ export
     speye,
     spones,
     sprand,
-    sprandbool,
     sprandn,
     spzeros,
     symperm,

base/sparse.jl

@@ -31,7 +31,7 @@ import Base.Broadcast: eltype_plus, broadcast_shape
 export AbstractSparseArray, AbstractSparseMatrix, AbstractSparseVector,
     SparseMatrixCSC, SparseVector, blkdiag, dense, droptol!, dropzeros!, etree,
     issparse, nonzeros, nzrange, rowvals, sparse, sparsevec, spdiagm, speye, spones,
-    sprand, sprandbool, sprandn, spzeros, symperm, nnz
+    sprand, sprandn, spzeros, symperm, nnz
 
 include("sparse/abstractsparse.jl")
 include("sparse/sparsematrix.jl")

base/sparse/sparsematrix.jl

@@ -894,12 +894,12 @@ function sprand_IJ(r::AbstractRNG, m::Integer, n::Integer, density::AbstractFloa
 end
 
 """
-    sprand([rng],m,[n],p::AbstractFloat,[rfn])
+    sprand([rng],[type],m,[n],p::AbstractFloat,[rfn])
 
 Create a random length `m` sparse vector or `m` by `n` sparse matrix, in
 which the probability of any element being nonzero is independently given by
 `p` (and hence the mean density of nonzeros is also exactly `p`). Nonzero
-values are sampled from the distribution specified by `rfn`. The uniform
+values are sampled from the distribution specified by `rfn` and have the type `type`. The uniform
 distribution is used in case `rfn` is not specified. The optional `rng`
 argument specifies a random number generator, see [Random Numbers](:ref:`Random Numbers <random-numbers>`).
 """
@@ -923,30 +923,27 @@ function sprand{T}(m::Integer, n::Integer, density::AbstractFloat,
     sparse_IJ_sorted!(I, J, rfn(length(I)), m, n, +)  # it will never need to combine
 end
 
-sprand(r::AbstractRNG, m::Integer, n::Integer, density::AbstractFloat) = sprand(r,m,n,density,rand,Float64)
+truebools(r::AbstractRNG, n::Integer) = ones(Bool, n)
+
 sprand(m::Integer, n::Integer, density::AbstractFloat) = sprand(GLOBAL_RNG,m,n,density)
-sprandn(r::AbstractRNG, m::Integer, n::Integer, density::AbstractFloat) = sprand(r,m,n,density,randn,Float64)
+
+sprand(r::AbstractRNG, m::Integer, n::Integer, density::AbstractFloat) = sprand(r,m,n,density,rand,Float64)
+sprand{T}(r::AbstractRNG, ::Type{T}, m::Integer, n::Integer, density::AbstractFloat) = sprand(r,m,n,density,(r, i) -> rand(r, T, i), T)
+sprand(r::AbstractRNG, ::Type{Bool}, m::Integer, n::Integer, density::AbstractFloat) = sprand(r,m,n,density, truebools, Bool)
+sprand{T}(::Type{T}, m::Integer, n::Integer, density::AbstractFloat) = sprand(GLOBAL_RNG, T, m, n, density)
+
 
 """
-    sprandn(m[,n],p::AbstractFloat)
+    sprandn([rng], m[,n],p::AbstractFloat)
 
 Create a random sparse vector of length `m` or sparse matrix of size `m` by `n`
 with the specified (independent) probability `p` of any entry being nonzero,
-where nonzero values are sampled from the normal distribution.
-"""
-sprandn( m::Integer, n::Integer, density::AbstractFloat) = sprandn(GLOBAL_RNG,m,n,density)
-
-truebools(r::AbstractRNG, n::Integer) = ones(Bool, n)
-sprandbool(r::AbstractRNG, m::Integer, n::Integer, density::AbstractFloat) = sprand(r,m,n,density,truebools,Bool)
-
+where nonzero values are sampled from the normal distribution. The optional `rng`
+argument specifies a random number generator, see [Random Numbers](:ref:`Random Numbers <random-numbers>`).
 """
-    sprandbool(m[,n],p)
+sprandn(r::AbstractRNG, m::Integer, n::Integer, density::AbstractFloat) = sprand(r,m,n,density,randn,Float64)
+sprandn(m::Integer, n::Integer, density::AbstractFloat) = sprandn(GLOBAL_RNG,m,n,density)
 
-Create a random `m` by `n` sparse boolean matrix or length `m` sparse boolean
-vector with the specified (independent) probability `p` of any entry being
-`true`.
-"""
-sprandbool(m::Integer, n::Integer, density::AbstractFloat) = sprandbool(GLOBAL_RNG,m,n,density)
 
 """
     spones(S)

base/sparse/sparsevector.jl

@@ -356,17 +356,16 @@ function sprand(r::AbstractRNG, n::Integer, p::AbstractFloat, rfn::Function)
     SparseVector(n, I, V)
 end
 
-sprand{T}(n::Integer, p::AbstractFloat, ::Type{T}) = sprand(GLOBAL_RNG, n, p, rand, T)
 sprand(n::Integer, p::AbstractFloat) = sprand(GLOBAL_RNG, n, p, rand)
-sprand{T}(r::AbstractRNG, n::Integer, p::AbstractFloat, ::Type{T}) = sprand(r, n, p, rand, T)
+
 sprand(r::AbstractRNG, n::Integer, p::AbstractFloat) = sprand(r, n, p, rand)
+sprand{T}(r::AbstractRNG, ::Type{T}, n::Integer, p::AbstractFloat) = sprand(r, n, p, (r, i) -> rand(r, T, i))
+sprand(r::AbstractRNG, ::Type{Bool}, n::Integer, p::AbstractFloat) = sprand(r, n, p, truebools)
+sprand{T}(::Type{T}, n::Integer, p::AbstractFloat) = sprand(GLOBAL_RNG, T, n, p)
 
 sprandn(n::Integer, p::AbstractFloat) = sprand(GLOBAL_RNG, n, p, randn)
 sprandn(r::AbstractRNG, n::Integer, p::AbstractFloat) = sprand(r, n, p, randn)
 
-sprandbool(n::Integer, p::AbstractFloat) = sprand(GLOBAL_RNG, n, p, truebools)
-sprandbool(r::AbstractRNG, n::Integer, p::AbstractFloat) = sprand(r, n, p, truebools)
-
 ## Indexing into Matrices can return SparseVectors
 
 # Column slices

contrib/BBEditTextWrangler-julia.plist

@@ -1070,7 +1070,6 @@
             <string>splitext</string>
             <string>spones</string>
             <string>sprand</string>
-            <string>sprandbool</string>
             <string>sprandn</string>
             <string>sprint</string>
             <string>spzeros</string>

doc/manual/arrays.rst

@@ -800,8 +800,3 @@ reference.
 |                                        |                                  | distribution. (Requires the                |
 |                                        |                                  | ``Distributions`` package.)                |
 +----------------------------------------+----------------------------------+--------------------------------------------+
-| :func:`sprandbool(m,n,d) <sprandbool>` | :func:`rand(Bool,m,n) <rand>`    | Creates a *m*-by-*n* random matrix (of     |
-|                                        |                                  | density *d*) with non-zero  ``Bool``       |
-|                                        |                                  | elements with probability *d* (*d* =0.5    |
-|                                        |                                  | for :func:`rand(Bool) <rand>`.)            |
-+----------------------------------------+----------------------------------+--------------------------------------------+

doc/stdlib/arrays.rst

@@ -940,23 +940,17 @@ dense counterparts. The following functions are specific to sparse arrays.
 
    Construct a sparse diagonal matrix. ``B`` is a tuple of vectors containing the diagonals and ``d`` is a tuple containing the positions of the diagonals. In the case the input contains only one diagonal, ``B`` can be a vector (instead of a tuple) and ``d`` can be the diagonal position (instead of a tuple), defaulting to 0 (diagonal). Optionally, ``m`` and ``n`` specify the size of the resulting sparse matrix.
 
-.. function:: sprand([rng],m,[n],p::AbstractFloat,[rfn])
+.. function:: sprand([rng],[type],m,[n],p::AbstractFloat,[rfn])
 
    .. Docstring generated from Julia source
 
-   Create a random length ``m`` sparse vector or ``m`` by ``n`` sparse matrix, in which the probability of any element being nonzero is independently given by ``p`` (and hence the mean density of nonzeros is also exactly ``p``\ ). Nonzero values are sampled from the distribution specified by ``rfn``\ . The uniform distribution is used in case ``rfn`` is not specified. The optional ``rng`` argument specifies a random number generator, see :ref:`Random Numbers <random-numbers>`\ .
+   Create a random length ``m`` sparse vector or ``m`` by ``n`` sparse matrix, in which the probability of any element being nonzero is independently given by ``p`` (and hence the mean density of nonzeros is also exactly ``p``\ ). Nonzero values are sampled from the distribution specified by ``rfn`` and have the type ``type``\ . The uniform distribution is used in case ``rfn`` is not specified. The optional ``rng`` argument specifies a random number generator, see :ref:`Random Numbers <random-numbers>`\ .
 
-.. function:: sprandn(m[,n],p::AbstractFloat)
+.. function:: sprandn([rng], m[,n],p::AbstractFloat)
 
    .. Docstring generated from Julia source
 
-   Create a random sparse vector of length ``m`` or sparse matrix of size ``m`` by ``n`` with the specified (independent) probability ``p`` of any entry being nonzero, where nonzero values are sampled from the normal distribution.
-
-.. function:: sprandbool(m[,n],p)
-
-   .. Docstring generated from Julia source
-
-   Create a random ``m`` by ``n`` sparse boolean matrix or length ``m`` sparse boolean vector with the specified (independent) probability ``p`` of any entry being ``true``\ .
+   Create a random sparse vector of length ``m`` or sparse matrix of size ``m`` by ``n`` with the specified (independent) probability ``p`` of any entry being nonzero, where nonzero values are sampled from the normal distribution. The optional ``rng`` argument specifies a random number generator, see :ref:`Random Numbers <random-numbers>`\ .
 
 .. function:: etree(A[, post])
 

test/perf/sparse/getindex.jl

@@ -95,7 +95,7 @@ function sparse_getindex_perf()
                     c = counters[sz]
                     if indstr=="logical array"
                         # make a logical array of the right size
-                        ind = sprandbool(size(m,1)..., 1e-5)
+                        ind = sprand(Bool, size(m,1)..., 1e-5)
                     end
                     if nargs==2
                         @timeit fun(m, ind)  "sparse_getindex_$s1$c" "Sparse matrix with $ms, $funstr with $indstr"
@@ -120,7 +120,7 @@ function sparse_getindex_perf()
                         continue # logical indexing with medium size sparse matrix takes too long
                     end
                     # make a logical array of the right size
-                    ind = sprandbool(size(m)..., 1e-5)
+                    ind = sprand(Bool, size(m)..., 1e-5)
                     c = counters[sz]
                     @timeit one_arg_indexing(m, ind) "sparse_getindex_$s1$c" "$s2 with $ms, linear indexing with $indstr"
                     counters[sz] += 1

test/sparsedir/sparse.jl

@@ -389,11 +389,11 @@ A = speye(Bool, 5)
 @test sprand(4,5,0.5).^0 == sparse(ones(4,5))
 
 # issue #5985
-@test sprandbool(4, 5, 0.0) == sparse(zeros(Bool, 4, 5))
-@test sprandbool(4, 5, 1.00) == sparse(ones(Bool, 4, 5))
+@test sprand(Bool, 4, 5, 0.0) == sparse(zeros(Bool, 4, 5))
+@test sprand(Bool, 4, 5, 1.00) == sparse(ones(Bool, 4, 5))
 sprb45nnzs = zeros(5)
 for i=1:5
-    sprb45 = sprandbool(4, 5, 0.5)
+    sprb45 = sprand(Bool, 4, 5, 0.5)
     @test length(sprb45) == 20
     sprb45nnzs[i] = sum(sprb45)[1]
 end
@@ -589,7 +589,7 @@ let A = speye(Int, 5), I=1:10, X=reshape([trues(10); falses(15)],5,5)
     @test A[I] == A[X] == collect(1:10)
 end
 
-let S = sprand(50, 30, 0.5, x->round(Int,rand(x)*100)), I = sprandbool(50, 30, 0.2)
+let S = sprand(50, 30, 0.5, x->round(Int,rand(x)*100)), I = sprand(Bool, 50, 30, 0.2)
     FS = full(S)
     FI = full(I)
     @test sparse(FS[FI]) == S[I] == S[FI]
@@ -973,7 +973,7 @@ end
 @test spzeros(1,2) .* spzeros(0,1)  == zeros(0,2)
 
 # test throws
-A = sprandbool(5,5,0.2)
+A = sprand(Bool, 5,5,0.2)
 @test_throws ArgumentError reinterpret(Complex128,A)
 @test_throws ArgumentError reinterpret(Complex128,A,(5,5))
 @test_throws DimensionMismatch reinterpret(Int8,A,(20,))
@@ -990,9 +990,9 @@ A = speye(5)
 @test convert(Matrix,A) == full(A)
 
 # test float
-A = sprandbool(5,5,0.0)
+A = sprand(Bool, 5,5,0.0)
 @test eltype(float(A)) == Float64  # issue #11658
-A = sprandbool(5,5,0.2)
+A = sprand(Bool, 5,5,0.2)
 @test float(A) == float(full(A))
 
 # test sparsevec
@@ -1319,3 +1319,12 @@ let
     @test issparse(UpperTriangular(full(m))) == false
     @test issparse(LinAlg.UnitUpperTriangular(full(m))) == false
 end
+
+let
+    m = sprand(Float32, 10, 10, 0.1)
+    @test eltype(m) == Float32
+    m = sprand(Float64, 10, 10, 0.1)
+    @test eltype(m) == Float64
+    m = sprand(Int32, 10, 10, 0.1)
+    @test eltype(m) == Int32
+end

test/sparsedir/sparsevector.jl

@@ -129,7 +129,7 @@ let xr = sprand(1000, 0.9)
     @test all(nonzeros(xr) .>= 0.0)
 end
 
-let xr = sprand(1000, 0.9, Float32)
+let xr = sprand(Float32, 1000, 0.9)
     @test isa(xr, SparseVector{Float32,Int})
     @test length(xr) == 1000
     @test all(nonzeros(xr) .>= 0.0)
@@ -143,7 +143,7 @@ let xr = sprandn(1000, 0.9)
     end
 end
 
-let xr = sprandbool(1000, 0.9)
+let xr = sprand(Bool, 1000, 0.9)
     @test isa(xr, SparseVector{Bool,Int})
     @test length(xr) == 1000
     @test all(nonzeros(xr))
@@ -152,7 +152,7 @@ end
 let r1 = MersenneTwister(), r2 = MersenneTwister()
     @test sprand(r1, 100, .9) == sprand(r2, 100, .9)
     @test sprandn(r1, 100, .9) == sprandn(r2, 100, .9)
-    @test sprandbool(r1, 100, .9) == sprandbool(r2, 100, .9)
+    @test sprand(r1, Bool, 100, .9, ) == sprand(r2,  Bool, 100, .9)
 end
 
 ### Element access