[WIP] rename plotting functions and improve their documentation (#62)

* renames

bit more concistent names:
```
recurrencetext, recurrencescatter, recurrenceplot
```
also exporting `recurrencescatter`, because I want to put this to the docs as well.

* different names and abit more detail in docstrings

* fix tests

* change all x to R in rqa docs 

for documentation purposes

* correct quotes indocstrings

Author: Datseris

NEWS.md

@@ -1,5 +1,11 @@
 # RecurrenceAnalysis.jl News
 
+## v0.12.0
+- Doc improvements
+- Return type changes in `rqa`
+- Breaking changes in implementations of `trend` and denominator of "RR"
+- name changes in plotting
+
 ## v0.10.0
 - Theiler window now has default values that depend on the type: `CrossRecurrenceMatrix` has default 0, otherwise 1.
 

src/matrices.jl

@@ -141,6 +141,7 @@ colvals(x::ARM) = colvals(x.data)
     RecurrenceMatrix(x, ε; kwargs...)
 
 Create a recurrence matrix from trajectory `x`.
+Objects of type `<:AbstractRecurrenceMatrix` are displayed as a [`recurrenceplot`](@ref).
 
 ## Description
 

src/plot.jl

@@ -1,11 +1,13 @@
+using UnicodePlots
+export recurrenceplot, coordinates, grayscale
 #########################################
 # Text-based plotting
 #########################################
 """
-    scatterdata(R::ARM) -> xs, ys
-Transform the data of a recurrence matrix to scatter data `xs, ys`.
+    coordinates(R) -> xs, ys
+Return the coordinates of the recurrence points of `R` (in indices).
 """
-function scatterdata(R::ARM) # TODO: scan every ÷100 elements depending on size?
+function coordinates(R::ARM) # TODO: allow scan every ÷100 elements?
    rows = rowvals(R)
    is = zeros(Int, nnz(R))
    js = zeros(Int, nnz(R))
@@ -21,16 +23,14 @@ function scatterdata(R::ARM) # TODO: scan every ÷100 elements depending on size
    return is, js
 end
 
-using UnicodePlots
-export textrecurrenceplot
-
-textrecurrenceplot(R::ARM; kwargs...) = textrecurrenceplot(stdout, R::ARM; kwargs...)
+recurrenceplot(R::ARM; kwargs...) = recurrenceplot(stdout, R::ARM; kwargs...)
 
 """
-    textrecurrenceplot([io,] R; minh = 25, maxh = 0.5, ascii, kwargs...) -> u
+    recurrenceplot([io,] R; minh = 25, maxh = 0.5, ascii, kwargs...) -> u
 
-Obtain a text-scatterplot representation of a recurrence matrix `R` to be displayed in
-`io` (by default `stdout`). The matrix spans at minimum `minh` rows and at maximum
+Create a text-based scatterplot representation of a recurrence matrix `R` to be displayed in
+`io` (by default `stdout`) using `UnicodePlots`.
+The matrix spans at minimum `minh` rows and at maximum
 `maxh*displaysize(io)[1]` (i.e. by default half the display).
 As we always try to plot in equal aspect ratio, if the width of the plot is even less,
 the minimum height is dictated by the width.
@@ -40,10 +40,11 @@ The keyword `ascii::Bool` can ensure that all elements of the plot are ASCII cha
 
 The rest of the `kwargs` are propagated into `UnicodePlots.scatterplot`.
 
-Internally this function calls `RecurrenceAnalysis.scatterdata` to transform
-a recurrence matrix into scatter data.
+Notice that the accuracy of this function drops drastically for matrices whose size
+is significantly bigger than the width and height of the display (assuming each
+index of the matrix is one character).
 """
-function textrecurrenceplot(io::IO, R::ARM; minh = 25, maxh = 0.5, ascii = nothing, kwargs...)
+function recurrenceplot(io::IO, R::ARM; minh = 25, maxh = 0.5, ascii = nothing, kwargs...)
     @assert maxh ≤ 1
     h, w = displaysize(io)
     h = max(minh, round(Int, maxh * h)) # make matrix as long as half the screen (but not too short)
@@ -54,7 +55,7 @@ function textrecurrenceplot(io::IO, R::ARM; minh = 25, maxh = 0.5, ascii = nothi
         w = round(Int, h*s)
     end
 
-    is, js = scatterdata(R)
+    is, js = coordinates(R)
     n, m = size(R)
 
     if ascii == true
@@ -85,7 +86,7 @@ function textrecurrenceplot(io::IO, R::ARM; minh = 25, maxh = 0.5, ascii = nothi
 end
 
 function Base.show(io::IO, ::MIME"text/plain", R::ARM)
-    a = textrecurrenceplot(io, R)
+    a = recurrenceplot(io, R)
     show(io, a)
 end
 
@@ -103,7 +104,7 @@ function checkgridsize(width::T, height::T, dims::Tuple{T,T}) where T<:Integer
                      (height,width-1) => height/(width-1))
     distances = Dict(d=>(r-ratio) for (d,r) in intratios)
     distancesigns = sign.(collect(values(distances)))
-    if all(x -> x >= 0, distancesigns) || all(x -> x <= 0, distancesigns)
+    if all(R -> R >= 0, distancesigns) || all(R -> R <= 0, distancesigns)
         width_adj = round(Integer, height*dims[1]/dims[2])
         height_adj = round(Integer, width*dims[2]/dims[1])
         width = min(width, width_adj)
@@ -124,21 +125,19 @@ function overlapgrid(m::T, n::T) where T<:Integer
 end
 
 # Calculate the level of "gray" (0=white, 1=black) corresponding to a matrix block
-function block2grayscale(x, rind::Tuple{T,T}, cind::Tuple{T,T}) where T<:Integer
-    submat = @view x[rind[1]:rind[2], cind[1]:cind[2]]
+function block2grayscale(R, rind::Tuple{T,T}, cind::Tuple{T,T}) where T<:Integer
+    submat = @view R[rind[1]:rind[2], cind[1]:cind[2]]
     ratio = count(!iszero, submat)/prod(size(submat))
 end
 
 """
-    recurrenceplot(x [, bwcode]; width::Int, height::Int, exactsize=false)
+    grayscale(R [, bwcode]; width::Int, height::Int, exactsize=false)
 
-Transform the recurrence matrix `x` into a full matrix suitable for plotting as a
-grayscale image. By default it returns a matrix with the same size as `x`,
+Transform the recurrence matrix `R` into a full matrix suitable for plotting as a
+grayscale image. By default it returns a matrix with the same size as `R`,
 but switched axes, containing "black" values in the cells that represent recurrent points,
-and "white" values in the empty cells.
-
-**This function does not do any plotting!** You have to use the return value with
-the plotting library of your choice.
+and "white" values in the empty cells and interpolating in-between for cases with
+both recurrent and empty cells, see below.
 
 The numeric codes for black and white are given in a 2-element tuple as a second
 optional argument. Its default value is `(0.0, 1.0)`, i.e. black is coded as `0.0`
@@ -155,28 +154,31 @@ proportional to the original matrix, such that the returned matrix fits into a
 matrix of the given dimensions. This automatic adjustment can be disabled by
 passing the keyword argument `exactsize=true`.
 
-If the image has different dimensions than `x`, the cells of `x` are distributed
+If the image has different dimensions than `R`, the cells of `R` are distributed
 in a grid with the size of the image, and a gray level between white and black
 is calculated for each element of the grid, proportional to the number of
 recurrent points contained in it. The levels of gray are coded as numbers of the
 same type as the black and white codes.
+
+It is advised to use `width, height` arguments for large matrices otherwise
+plots using functions like e.g. `imshow` could be misleading.
 """
-function recurrenceplot(x, bwcode::Tuple{TT,T}=(0.0,1.0);
+function grayscale(R, bwcode::Tuple{TT,T}=(0.0,1.0);
     exactsize=false, kwargs...) where {TT<:Real, T<:Real}
 
-    dims = size(x)
+    dims = size(R)
     kwargs = Dict(kwargs)
     if haskey(kwargs, :width) && !haskey(kwargs, :height)
         width = Integer(kwargs[:width])
         height = round(Integer, width*dims[2]/dims[1])
-        return recurrenceplot(x, bwcode; width=width, height=height)
+        return grayscale(R, bwcode; width=width, height=height)
     elseif haskey(kwargs, :height) && !haskey(kwargs, :width)
         height = Integer(kwargs[:height])
         width = round(Integer, height*dims[1]/dims[2])
-        return recurrenceplot(x, bwcode; width=width, height=height)
+        return grayscale(R, bwcode; width=width, height=height)
     elseif !haskey(kwargs, :width) || !haskey(kwargs, :height)
         width, height = Integer.(dims)
-        return recurrenceplot(x, bwcode; width=width, height=height)
+        return grayscale(R, bwcode; width=width, height=height)
     end
     if exactsize
         width, height = Integer(kwargs[:width]), Integer(kwargs[:height])
@@ -190,7 +192,7 @@ function recurrenceplot(x, bwcode::Tuple{TT,T}=(0.0,1.0);
     p = zeros(height, width)
     # Fill img switching dimensions
     for c=1:width, r=1:height
-        p[r,c] = block2grayscale(x, rows[c], cols[end-r+1])
+        p[r,c] = block2grayscale(R, rows[c], cols[end-r+1])
     end
     # Normalize values
     p ./= maximum(p)