fix_flip_docstring (#560)

d-chambers · web-flow · commit d843736696cc · 2025-09-30T13:15:46.000+01:00
* fix_flip_docstring

* more doc update
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
@@ -3,8 +3,7 @@ Thanks for contributing to DASCore, community contributions are most welcomed!
 
 Before contributing, please read through the [contributors doc](https://dascore.org/contributing/contributing.html)
 
-Before making big changes to the code or adding large complex features, it is a good idea to
-[open a discussion](https://github.com/DASDAE/dascore/discussions). Don't hesitate to ask a question or for
+Before making big changes to the code or adding large complex features, it is a good idea to [open a discussion](https://github.com/DASDAE/dascore/discussions). Don't hesitate to ask a question or for
 help if something isn't clear.
 -->
 
@@ -22,7 +21,6 @@ pound sign, e.g. `#12` without the backticks)
 I have (if applicable):
 
 - [ ] referenced the GitHub issue this PR closes.
-- [ ] documented the new feature with docstrings or appropriate doc page.
-- [ ] included a test. See [testing guidelines](https://dascore.org/contributing/testing.html).
-- [ ] your name has been added to the contributors page (docs/contributors.md).
+- [ ] documented the new feature with docstrings and/or appropriate doc page.
+- [ ] included tests. See [testing guidelines](https://dascore.org/contributing/testing.html).
 - [ ] added the "ready_for_review" tag once the PR is ready to be reviewed.
diff --git a/dascore/proc/basic.py b/dascore/proc/basic.py
@@ -773,6 +773,7 @@ def flip(patch, *dims, flip_coords=True):
     Examples
     --------
     >>> import dascore as dc
+    >>> import numpy as np
     >>> patch = dc.get_example_patch()
     >>>
     >>> # Flip patch over time axis
diff --git a/docs/contributing/contributing.qmd b/docs/contributing/contributing.qmd
@@ -10,7 +10,7 @@ please be aware of our [code of conduct](code_of_conduct.qmd).
 To start, clone DASCore and [install it in development mode](dev_install.qmd). If you are new to contributing to open-source projects, this [recipe](../recipes/how_to_contribute.qmd) provides step-by-step instructions.
 
 Review how [DASCore's testing](testing.qmd) works, [how DASCore is documented](documentation.qmd),
-[DAScore style and linting](style_and_linting.qmd), and the [general guidelines](general_guidelines.qmd).
+[DASCore style and linting](style_and_linting.qmd), and the [general guidelines](general_guidelines.qmd).
 
 
 
@@ -20,38 +20,12 @@ Development planning and prioritization takes place [here](https://github.com/or
 
 # DASCore or other DASDAE packages
 
-You may wonder whether a new feature you'd like to add belongs in DASCore, or if it should be
-part of another [DASDAE](https://github.com/DASDAE) package. The guiding principle is that
-if it does not require additional dependencies and is not particularly specialized to
-one sub-area of applied seismology, then it can be part of DASCore. What if the feature
-you're interested in adding is generally applicable for many kinds of DAS data analysis, but
-requires some additional package dependency? If this is the case, open a discussion describing
-the feature, the additional dependency, and (optional but encouraged) other future
-features that may also share this dependency. Typically we'll try to come to a clear consensus, then you can
-move ahead with development. If the proposed DASCore dependency addition appears to be controversial, then you will
-deliver a short presentation at one of the bi-weekly DASDAE developer team check-ins that should
-describe the feature, the additional dependency (including the approximate size of the additional
-software to be installed), and ideas for other features this dependency could enable.
-Then the developer community in attendance will discuss the proposed change and take a vote (majority
-approval required).
-
-If you are interested in creating a new [DASDAE](https://github.com/DASDAE) package which uses
-DASCore as a dependency, you are not required to hold it to the same style and testing guidelines
-as DASCore, but you are encouraged to do so, and can use DASCore's setup as an example. Following
-a common set of style and contributor workflows will make it easier for us to develop a
-community of DASDAE developers who can easily move between using and developing any of the
-DASDAE packages.
+You may wonder whether a new feature you'd like to add belongs in DASCore, or if it should be part of another [DASDAE](https://github.com/DASDAE) package. The guiding principle is that if it does not require additional dependencies and is not particularly specialized to one sub-area of applied seismology, then it can be part of DASCore. What if the feature you're interested in adding is generally applicable for many kinds of DAS data analysis, but requires some additional package dependency? If this is the case, open a discussion describing the feature, the additional dependency, and (optional but encouraged) other future features that may also share this dependency. Typically we'll try to come to a clear consensus, then you can move ahead with development. If the proposed DASCore dependency addition appears to be controversial, then you will deliver a short presentation at one of the bi-weekly DASDAE developer team check-ins that should describe the feature, the additional dependency (including the approximate size of the additional software to be installed), and ideas for other features this dependency could enable. Then the developer community in attendance will discuss the proposed change and take a vote (majority approval required).
+
+If you are interested in creating a new [DASDAE](https://github.com/DASDAE) package which uses DASCore as a dependency, you are not required to hold it to the same style and testing guidelines as DASCore, but you are encouraged to do so, and can use DASCore's setup as an example. Following a common set of style and contributor workflows will make it easier for us to develop a community of DASDAE developers who can easily move between using and developing any of the DASDAE packages.
 
 # Leadership
 
-Currently DASCore operates in BDFL mode during its initial construction phase,
-with Derrick Chambers leading the oversight of the master branch, but this is
-not intended to be the mode of operation in the future. At a DASDAE developer team check-in (currently biweekly), the team reviews contributions and nominates a leadership team for the next cycle based on contribution history.
-
-Currently Eileen Martin and Ge Jin lead organizational activities (e.g. organize
-team meetings, coordinate logistics of training and tutorial activities, enforcement
-of community standards, approving travel and research assistantships for some contributors
-at Colorado School of Mines) as PI and co-PI of the NSF Geoinformatics grant that is
-supporting initial development of DASDAE packages. However, as the contributor
-community grows beyond Colorado School of Mines, after the life of the grant, these
-roles are intended to be rotating among community members.
+Currently DASCore operates in BDFL mode during its initial construction phase, with Derrick Chambers leading the oversight of the master branch, but this is not intended to be the mode of operation in the future. At a DASDAE developer team check-in (currently biweekly), the team reviews contributions and nominates a leadership team for the next cycle based on contribution history.
+
+Currently Eileen Martin and Ge Jin lead organizational activities (e.g. organize team meetings, coordinate logistics of training and tutorial activities, enforcement of community standards, approving travel and research assistantships for some contributors at Colorado School of Mines) as PI and co-PI of the NSF Geoinformatics grant that is supporting initial development of DASDAE packages. However, as the contributor community grows beyond Colorado School of Mines, after the life of the grant, these roles are intended to be rotating among community members.
diff --git a/docs/contributing/new_format.qmd b/docs/contributing/new_format.qmd
@@ -18,7 +18,7 @@ To demonstrate this process, imagine adding support for a format called `jingle`
 
 ## Adding a New IO Module
 
-First, we create a new io module called 'jingle' in DASCore's io module (dascore/io/jingle). Make sure there is a \__init__.py file in this module whose docstring describes basic use of the format and lists any non-obvious implementation details that might debug/improve the parser.
+First, we create a new io module called 'jingle' in DASCore's io module (dascore/io/jingle). Make sure there is a \__init__.py file in this module whose docstring describes basic use of the format and lists any non-obvious implementation details that might help debug/improve the parser.
 
 contents of `dascore/io/jingle/__init__.py`
 ```{python}
@@ -37,7 +37,7 @@ jingle = dc.spool('path_to_file.jgl')
 """
 ```
 
-Next, create a `core.py` file in the new module (dascore/io/jingle/core.py). Start by creating a class called `JingleIOV1` which subclasses (`dascore.io.core.FiberIO`)[`dascore.io.core.FiberIO`]. Now, on your subclass, you need to implement the supported methods.
+Next, create a `core.py` file in the new module (dascore/io/jingle/core.py). Start by creating a class called `JingleIOV1` which subclasses [`dascore.io.core.FiberIO`](`dascore.io.core.FiberIO`). Now, on your subclass, you need to implement the supported methods.
 
 Contents of `dascore/io/jingle/core.py`:
 
diff --git a/docs/contributing/profiling_benchmarks.qmd b/docs/contributing/profiling_benchmarks.qmd
@@ -21,7 +21,7 @@ If you find a significant issue, you can profile the problematic benchmark(s) to
 For example, suppose you notice a large increase in runtime for the pass_filter benchmark in the patch_benchmarks' TestProcessingBenchmarks class. Run the benchmark again under profiling: 
 
 ```bash
-pytest benchmarks/test_patch_benchmarks.py::TestProcessingBenchmarks::test_pass_filter_performance --profile
+pytest benchmarks/test_patch_benchmarks.py::TestProcessingBenchmarks::test_pass_filter --profile
 ```
 This will create a new `prof` folder with `test_pass_filter_performance.prof` as one of the files. You can view these with a variety of tools, such as [snakeviz](https://jiffyclub.github.io/snakeviz/) (assuming you installed snakeviz with `pip install snakeviz`).
 
diff --git a/docs/contributing/publish_a_new_release.qmd b/docs/contributing/publish_a_new_release.qmd
@@ -2,11 +2,11 @@
 title: "Publish a new release"
 ---
 
-On this page, we provide a step-by-step guidance on how to publish a new release for DASCore.
+On this page, we provide step-by-step guidance on how to publish a new release for DASCore.
 
 ## Step 1: Draft a new release and publish
 
-On DASCore GitHub page, you should go to [Releases](https://github.com/DASDAE/dascore/releases), draft a new release. On the draft, choose a new tag a release title (e.g. 0.0.14). Finally, generate release notes and publish the relase.
+On DASCore GitHub page, you should go to [Releases](https://github.com/DASDAE/dascore/releases), draft a new release. On the draft, choose a new tag and a release title (e.g. 0.0.14). Finally, generate release notes and publish the release.
 
 ## Step 2: Check the release status
 
diff --git a/docs/contributing/style_and_linting.qmd b/docs/contributing/style_and_linting.qmd
@@ -5,7 +5,7 @@ title: "Style and Linting"
 # Linting
 
 DASCore uses [Black](https://github.com/ambv/black) and [flake8](http://flake8.pycqa.org/en/latest/) for code linting.
-If you have [properly installed DASCore' pre-commit hooks](dev_install.qmd#setup-pre-commit-hooks) they will be
+If you have [properly installed DASCore's pre-commit hooks](dev_install.qmd#setup-pre-commit-hooks) they will be
 invoked automatically when you make a git commit. If any complaints are raised simply address them and try again.
 
 Alternatively, before making a commit, you can run all the hooks on all the code like so:
@@ -20,5 +20,5 @@ will automatically fix the issue they raise on the first run.
 # Type Hints
 
 DASCore makes extensive use of Python 3's [type hints](https://docs.python.org/3/library/typing.html).
-Use them to annotate any public functions/methods. See the docstring section of the [documentation page](documentation.qml)
+Use them to annotate any public functions/methods. See the docstring section of the [documentation page](documentation.qmd)
 for more information and some examples.
diff --git a/docs/notes/dft_notes.qmd b/docs/notes/dft_notes.qmd
@@ -4,7 +4,7 @@ These notes provide the reasoning for DASCore's [fourier](`dascore.transform.fou
 
 ## Summary {#sec-summary}
 
-- When performing discrete fourier transforms, DACore multiplies numpy's fft output by the coordinate spacing in order to:
+- When performing discrete fourier transforms, DASCore multiplies numpy's fft output by the coordinate spacing in order to:
 
    - Produce the same units as the continuous fourier transform
    - Preserve energy between the initial and transformed signals
@@ -55,7 +55,7 @@ Before defining the Discrete Fourier Transform (DFT), let's first consider how w
 
 2. Energy Preservation: From @eq-3, integrating the square of the untransformed data should yield the same value as integrating the square of the amplitude spectra.
 
-3. The amplitude of the zero frequency should be equal to the integral of the time series.
+3. The amplitude of the zero frequency should be equal to the integral of the signal.
 
 Now, let's look at Numpy's DFT, which is defined as:
 
@@ -65,11 +65,11 @@ $${#eq-4}
 
 where $a$ is the untransformed series of length $n$, $A$ is the transformed discrete series with elements corresponding to frequency bins ($k$, $k=0, ..., n-1$)
 
-Right away you might notice some reasons @eq-4 can't meet our expectations. First, nowhere are the units of $a$'s axis multiplied by the summation. Since the exponential term must be unit-less, $a$ must have the same units as $A$. Next, the energy can't be preserved since the number of elements in the summation increases as $n$ increases. Lastly, $A(0) = \sum_{m=0}^{n-1} a_m$ which is not the integral, but the sum, of $a$ (it doesn't consider sample spacing).
+Right away you might notice some reasons @eq-4 can't meet our expectations. First, nowhere are the units of $a$'s axis multiplied in the summation. Since the exponential term must be unit-less, $a$ must have the same units as $A$. Next, the energy can't be preserved since the number of elements in the summation increases as $n$ increases. Lastly, $A(0) = \sum_{m=0}^{n-1} a_m$ which is not the integral, but the sum, of $a$ (it doesn't consider sample spacing).
 
 ## Two Sine Waves
 
-To illustrate some of these issues, consider a sine waves with amplitude of $\pm$ $b_0$ and dominant frequency of $f_0$ Hz.
+To illustrate some of these issues, consider a sine wave with amplitude of $\pm$ $b_0$ and dominant frequency of $f_0$ Hz.
 
 $$
 f(x) = b_0 sin(2 \pi\ f_0 x)
@@ -83,11 +83,11 @@ $${#eq-6}
 
 Where $\delta$ is the Dirac delta distribution.
 
-To discretize @eq-5, let $f_0 = 2$, the total signal duration ($T$) = 5 seconds, and $b_0$ = 1. We create two sine waves, one with 500 samples and one with 1000 samples. When we naively perform the dft, [shift the zero frequency to the center](https://numpy.org/doc/stable/reference/generated/numpy.fft.fftshift.html), and plot the amplitude spectra get the following:
+To discretize @eq-5, let $f_0 = 2$, the total signal duration ($T$) = 5 seconds, and $b_0$ = 1. We create two sine waves, one with 500 samples and one with 1000 samples. When we naively perform the dft, [shift the zero frequency to the center](https://numpy.org/doc/stable/reference/generated/numpy.fft.fftshift.html), and plot the amplitude spectra we get the following:
 
 ```{python}
 #| code-fold: true
-#| label: fig-unscalled-plot
+#| label: fig-unscaled-plot
 #| fig-cap: "Sine amplitude spectrum"
 import matplotlib.pyplot as plt
 
@@ -109,7 +109,7 @@ def get_fft_and_freqs(time, signal):
     return np.fft.fftshift(freqs), np.fft.fftshift(fft)
 
 
-def plot_amplitude_spectras(freqs1, fft1, freqs2, fft2, lims=(-5, 5)):
+def plot_amplitude_spectra(freqs1, fft1, freqs2, fft2, lims=(-5, 5)):
     """plot amplitude spectra without normalization"""
     plt.plot(freqs1, np.abs(fft1), label=f"n={len(freqs1)}", alpha=0.8)
     plt.plot(freqs2, np.abs(fft2), label=f"n={len(freqs2)}", alpha=0.8)
@@ -133,23 +133,23 @@ freqs1, fft1 = get_fft_and_freqs(t1, sin1)
 freqs2, fft2 = get_fft_and_freqs(t2, sin2)
 
 # and plot
-ax = plot_amplitude_spectras(freqs1, fft1, freqs2, fft2)
+ax = plot_amplitude_spectra(freqs1, fft1, freqs2, fft2)
 plt.show()
 ```
 
-As expected, both outputs have spikes at $\pm f_0$ (5Hz), but the amplitude of the 1000 sample function 2X larger than the 500 sample function. This isn't entirely surprising; from @eq-6 we expect the amplitude to tend toward infinity as the signal moves from discrete to continuous ($n \rightarrow \infty$). However, this scaling is typically not useful. Certainly, it won't meet our expectations stated above.
+As expected, both outputs have spikes at $\pm f_0$ (2Hz), but the amplitude of the 1000 sample function is 2X larger than the 500 sample function. This isn't entirely surprising; from @eq-6 we expect the amplitude to tend toward infinity as the signal moves from discrete to continuous ($n \rightarrow \infty$). However, this scaling is typically not useful. Certainly, it won't meet our expectations stated above.
 
 ## Scaling
 
 One approach to fix scaling discrepancy is to divide each amplitude spectrum by the number of samples. After which, they have nearly identical spectral amplitudes.
 
 ```{python}
 #| code-fold: true
-#| label: fig-n-scalled-plot
+#| label: fig-n-scaled-plot
 #| fig-cap: "Sine amplitude spectrum scaled by n"
 n_scaled_fft1 = fft1 / len(freqs1)
 n_scaled_fft2 = fft2 / len(freqs2)
-ax = plot_amplitude_spectras(freqs1, n_scaled_fft1, freqs2, n_scaled_fft2)
+ax = plot_amplitude_spectra(freqs1, n_scaled_fft1, freqs2, n_scaled_fft2)
 plt.show()
 ```
 
@@ -182,7 +182,7 @@ print(f"fft n-scaled (n={len(t2)}) energy {fft2_energy:.02f}")
 
 It doesn't. And what about the units? As we saw above, $A$ in @eq-4 would have the same units as $a$.
 
-What if, drawing inspiration from @eq-1, we simply scale the output units by the function's sample spacing ($dx$)? After all, the spacing and the number of samples is directly related by
+What if, drawing inspiration from @eq-1, we simply scale the output by the function's sample spacing ($dx$)? After all, the spacing and the number of samples is directly related by
 
 $$
 \frac{T}{n} = dx
@@ -191,16 +191,16 @@ $${#eq-7}
 
 ```{python}
 #| code-fold: true
-#| label: fig-dt-scalled-plot
-#| fig-cap: "Sine amplitude spectrum scalled by dx"
+#| label: fig-dt-scaled-plot
+#| fig-cap: "Sine amplitude spectrum scaled by dx"
 dt1, dt2 = t1[1] - t1[0], t2[1] - t2[0]
 dt_scaled_fft1 = fft1 * dt1
 dt_scaled_fft2 = fft2 * dt2
-ax = plot_amplitude_spectras(freqs1, dt_scaled_fft1, freqs2, dt_scaled_fft2)
+ax = plot_amplitude_spectra(freqs1, dt_scaled_fft1, freqs2, dt_scaled_fft2)
 plt.show()
 ```
 
-As expected, The transforms with different numbers of points still have the same magnitude at $\pm f_0$. Checking their energy conservation:
+As expected, the transforms with different numbers of points still have the same magnitude at $\pm f_0$. Checking their energy conservation:
 
 ```{python}
 #| code-fold: true
@@ -242,7 +242,7 @@ tri_fft1_scaled = tri_fft1 * dt1
 tri_fft2_scaled = tri_fft2 * dt2
 
 
-ax = plot_amplitude_spectras(tri_freq1, tri_fft1_scaled, tri_freq2, tri_fft2_scaled)
+ax = plot_amplitude_spectra(tri_freq1, tri_fft1_scaled, tri_freq2, tri_fft2_scaled)
 
 value = np.abs(tri_fft2_scaled).max()
 
diff --git a/docs/notes/velocity_to_strain_rate.qmd b/docs/notes/velocity_to_strain_rate.qmd
@@ -77,7 +77,7 @@ plt.tight_layout()
 
 Notice how the noisy channels around distance 2600m and 3400m have lower amplitude but occur along more channels when the `step_multiple` is increased.
 
-Using the first function, the smallest `step_multiple` is 2. Despite treating the edges differently, the outputs of function 2 are nearly tha same as function 1 and no significant edge effects are observable. 
+Using the first function, the smallest `step_multiple` is 2. Despite treating the edges differently, the outputs of function 2 are nearly the same as function 1 and no significant edge effects are observable. 
 
 ```{python}
 #| code-fold: true
diff --git a/docs/recipes/low_freq_proc.qmd b/docs/recipes/low_freq_proc.qmd
diff --git a/docs/recipes/parallelization.qmd b/docs/recipes/parallelization.qmd
diff --git a/docs/recipes/real_time_proc.qmd b/docs/recipes/real_time_proc.qmd
diff --git a/docs/tutorial/transformations.qmd b/docs/tutorial/transformations.qmd
