----------------------------------------------------------------------
This is the API documentation for the gdtest_docstring_combo library.
----------------------------------------------------------------------


## Functions

Public functions


advanced_compute(data: list, method: str = 'fast') -> dict

Perform advanced computation on data using the specified method.

Applies a configurable analysis pipeline to the input data,
returning detailed results including computed values,
diagnostics, and metadata. Uses :py:func:`helper` internally
for element-wise transformations.

.. versionadded:: 3.0

Parameters
----------
data
    A list of numeric values to process. Must contain at
    least one element.
method
    The computation method. One of ``"fast"`` or ``"precise"``.
    The ``"fast"`` method uses approximate algorithms while
    ``"precise"`` uses exact arithmetic at the cost of speed.
    Defaults to ``"fast"``.

Returns
-------
dict
    A dictionary with the following keys:

    - ``"result"`` — the computed aggregate value (float).
    - ``"transformed"`` — element-wise transformed data (list).
    - ``"method"`` — the method that was used (str).
    - ``"n"`` — the number of data points processed (int).

Raises
------
ValueError
    If ``data`` is empty or ``method`` is not recognized.
TypeError
    If ``data`` contains non-numeric values.
OverflowError
    If intermediate computations exceed float range.

Notes
-----
The ``"fast"`` method computes an approximate result using
the following formula:

.. math::

    R = \frac{1}{n} \sum_{i=1}^{n} h(x_i)

where :math:`h` is the :py:func:`helper` transformation and
:math:`n` is the number of data points.

The ``"precise"`` method uses compensated summation (Kahan
algorithm) to minimize floating-point rounding errors. This
is especially important when data values span many orders
of magnitude.

The overall time complexity is ``O(n)`` for both methods,
but the ``"precise"`` method has approximately 4x the
constant factor due to the compensation arithmetic.

Warnings
--------
The ``"fast"`` method may produce results with relative
error up to 1e-10 for datasets with high dynamic range.

See Also
--------
helper : Element-wise transformation used internally.

References
----------
.. [1] Kahan, W. (1965). "Further remarks on reducing
   truncation errors." Communications of the ACM, 8(1), 40.
.. [2] Higham, N.J. (2002). "Accuracy and Stability of
   Numerical Algorithms", 2nd edition, SIAM.

Examples
--------
Basic usage with the default fast method:

>>> result = advanced_compute([1.0, 2.0, 3.0])
>>> result["method"]
'fast'
>>> result["n"]
3

Using the precise method:

>>> result = advanced_compute([1.0, 2.0], method="precise")
>>> result["method"]
'precise'

The transformed values are computed via :py:func:`helper`:

>>> result = advanced_compute([4.0])
>>> result["transformed"]
[2.0]

helper(x: float) -> float

Apply a square-root transformation to a single value.

Computes the square root of the absolute value of ``x``,
preserving the original sign.

Parameters
----------
x
    A numeric value to transform.

Returns
-------
float
    The signed square root: ``sign(x) * sqrt(abs(x))``.

Notes
-----
This function is used internally by
:py:func:`advanced_compute` for element-wise data
transformation.

Examples
--------
>>> helper(4.0)
2.0

>>> helper(-9.0)
-3.0

>>> helper(0.0)
0.0