update sigma vignette

vignettes/sigma.Rmd

@@ -21,7 +21,7 @@ In contrast to the [Short Time Fourier Transform](https://en.wikipedia.org/wiki/
 
 [^1]: That is of course one of the selling points of the CWT: it works for all frequency ranges, while the fixed window size in the Short Time Fourier Transform will break down when probing modes whose wavelength approach the window size, at the same time it lacks a reasonable time resolutions for modes whose wavelength is much smaller than the window size.
 
-For a particular time $t$ and a reference frequency $f$, the Gaussian envelope $g(t)$ of the wavelet is given by
+For a reference frequency $f$, the Gaussian envelope $g(t)$ of the wavelet is given by
 
 $$g(t) \sim e^{-\left( \frac{t f}{2 \Sigma} \right)^2}$$
 
@@ -31,47 +31,47 @@ The time-frequency uncertainty relation is true for any $\Sigma$ or frequency $f
 
 ## From uncertainty to resolution
 
-So what time and frequency resolution $\Delta t$ and $\Delta f$ can we expect from a certain value of $\Sigma$? The resolution is set by the Gaussian spread which in turn is quantified by the uncertainties $\sigma_t$ and $\sigma_f$.
+So which time and frequency resolution $\Delta t$ and $\Delta f$ can we expect from a certain value of $\Sigma$? The resolution is set by the Gaussian spread which in turn is quantified by the uncertainties $\sigma_t$ and $\sigma_f$.
 
-Interpreting the Gaussian as a window function, we expect that in order to achieve a certain resolution $\Delta_t$ the window size needs to be at least equal (or smaller) than $\Delta t$. Since a Gaussian has infinite support, we need to make a more or less arbitrary decision on where the exponential falloff of the Gaussian is close enough to zero for our liking.
+Interpreting the Gaussian as a window function, we expect that in order to achieve a certain resolution $\Delta_t$ the window size needs to be at least equal (or smaller) than $\Delta t$. Since a Gaussian has infinite support, we need to make a more or less arbitrary decision where the exponential falloff of the Gaussian is close enough to zero for our liking.
 
 [![Ainali, CC BY-SA 3.0 \<https://creativecommons.org/licenses/by-sa/3.0\>, via Wikimedia Commons](images/Standard_deviation_diagram.svg){width="100%"}](https://upload.wikimedia.org/wikipedia/commons/3/3a/Standard_deviation_diagram_micro.svg)
 
-In our case we decide that $4\,\sigma$ is the effective width of our window function, and so we expect an effective resolution of
+In our case, we decide that $4\,\sigma$ is the effective width of our window function, and so we expect an effective resolution of
 
-$$\Delta t:=4\frac{Σ}{f}$$
+$$\Delta t:=\frac{4Σ}{f}$$
 
 and
 
-$$\Delta f:=4\frac{f}{2πΣ}$$
+$$\Delta f:=\frac{2f}{πΣ}$$
 
 ## Example: Piano keys
 
 Let's try to understand the meaning of $\Sigma$ via an example: We would like to analyse piano music, and be able to at least distinguish different piano key frequencies.
 
-We can for example check what the resolutions corresponding to $\Sigma=1$ at the key A4 (440 Hz) is with helper functions that implement the formulas above:
+We can, for example, check what the resolutions corresponding to $\Sigma=1$ at the key A4 (440 Hz) is with helper functions that implement the formulas above:
 
 ```{r setup}
 library(fCWTr)
 ```
 
 ```{r}
-sigma_resolution(sigma = 1, u(440, "Hz"))
+sigma_res(sigma = 1, u(440, "Hz"))
 ```
 
-We see now, with $\Sigma=1$, our frequency resolution at 440 Hz is only 280 Hz! The spreading is way too high to be able to distinguish different keys (the next key A#4 is at 466 Hz and the previous key Ab4 is at 415 Hz), we need to able at least to resolve the difference, 15 Hz. We can use another helper function to check what the corresponding $\Sigma$ should be:
+We see now, with $\Sigma=1$, our frequency resolution at 440 Hz is only 280 Hz! The spreading is way too high to be able to distinguish different keys (the next key A#4 is at 466 Hz and the previous key Ab4 is at 415 Hz), at least we need to be able to resolve the difference, 15 Hz. We can use another helper function to check what the corresponding $\Sigma$ should be:
 
 ```{r}
-sigma_from_frequency_resolution(u(15, "Hz"), u(440, "Hz"))
+sigma_from_freq_res(u(15, "Hz"), u(440, "Hz"))
 ```
 
 and it tells us we need $\Sigma=19$ or higher. Let's double-check what that implies for the time resolution:
 
 ```{r}
-sigma_resolution(sigma = 19, u(440, "Hz"))
+sigma_res(sigma = 19, u(440, "Hz"))
 ```
 
-That means, we can detect those frequencies with a time resolution of 170 milliseconds. A typical very fast piano beat is around 180 beats per minutes (\> Prestissimo), that means, 3 beats per seconds, and the required time resolution to detect that is at least 330 milliseconds: our time resolution is still below that, so we are on the safe side.[^2]
+This means, we can detect those frequencies with a time resolution of 170 milliseconds. A typical very fast piano beat is around 180 beats per minutes (\> Prestissimo), i.e. three beats per seconds, and the required time resolution to detect that is at least 330 milliseconds: our time resolution is still below that, so we are on the safe side.[^2]
 
 [^2]: As an interesting side note, we do not have a whole lot of leeway, and when playing a fast piano piece we are already at the edge of what we we can resolve (that is, when only playing a single frequency note, when playing a lot of different notes, we probably can still resolve a faster beat).
 
@@ -80,45 +80,45 @@ Let's compare these settings in practice. As an example serves a simple piano sa
 ### High time resolution, low frequency resolution
 
 ```{r}
-sigma_resolution(sigma = 1, u(440, "Hz"))
+sigma_res(sigma = 1, u(440, "Hz"))
 ```
 
 ```{r}
 library(ggplot2)
 
 fcwt_batch(
   ts_piano_sample,
-  sample_freq = u(44.1, "kHz") / 4,
+  x_sample_freq = u(44.1, "kHz") / 4,
+  y_sample_freq = u(10, "Hz"),
   freq_begin = u(220, "Hz"),
   freq_end = u(440, "Hz") * 4,
   # 5 octaves, 12 keys per octave, 3 frequencies per key
   n_freqs = 12 * 5 * 3,
   sigma = 1,
-  freq_scale = "log",
-  time_resolution = u(100, "ms")
+  freq_scale = "log"
 ) |>
   plot()
 ```
 
 ### Good middle ground
 
 ```{r}
-sigma_resolution(sigma = 19, u(440, "Hz"))
+sigma_res(sigma = 19, u(440, "Hz"))
 ```
 
 ```{r}
 library(ggplot2)
 
 fcwt_batch(
   ts_piano_sample,
-  sample_freq = u(44.1, "kHz") / 4,
+  x_sample_freq = u(44.1, "kHz") / 4,
+  y_sample_freq = u(10, "Hz"),
   freq_begin = u(220, "Hz"),
   freq_end = u(440, "Hz") * 4,
   # 5 octaves, 12 keys per octave, 3 frequencies per key
   n_freqs = 12 * 5 * 3,
   sigma = 20,
-  freq_scale = "log",
-  time_resolution = u(100, "ms")
+  freq_scale = "log"
 ) |>
   plot()
 ```
@@ -128,24 +128,24 @@ fcwt_batch(
 Note that with $\Sigma=100$ we have
 
 ```{r}
-sigma_resolution(sigma = 100, u(440, "Hz"))
+sigma_res(sigma = 100, u(440, "Hz"))
 ```
 
-and so we barely have a time resolution of one second. As we can see we can not resolve the beats between second 12 and 18 anymore:
+and so we barely have a time resolution of one second. As we can see, we can not resolve the beats between second 12 and 18 anymore:
 
 ```{r}
 fcwt_batch(
   ts_piano_sample,
-  sample_freq = u(44.1, "kHz") / 4,
+  x_sample_freq = u(44.1, "kHz") / 4,
+  y_sample_freq = u(10, "Hz"),
   freq_begin = u(220, "Hz"),
   freq_end = u(440, "Hz") * 4,
-  # 5 octaves, 12 keys per octave, 3 frequencies per key
-  n_freqs = 12 * 5 * 3,
+  # 3 octaves, 12 keys per octave, 10 frequencies per key
+  n_freqs = 12 * 3 * 10,
   sigma = 100,
-  freq_scale = "log",
-  time_resolution = u(100, "ms")
+  freq_scale = "log"
 ) |>
   plot()
 ```
 
-In some way, $\Sigma$ can be thought of the exposure time of a camera that has to adjusted manually. Is the exposure time too long the picture becomes blurry, is it too short, the picture becomes too dark to see anything. A good balance is the key to a good photo.
+In some way, $\Sigma$ can be thought of the exposure time of a camera that has to adjusted manually. Is the exposure time too long the picture becomes blurry; is it too short, the picture becomes too dark to see anything. A good balance is key to a good photo.