Temporian

Temporian provides several specialized tutorials for different domains and technical workflows. Before diving into these, it is recommended to review the Getting Started guide to understand core concepts like sampling and indexes.

Available tutorial scenarios include:

• Medical Data Analysis: Heart rate analysis for loading, visualizing, and preprocessing ECG signals to detect heartbeats and compute heart rate variability.
• Financial Modeling:
  • Loan outcomes prediction for preparing data to predict loan outcomes.
  • Detecting payment card fraud using feature augmentation combined with TensorFlow Decision Forests.
• Forecasting & Competition: M5 Competition for feature engineering and model training on M5 Makridakis Forecasting datasets.
• Anomaly Detection:
  • Supervised anomaly detection
  • Unsupervised anomaly detection
• Distributed Computing: Temporian with Apache Beam for executing Temporian operations on large-scale datasets using Apache Beam.

When contributing to Temporian, follow these guidelines for writing docstrings for the public API to ensure consistency and clarity. The objective is to provide succinct, accurate, and unambiguous technical reference material.

General Principles

• Austere and To the point: Avoid flowery language; docstrings should only describe.
• Descriptive, not Imperative: Use """Shifts the sampling backwards""" instead of """Shift the sampling backwards""".
• No Noun Prefixes: Avoid """Function that shifts...""" or """Operator that shifts...""".
• Avoid Redundancy: Do not write docstrings that provide no new information (e.g., """Test for lag operator.""").

Structure

Use the three-double-quote """ format:

1. A summary line (max 80 chars) terminated by a period.
2. A blank line.
3. The rest of the docstring content.

Every file should also contain license boilerplate.

A module's docstring should describe its contents and usage. While not currently mandatory in Temporian, it is recommended for public modules.

Structure

1. A one-line summary terminated by a period.
2. A blank line.
3. An overall description of the module.
4. (Optional) A brief description of exported classes/functions and usage examples.

To ensure mkdocs renders examples correctly as dropdowns, indent the content after the Example: clause and use triple backticks (```) for code blocks.

Example

    """A one-line summary of the module, terminated by a period.

    Leave one blank line.  The rest of this docstring should contain an
    overall description of the module.  Optionally, it may also contain a brief
    description of exported classes and functions and/or usage examples.

    Example:
        ```python
        foo = ClassFoo()
        bar = foo.FunctionBar()
        ```
    """

Docstrings are mandatory for any function that is part of the public API, has non-trivial size, or contains non-obvious logic.

Special Sections

Use the following sections for detailed documentation. Each section heading must end with a colon, and content must be indented by 4 spaces.

Args:

• List each parameter by name.
• Do not document the expected type (use type hints instead).
• Format: name: description.
• If a description exceeds the line length, indent the next line by an additional 4 spaces.
• Include *args and **kwargs if present.
• Omit unnecessary prepositions like The or A at the start of descriptions.

Returns: (or Yields: for generators)

• Describe the semantics of the return value.
• Do not document the expected return type.
• Do not include this section if the function returns None.
• For tuples, use: Returns: A tuple (a, b) where a is....

Raises:

• List and describe all exceptions relevant to the interface.
• Do not document exceptions raised if the API is violated (e.g., invalid argument types).

Example

    """Fetches rows from a Smalltable.

    Retrieves rows pertaining to the given keys from the Table instance
    represented by table_handle.  String keys will be UTF-8 encoded.

    Example:
        ```python
        rows = fetch_rows(handle, keys)
        ```

    Args:
        table_handle: Open `smalltable.Table` instance.
        keys: Sequence of strings representing the key of each table row to
            fetch. String keys will be UTF-8 encoded.
        require_all_keys: If `True`,  only rows with values set for all keys
            will be returned.

    Returns:
        Dict mapping keys to the corresponding table row data fetched. Each row
            is represented as a tuple of strings.

    Raises:
        IOError: An error occurred accessing the smalltable.
    """