From 885bb7533e99005348817fff03b57bfe3e5d5c71 Mon Sep 17 00:00:00 2001
From: Lukas Schneiderbauer <lukas.schneiderbauer@gmail.com>
Date: Sat, 15 Jun 2024 12:08:09 +0200
Subject: [PATCH] be more elaborate with return value documentation, especially
 for as.data.frame()

---
 R/fcwt.R                             |  2 ++
 R/fcwtr_scalogram.R                  | 17 +++++++++++++++--
 man/as.data.frame.fcwtr_scalogram.Rd | 14 +++++++++++++-
 man/fcwt.Rd                          |  2 ++
 man/plot.fcwtr_scalogram.Rd          |  3 +++
 5 files changed, 35 insertions(+), 3 deletions(-)

diff --git a/R/fcwt.R b/R/fcwt.R
index 214ba7c..d056a71 100644
--- a/R/fcwt.R
+++ b/R/fcwt.R
@@ -60,6 +60,8 @@
 #' @return
 #'  The spectogram, a numeric real-valued matrix with dimensions
 #'  `dim = c(length(signal), n_freqs)`.
+#'  This matrix is wrapped into a S3-class `fcwtr_scalogram` so that plotting and
+#'  coercion functions can be used conveniently.
 #'
 #' @examples
 #' ts_sin_440 <- sin((1:5000) * 2 * pi * 440 / 44100)
diff --git a/R/fcwtr_scalogram.R b/R/fcwtr_scalogram.R
index 9f3c4e5..60e92ee 100644
--- a/R/fcwtr_scalogram.R
+++ b/R/fcwtr_scalogram.R
@@ -121,11 +121,23 @@ rm_na_time_slices <- function(x) {
 #'
 #' Internally, the scalogram resulting from [fcwt()] is represented by
 #' a numeric matrix. This method coerces this matrix into a reasonable
-#' data frame. It is associated to a certain runtime cost.
+#' data frame. Note that this conversion has a significant run time cost.
 #'
 #' @param x
 #'  An object resulting from [fcwt()].
 #'
+#' @return
+#'  A [data.frame()] object representing the scalogram data with four columns:
+#' \describe{
+#'   \item{time_ind}{An integer index uniquely identifying time slices.}
+#'   \item{time}{The time difference to the first time slice in physical units.
+#'               The time unit is the inverse of the frequency unit chosen by the user
+#'               for the `sample_freq` argument of [fcwt()].}
+#'   \item{freq}{The frequency in the same units as the `sample_freq` argument
+#'               of [fcwt()].}
+#'   \item{value}{The fCWT result for the particular time-frequency combination.}
+#' }
+#'
 #' @inheritParams base::as.data.frame
 #' @export
 as.data.frame.fcwtr_scalogram <- function(x, ...) {
@@ -136,7 +148,7 @@ as.data.frame.fcwtr_scalogram <- function(x, ...) {
 
   df[["time"]] <- df[["time_ind"]] / attr(x, "sample_freq")
 
-  df
+  df[, c("time_ind", "time", "freq", "value")]
 }
 
 #' Scalogram plotting
@@ -148,6 +160,7 @@ as.data.frame.fcwtr_scalogram <- function(x, ...) {
 #'  An object resulting from [fcwt()].
 #'
 #' @inheritParams autoplot.fcwtr_scalogram
+#' @return No return value, called for side effects.
 #'
 #' @importFrom graphics plot
 #' @export
diff --git a/man/as.data.frame.fcwtr_scalogram.Rd b/man/as.data.frame.fcwtr_scalogram.Rd
index 7ec6d26..bf5f21f 100644
--- a/man/as.data.frame.fcwtr_scalogram.Rd
+++ b/man/as.data.frame.fcwtr_scalogram.Rd
@@ -11,8 +11,20 @@
 
 \item{...}{additional arguments to be passed to or from methods.}
 }
+\value{
+A \code{\link[=data.frame]{data.frame()}} object representing the scalogram data with four columns:
+\describe{
+\item{time_ind}{An integer index uniquely identifying time slices.}
+\item{time}{The time difference to the first time slice in physical units.
+The time unit is the inverse of the frequency unit chosen by the user
+for the \code{sample_freq} argument of \code{\link[=fcwt]{fcwt()}}.}
+\item{freq}{The frequency in the same units as the \code{sample_freq} argument
+of \code{\link[=fcwt]{fcwt()}}.}
+\item{value}{The fCWT result for the particular time-frequency combination.}
+}
+}
 \description{
 Internally, the scalogram resulting from \code{\link[=fcwt]{fcwt()}} is represented by
 a numeric matrix. This method coerces this matrix into a reasonable
-data frame. It is associated to a certain runtime cost.
+data frame. Note that this conversion has a significant run time cost.
 }
diff --git a/man/fcwt.Rd b/man/fcwt.Rd
index 5d5eda9..37d41b4 100644
--- a/man/fcwt.Rd
+++ b/man/fcwt.Rd
@@ -53,6 +53,8 @@ Defaults to 2 threads (to accomodate CRAN requirements).}
 \value{
 The spectogram, a numeric real-valued matrix with dimensions
 \code{dim = c(length(signal), n_freqs)}.
+This matrix is wrapped into a S3-class \code{fcwtr_scalogram} so that plotting and
+coercion functions can be used conveniently.
 }
 \description{
 The core function of this package making use of the fcwt library. It processes
diff --git a/man/plot.fcwtr_scalogram.Rd b/man/plot.fcwtr_scalogram.Rd
index d1ec6b0..ce7c81a 100644
--- a/man/plot.fcwtr_scalogram.Rd
+++ b/man/plot.fcwtr_scalogram.Rd
@@ -15,6 +15,9 @@ steps that are plotted. Defaults to \code{n = 1000}.}
 
 \item{...}{other arguments passed to specific methods}
 }
+\value{
+No return value, called for side effects.
+}
 \description{
 Plots the scalogram resulting from \code{\link[=fcwt]{fcwt()}}.
 Requires \href{https://ggplot2.tidyverse.org/}{ggplot2}.