menu
Contribute

Functions

GS Quant uses Sphinx to generate python API documentation automatically from the source code.

Type Hinting

Since Python 3.5, functions can use type hinting to document both parameter and return types:

import pandas as pd

def abs(x: pd.Series) -> pd.Series:
    """Docstring"""

    # function code

Each variable can be typed through the syntax param: type. The abs function above has a parameter x which is documented as type pd.Series, which is a pandas Series object. The -> syntax is used to declare the return type of the function. The abs function above also returns a pandas Series object.

Docstring

Functions should use Docstrings per PEP 257 standard to document usage. Python function documentation should have the following components:

  • Function title
  • Parameters and return type
  • Usage info
  • Examples
  • See also

Here's an example of a doc string:

def my_func(x: int) -> str:
    """
    Title / one line description

    :param x: description of parameter x
    :return: description of return value

    **Usage**

    Describe how to use the function should be used

    **Examples**

    Provide one or more examples:

    result = my_func(1)

    **See also**

    :func:`his_func` :func:`her_func`
    """
    # function code

Mathematical Formulas

The GS Quant documentation supports inline LaTex within python docstrings in order to render mathematical formulae. This can be declared using the :math: declaration. For example:

import pandas as pd

def abs(x: pd.Series) -> pd.Series:
    """Absolute value

    :math:`R_t = |X_t|`
    """
    # function code

Everything inside the math block quote marks will be rendered as LaTeX-formatted math.

Full Example

See below for an example of a fully documented function:

def abs(x: pd.Series) -> pd.Series:
    """
    Absolute value of each element in series

    :param x: date-based time series of prices
    :return: date-based time series of absolute value

    **Usage**

    Return the absolute value of :math:`X`. For each value in time series :math:`X_t`, return :math:`X_t` if :math:`X_t`
    is greater than or equal to 0; otherwise return :math:`-X_t`:

    :math:`R_t = |X_t|`

    Equivalent to :math:`R_t = \sqrt{X_t^2}`

    **Examples**

    Generate price series and take absolute value of :math:`X_t-100`

    >>> prices = generate_series(100) - 100
    >>> abs_(prices)

    **See also**

    :func:`exp` :func:`sqrt`

    """
    return abs(x)

Related Content