Rewrite NumPy and SciPy compatibility docs for clarity

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: jeandet

docs/user/numpy.rst

@@ -1,16 +1,18 @@
-Numpy compatibility
+NumPy compatibility
 ===================
 
 .. toctree::
    :maxdepth: 1
 
-
-Speasy is compatible with `numpy <https://numpy.org/>`_ and uses it internally to perform various operations. You can also pass Speasy variables to most numpy functions.
+``SpeasyVariable`` objects behave like NumPy arrays: you can use arithmetic operators, pass them to NumPy functions,
+and index them with boolean masks or integer arrays. The result is always a ``SpeasyVariable`` when the shape
+allows it (i.e. when the time axis is preserved), and a scalar or plain array otherwise.
 
 Arithmetic operations
 ---------------------
 
-For example, you can perform arithmetic operations on Speasy variables:
+Standard arithmetic operators (``+``, ``-``, ``*``, ``/``, ``**``) work directly on Speasy variables
+and return a new ``SpeasyVariable`` with the same time axis:
 
     >>> import speasy as spz
     >>> ace_mag = spz.get_data('amda/imf', "2016-6-2", "2016-6-5")
@@ -19,12 +21,12 @@ For example, you can perform arithmetic operations on Speasy variables:
     <class 'speasy.products.variable.SpeasyVariable'>
 
 
-Numpy functions
+NumPy functions
 ---------------
 
-You can also use numpy functions on Speasy variables, depending on the function, the result will be a Speasy variable or a scalar value:
+Most NumPy functions accept Speasy variables directly.
 
-In the following example, np.mean and np.std return scalar values:
+**Reduction functions** (like ``np.mean``, ``np.std``) collapse the data and return scalar values:
 
     >>> import speasy as spz
     >>> import numpy as np
@@ -35,7 +37,7 @@ In the following example, np.mean and np.std return scalar values:
     >>> np.std(ace_mag) / np.std(mag_divided_offset)
     np.float32(3.0)
 
-In the following example, np.linalg.norm returns a Speasy variable with the same number of rows as the input variable:
+**Per-row functions** (like ``np.linalg.norm`` with ``axis=1``) preserve the time axis and return a ``SpeasyVariable``:
 
     >>> import speasy as spz
     >>> import numpy as np
@@ -49,10 +51,10 @@ In the following example, np.linalg.norm returns a Speasy variable with the same
     (16200, 1)
 
 
-Indexing
---------
+Indexing and slicing
+--------------------
 
-Speasy variables support several indexing methods, including boolean indexing:
+**Boolean indexing** — select rows where a condition is true across all columns:
 
     >>> import speasy as spz
     >>> ace_mag = spz.get_data('amda/imf', "2016-6-2", "2016-6-5")
@@ -61,7 +63,7 @@ Speasy variables support several indexing methods, including boolean indexing:
     >>> ace_mag[ace_mag > 0].shape, ace_mag.shape
     ((1157, 3), (16200, 3))
 
-You can also use integer indexing as with :meth:`numpy.where(...) <numpy.where>`:
+**Integer indexing** with ``np.where``:
 
     >>> import numpy as np
     >>> import speasy as spz
@@ -70,3 +72,36 @@ You can also use integer indexing as with :meth:`numpy.where(...) <numpy.where>`
     <speasy.products.variable.SpeasyVariable object at ...>
     >>> ace_mag[np.where(ace_mag>0)].shape, ace_mag.shape
     ((1157, 3), (16200, 3))
+
+**Column selection** — select one or more columns by name:
+
+    >>> import speasy as spz
+    >>> ace_mag = spz.get_data('amda/imf', "2016-6-2", "2016-6-5")
+    >>> ace_mag.columns
+    ['bx', 'by', 'bz']
+    >>> bx = ace_mag["bx"]
+    >>> bx.shape
+    (16200, 1)
+
+**Time slicing** — slice by ``np.datetime64`` or ``datetime`` objects:
+
+    >>> import speasy as spz
+    >>> import numpy as np
+    >>> ace_mag = spz.get_data('amda/imf', "2016-6-2", "2016-6-5")
+    >>> one_hour = ace_mag[np.datetime64("2016-06-02"):np.datetime64("2016-06-02T01:00:00")]
+    >>> one_hour.shape[0] < ace_mag.shape[0]
+    True
+
+
+Pandas conversion
+-----------------
+
+You can convert a ``SpeasyVariable`` to a Pandas ``DataFrame`` and back:
+
+    >>> import speasy as spz
+    >>> ace_mag = spz.get_data('amda/imf', "2016-6-2", "2016-6-5")
+    >>> df = ace_mag.to_dataframe()
+    >>> type(df)
+    <class 'pandas.core.frame.DataFrame'>
+    >>> df.shape
+    (16200, 3)

