Documentation Style Guide#

Overview#

This document outlines the documentation standards for the spectral_connectivity package. We follow NumPy-style docstrings with precise array shape and dtype specifications.

NumPy Docstring Format#

All public functions and classes should use NumPy-style docstrings with the following sections:

Standard Sections#

  1. Summary: Brief one-line description

  2. Parameters: Input parameters with shapes and dtypes

  3. Returns: Output values with shapes and dtypes

  4. Raises: Exceptions that may be raised

  5. Notes: Additional technical details

  6. References: Citations and links

  7. Examples: Executable code examples

Array Documentation#

For all array parameters and returns, specify:

  • Shape: Use descriptive dimension names (e.g., (n_times, n_channels))

  • Dtype: Specify NumPy dtypes (e.g., float64, complex128)

Examples#

def coherence_magnitude(data: NDArray[np.complex128]) -> NDArray[np.float64]:
    """
    Calculate coherence magnitude between signals.

    Parameters
    ----------
    data : NDArray[complex128], shape (n_times, n_channels)
        Time series data for each channel.

    Returns
    -------
    coherence : NDArray[float64], shape (n_freqs, n_channels, n_channels)
        Magnitude of coherence between channel pairs.
    """

Type Annotations#

Preferred Types#

  • Use numpy.typing.NDArray for array types

  • Specify precise dtypes: NDArray[np.float64], NDArray[np.complex128]

  • For mixed precision, use NDArray[np.floating] or NDArray[np.complexfloating]

  • Use standard Python types for scalars: int, float, str, bool

GPU Compatibility#

  • Public APIs should use NumPy types in signatures

  • Document CuPy compatibility in module docstrings

  • Internal functions may use xp array module pattern

Examples Requirements#

  • Include at least one executable example per public function

  • Use realistic array shapes and data

  • Show complete workflows where applicable

  • Verify examples work with doctest when possible

Documentation Checks#

Run the following checks before committing:

# Style validation
pydocstyle --convention=numpy spectral_connectivity

# NumPy docstring validation (spot check)
numpydoc validate spectral_connectivity.connectivity.Connectivity

# Type checking
mypy spectral_connectivity/{connectivity,transforms,simulate,wrapper}.py

Common Patterns#

Shape Specifications#

# Good - descriptive dimension names
shape (n_times, n_trials, n_channels)
shape (n_freqs, n_channels, n_channels)

# Less ideal - generic dimensions
shape (T, N, K)

Dtype Specifications#

# Preferred - specific dtypes
NDArray[np.complex128]
NDArray[np.float64]

# Acceptable for flexibility
NDArray[np.floating]
NDArray[np.complexfloating]

Optional Parameters#

# Document defaults and behavior
sampling_rate : float, default=1000.0
    Sampling rate in Hz. Used for frequency axis scaling.

This style guide ensures consistent, precise documentation that helps users understand array requirements and expected outputs.