From 334d8d1f52ab8f742920077f8fe9b6e326651be2 Mon Sep 17 00:00:00 2001
From: Lukas Schneiderbauer <lukas.schneiderbauer@gmail.com>
Date: Mon, 6 Jan 2025 11:32:14 +0100
Subject: [PATCH] add `as_tibble()` doc and adjust `as.data.frame()` doc

---
 R/fcwtr_scalogram.R                  | 48 +++++++++++++++++++++++++---
 man/as.data.frame.fcwtr_scalogram.Rd | 10 +++---
 man/as_tibble.fcwtr_scalogram.Rd     | 48 ++++++++++++++++++++++++++++
 3 files changed, 97 insertions(+), 9 deletions(-)
 create mode 100644 man/as_tibble.fcwtr_scalogram.Rd

diff --git a/R/fcwtr_scalogram.R b/R/fcwtr_scalogram.R
index 02290fc..483b56e 100644
--- a/R/fcwtr_scalogram.R
+++ b/R/fcwtr_scalogram.R
@@ -294,15 +294,20 @@ print.fcwtr_scalogram <- function(x, ...) {
 }
 
 
-#' Coerce the scalogram matrix to a data frame
+#' Convert the scalogram matrix to a data frame
 #'
 #' Internally, the scalogram resulting from [fcwt()] is represented by
-#' a numeric matrix. This method coerces this matrix into a reasonable
-#' data frame. Note that this conversion has a significant run time cost.
+#' a numeric [matrix()]. This method converts this matrix into a three-columned
+#' [data.frame()] (two columns to represent the matrix indices, and one column
+#' for the corresponding value).
+#' Note that this conversion has a significant run time cost.
 #'
 #' @param x
 #'  An "fcwtr_scalogram" object resulting from [fcwt()].
 #'
+#' @param ...
+#'  Additional arguments are ignored.
+#'
 #' @return
 #'  A [data.frame()] object representing the scalogram data with four columns:
 #' \describe{
@@ -315,7 +320,6 @@ print.fcwtr_scalogram <- function(x, ...) {
 #'   \item{value}{The fCWT result for the particular time-frequency combination.}
 #' }
 #'
-#' @inheritParams base::as.data.frame
 #' @examples
 #' fcwt(
 #'   sin((1:5000) * 2 * pi * 440 / 44100),
@@ -343,11 +347,45 @@ as.data.frame.fcwtr_scalogram <- function(x, ...) {
   )
 }
 
+#' Convert the scalogram matrix to a tibble
+#'
+#' Internally, the scalogram resulting from [fcwt()] is represented by
+#' a numeric [matrix()]. This method converts this matrix into a three-columned
+#' [tibble::tibble()] (two columns to represent the matrix indices, and one column
+#' for the corresponding value).
+#' Note that this conversion has a significant run time cost.
+#'
+#' This method is conceptually identical to [as.data.frame()],
+#' it simply returns a [tibble::tibble()] instead of a [data.frame()].
+#'
+#' @return
+#'  A [tibble::tibble()] object representing the scalogram data with four columns:
+#' \describe{
+#'   \item{time_index}{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.}
+#' }
+#'
+#' @inherit as.data.frame.fcwtr_scalogram
+#' @examplesIf requireNamespace("tibble", quietly = TRUE)
+#' library(tibble)
+#'
+#' fcwt(
+#'   sin((1:5000) * 2 * pi * 440 / 44100),
+#'   x_sample_freq = u(44100, "Hz"),
+#'   n_freqs = 10
+#' ) |>
+#'   as_tibble()
+#'
 #' @exportS3Method tibble::as_tibble
 as_tibble.fcwtr_scalogram <- function(x, ...) {
   stopifnot(requireNamespace("tibble", quietly = TRUE))
 
-  tibble::as_tibble(as.data.frame(x))
+  tibble::as_tibble(as.data.frame(x, ...))
 }
 
 #' Extract the data matrix from a scalogram
diff --git a/man/as.data.frame.fcwtr_scalogram.Rd b/man/as.data.frame.fcwtr_scalogram.Rd
index 7b9ee73..53ea246 100644
--- a/man/as.data.frame.fcwtr_scalogram.Rd
+++ b/man/as.data.frame.fcwtr_scalogram.Rd
@@ -2,14 +2,14 @@
 % Please edit documentation in R/fcwtr_scalogram.R
 \name{as.data.frame.fcwtr_scalogram}
 \alias{as.data.frame.fcwtr_scalogram}
-\title{Coerce the scalogram matrix to a data frame}
+\title{Convert the scalogram matrix to a data frame}
 \usage{
 \method{as.data.frame}{fcwtr_scalogram}(x, ...)
 }
 \arguments{
 \item{x}{An "fcwtr_scalogram" object resulting from \code{\link[=fcwt]{fcwt()}}.}
 
-\item{...}{additional arguments to be passed to or from methods.}
+\item{...}{Additional arguments are ignored.}
 }
 \value{
 A \code{\link[=data.frame]{data.frame()}} object representing the scalogram data with four columns:
@@ -25,8 +25,10 @@ of \code{\link[=fcwt]{fcwt()}}.}
 }
 \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. Note that this conversion has a significant run time cost.
+a numeric \code{\link[=matrix]{matrix()}}. This method converts this matrix into a three-columned
+\code{\link[=data.frame]{data.frame()}} (two columns to represent the matrix indices, and one column
+for the corresponding value).
+Note that this conversion has a significant run time cost.
 }
 \examples{
 fcwt(
diff --git a/man/as_tibble.fcwtr_scalogram.Rd b/man/as_tibble.fcwtr_scalogram.Rd
new file mode 100644
index 0000000..a0f2b82
--- /dev/null
+++ b/man/as_tibble.fcwtr_scalogram.Rd
@@ -0,0 +1,48 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/fcwtr_scalogram.R
+\name{as_tibble.fcwtr_scalogram}
+\alias{as_tibble.fcwtr_scalogram}
+\title{Convert the scalogram matrix to a tibble}
+\usage{
+\method{as_tibble}{fcwtr_scalogram}(x, ...)
+}
+\arguments{
+\item{x}{An "fcwtr_scalogram" object resulting from \code{\link[=fcwt]{fcwt()}}.}
+
+\item{...}{Additional arguments are ignored.}
+}
+\value{
+A \code{\link[tibble:tibble]{tibble::tibble()}} object representing the scalogram data with four columns:
+\describe{
+\item{time_index}{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 \code{\link[=matrix]{matrix()}}. This method converts this matrix into a three-columned
+\code{\link[tibble:tibble]{tibble::tibble()}} (two columns to represent the matrix indices, and one column
+for the corresponding value).
+Note that this conversion has a significant run time cost.
+}
+\details{
+This method is conceptually identical to \code{\link[=as.data.frame]{as.data.frame()}},
+it simply returns a \code{\link[tibble:tibble]{tibble::tibble()}} instead of a \code{\link[=data.frame]{data.frame()}}.
+}
+\examples{
+\dontshow{if (requireNamespace("tibble", quietly = TRUE)) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf}
+library(tibble)
+
+fcwt(
+  sin((1:5000) * 2 * pi * 440 / 44100),
+  x_sample_freq = u(44100, "Hz"),
+  n_freqs = 10
+) |>
+  as_tibble()
+\dontshow{\}) # examplesIf}
+}