docs/user/scipy.rst

@@ -4,14 +4,21 @@ SciPy compatibility
 .. toctree::
    :maxdepth: 1
 
-Speasy wraps a few `scipy <https://www.scipy.org/>`_ functions to provide interpolation, filtering, and resampling capabilities for Speasy variables.
+When working with space physics data, you often need to combine measurements from different instruments
+that sample at different rates, or remove low-frequency trends from a signal. Speasy provides
+ready-to-use functions for these common tasks, built on top of `SciPy <https://www.scipy.org/>`_.
+
+All functions in ``speasy.signal`` accept one or more ``SpeasyVariable`` objects and return
+``SpeasyVariable`` objects with metadata preserved.
+
 
 Interpolation
 -------------
 
-You can use the :func:`speasy.signal.resampling.interpolate` function to interpolate one or more Speasy variables onto a new time base or another variable's time base.
+Instruments on the same spacecraft often sample at different cadences (e.g. magnetic field at 16 Hz,
+particle moments at 4.5 s). To compare them, you need to bring them onto a common time base.
 
-For example, you can interpolate a variable onto a new time base:
+**Interpolate onto a regular time grid:**
 
     >>> import speasy as spz
     >>> from speasy.signal import resampling
@@ -26,7 +33,7 @@ For example, you can interpolate a variable onto a new time base:
     >>> bool(np.all(ace_mag_resampled.time == ref_time))
     True
 
-Even more complex interpolations are supported, such as interpolating multiple variables onto a reference variable.
+**Interpolate onto another variable's time base** — useful for aligning two instruments:
 
     >>> import speasy as spz
     >>> from speasy.signal import resampling
@@ -45,12 +52,34 @@ Even more complex interpolations are supported, such as interpolating multiple v
     >>> Tperp_interp.shape, Tpara_interp.shape, b.shape
     ((240, 1), (240, 1), (240, 4))
 
+Here ``Tperp`` and ``Tpara`` (sampled at ~4.5 s) are interpolated onto the magnetic field time base (~16 Hz).
+You can pass a list of variables to interpolate them all onto the same reference in one call.
+
+
+Resampling
+----------
+
+If you simply want to change the sampling rate of a variable without providing an explicit time vector,
+use :func:`~speasy.signal.resampling.resample`:
+
+    >>> import speasy as spz
+    >>> from speasy.signal import resampling
+    >>> import numpy as np
+    >>> ace_mag = spz.get_data('amda/imf', "2016-6-2", "2016-6-5")
+    >>> ace_mag.shape
+    (16200, 3)
+    >>> ace_mag_5s = resampling.resample(ace_mag, np.timedelta64(5, 's'))
+    >>> ace_mag_5s.shape
+    (51837, 3)
+
+
 Filtering
 ---------
 
-You can use the :func:`speasy.signal.filtering.apply_sos_filter` function to apply a second-order section (SOS) filter to one or more Speasy variables.
+You can apply any SciPy IIR filter (designed as second-order sections) to a Speasy variable.
+This is useful for removing trends, isolating frequency bands, or smoothing data.
 
-For example, you can apply a high-pass filter to a variable:
+**Example: high-pass filter to remove the DC component**
 
     >>> import speasy as spz
     >>> from speasy.signal import filtering
@@ -63,3 +92,13 @@ For example, you can apply a high-pass filter to a variable:
     (16200, 3)
     >>> round(np.mean(ace_mag), 3), round(np.mean(ace_mag_filtered), 3)
     (np.float32(0.355), np.float32(0.0))
+
+The ``apply_sos_filter`` function takes three arguments:
+
+1. The filter coefficients (from ``scipy.signal.butter``, ``scipy.signal.cheby1``, etc. with ``output='sos'``)
+2. The filter function to apply (typically ``scipy.signal.sosfilt`` or ``scipy.signal.sosfiltfilt`` for zero-phase filtering)
+3. The variable(s) to filter (a single ``SpeasyVariable`` or a list of them)
+
+.. note::
+    Filtering assumes a regular time axis. If your data has gaps or irregular sampling,
+    resample it first using :func:`~speasy.signal.resampling.resample` or :func:`~speasy.signal.resampling.interpolate`.