nested-pandas 0.3.2__tar.gz → 0.3.4__tar.gz

{nested_pandas-0.3.2 → nested_pandas-0.3.4}/.copier-answers.yml

@@ -1,5 +1,5 @@
 # Changes here will be overwritten by Copier
-_commit: v2.0.3
+_commit: v2.0.5
 _src_path: gh:lincc-frameworks/python-project-template
 author_email: brantd@uw.edu
 author_name: LINCC Frameworks
@@ -22,3 +22,4 @@ python_versions:
 - '3.10'
 - '3.11'
 - '3.12'
+- '3.13'

nested_pandas-0.3.4/.github/ISSUE_TEMPLATE/README.md

@@ -0,0 +1,9 @@
+# Configurations
+
+Templates for various different issue types are defined in this directory
+and a pull request template is defined as ``../pull_request_template.md``. Adding,
+removing, and modifying these templates to suit the needs of your project is encouraged.
+
+For more information about these templates, look here: https://lincc-ppt.readthedocs.io/en/latest/practices/issue_pr_templating.html
+
+Or if you still have questions contact us: https://lincc-ppt.readthedocs.io/en/latest/source/contact.html

nested_pandas-0.3.4/.github/workflows/README.md

@@ -0,0 +1,9 @@
+# Workflows
+
+The .yml files in this directory are used to define the various continuous
+integration scripts that will be run on your behalf e.g. nightly as a smoke check,
+or when you create a new PR.
+
+For more information about CI and workflows, look here: https://lincc-ppt.readthedocs.io/en/latest/practices/ci.html
+
+Or if you still have questions contact us: https://lincc-ppt.readthedocs.io/en/latest/source/contact.html

{nested_pandas-0.3.2 → nested_pandas-0.3.4}/.github/workflows/asv-main.yml

@@ -8,7 +8,7 @@ on:
     branches: [ main ]
 
 env:
-  PYTHON_VERSION: "3.10"
+  PYTHON_VERSION: "3.11"
   ASV_VERSION: "0.6.4"
   WORKING_DIR: ${{github.workspace}}/benchmarks
 

{nested_pandas-0.3.2 → nested_pandas-0.3.4}/.github/workflows/asv-nightly.yml

@@ -9,7 +9,7 @@ on:
   workflow_dispatch:
   
 env:
-  PYTHON_VERSION: "3.10"
+  PYTHON_VERSION: "3.11"
   ASV_VERSION: "0.6.4"
   WORKING_DIR: ${{github.workspace}}/benchmarks
   NIGHTLY_HASH_FILE: nightly-hash

{nested_pandas-0.3.2 → nested_pandas-0.3.4}/.github/workflows/asv-pr.yml

@@ -15,7 +15,7 @@ concurrency:
   cancel-in-progress: true
 
 env:
-  PYTHON_VERSION: "3.10"
+  PYTHON_VERSION: "3.11"
   ASV_VERSION: "0.6.4"
   WORKING_DIR: ${{github.workspace}}/benchmarks
   ARTIFACTS_DIR: ${{github.workspace}}/artifacts

{nested_pandas-0.3.2 → nested_pandas-0.3.4}/.github/workflows/build-documentation.yml

@@ -21,10 +21,10 @@ jobs:
 
     steps:
     - uses: actions/checkout@v4
-    - name: Set up Python 3.10
+    - name: Set up Python 3.11
       uses: actions/setup-python@v5
       with:
-        python-version: '3.10'
+        python-version: '3.11'
     - name: Install dependencies
       run: |
         sudo apt-get update

{nested_pandas-0.3.2 → nested_pandas-0.3.4}/.github/workflows/pre-commit-ci.yml

@@ -20,7 +20,7 @@ jobs:
     - name: Set up Python
       uses: actions/setup-python@v5
       with:
-        python-version: '3.10'
+        python-version: '3.11'
     - name: Install dependencies
       run: |
         sudo apt-get update
@@ -32,5 +32,5 @@ jobs:
         extra_args: --all-files --verbose
       env:
         SKIP: "check-lincc-frameworks-template-version,no-commit-to-branch,check-added-large-files,validate-pyproject,sphinx-build,pytest-check"
-    - uses: pre-commit-ci/lite-action@v1.0.3
+    - uses: pre-commit-ci/lite-action@v1.1.0
       if: failure() && github.event_name == 'pull_request' && github.event.pull_request.draft == false

{nested_pandas-0.3.2 → nested_pandas-0.3.4}/.github/workflows/publish-benchmarks-pr.yml

@@ -27,7 +27,7 @@ jobs:
         echo "Conclusion: ${{ github.event.workflow_run.conclusion }}"
         echo "Event: ${{ github.event.workflow_run.event }}"
     - name: Download artifact
-      uses: dawidd6/action-download-artifact@v6
+      uses: dawidd6/action-download-artifact@v7
       with:
         name: benchmark-artifacts
         run_id: ${{ github.event.workflow_run.id }}

{nested_pandas-0.3.2 → nested_pandas-0.3.4}/.github/workflows/publish-to-pypi.yml

@@ -27,7 +27,7 @@ jobs:
     - name: Set up Python
       uses: actions/setup-python@v5
       with:
-        python-version: '3.10'
+        python-version: '3.11'
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip

{nested_pandas-0.3.2 → nested_pandas-0.3.4}/.github/workflows/smoke-test.yml

@@ -20,7 +20,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ['3.9', '3.10', '3.11', '3.12']
+        python-version: ['3.9', '3.10', '3.11', '3.12', '3.13']
 
     steps:
     - uses: actions/checkout@v4

{nested_pandas-0.3.2 → nested_pandas-0.3.4}/.github/workflows/testing-and-coverage.yml

@@ -15,7 +15,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ['3.9', '3.10', '3.11', '3.12']
+        python-version: ['3.9', '3.10', '3.11', '3.12', '3.13']
 
     steps:
     - uses: actions/checkout@v4
@@ -33,6 +33,6 @@ jobs:
       run: |
         python -m pytest --cov=nested_pandas --cov-report=xml
     - name: Upload coverage report to codecov
-      uses: codecov/codecov-action@v4
+      uses: codecov/codecov-action@v5
       with:
         token: ${{ secrets.CODECOV_TOKEN }}

{nested_pandas-0.3.2 → nested_pandas-0.3.4}/.pre-commit-config.yaml

@@ -18,7 +18,7 @@ repos:
         description: Clear output from Jupyter notebooks.
         files: \.ipynb$
         exclude: ^docs/pre_executed
-        stages: [commit]
+        stages: [pre-commit]
         language: system
         entry: jupyter nbconvert --clear-output
     # Prevents committing directly branches named 'main' and 'master'.

{nested_pandas-0.3.2 → nested_pandas-0.3.4}/.readthedocs.yml

@@ -9,7 +9,7 @@ version: 2
 build:
   os: ubuntu-22.04
   tools:
-    python: "3.10"
+    python: "3.11"
 
 # Build documentation in the docs/ directory with Sphinx
 sphinx:

{nested_pandas-0.3.2 → nested_pandas-0.3.4}/PKG-INFO

@@ -1,6 +1,7 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.2
 Name: nested-pandas
-Version: 0.3.2
+Version: 0.3.4
+Summary: An extension of pandas for efficient representation of nested associated datasets.
 Author-email: LINCC Frameworks <brantd@uw.edu>
 License: MIT License
         
@@ -50,6 +51,9 @@ Requires-Dist: ruff; extra == "dev"
 
 [![Template](https://img.shields.io/badge/Template-LINCC%20Frameworks%20Python%20Project%20Template-brightgreen)](https://lincc-ppt.readthedocs.io/en/latest/)
 
+[![PyPI](https://img.shields.io/pypi/v/nested-pandas?color=blue&logo=pypi&logoColor=white)](https://pypi.org/project/nested-pandas/)
+[![Conda](https://img.shields.io/conda/vn/conda-forge/nested-pandas.svg?color=blue&logo=condaforge&logoColor=white)](https://anaconda.org/conda-forge/nested-pandas)
+
 [![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/lincc-frameworks/nested-pandas/smoke-test.yml)](https://github.com/lincc-frameworks/nested-pandas/actions/workflows/smoke-test.yml)
 [![codecov](https://codecov.io/gh/lincc-frameworks/nested-pandas/branch/main/graph/badge.svg)](https://codecov.io/gh/lincc-frameworks/nested-pandas)
 [![Read the Docs](https://img.shields.io/readthedocs/nested-pandas)](https://nested-pandas.readthedocs.io/)
@@ -63,7 +67,40 @@ tooling and support for nested dataframes packed into values of top-level
 dataframe columns. [Pyarrow](https://arrow.apache.org/docs/python/index.html) 
 is used internally to aid in scalability and performance.
 
-![image](./nestedframe.png)
+Nested-Pandas allows data like this:
+
+<p align="center">
+    <img src="./docs/intro_images/pandas_dfs.png" alt="pandas dataframes" width="400"/>
+</p>
+
+To instead be represented like this:
+
+<p align="center">
+    <img src="./docs/intro_images/nestedframe.png" alt="nestedframe" width="400"/>
+</p>
+
+Where the nested data is represented as nested dataframes:
+
+```python
+   # Each row of "object_nf" now has it's own sub-dataframe of matched rows from "source_df"
+   object_nf.loc[0]["nested_sources"]
+```
+
+<p align="center">
+    <img src="./docs/intro_images/loc_into_nested.png" alt="sub-dataframe" width="225"/>
+</p>
+
+Allowing powerful and straightforward operations, like:
+
+```python
+   # Compute the mean flux for each row of "object_nf"
+   import numpy as np
+   object_nf.reduce(np.mean, "nested_sources.flux")
+```
+
+<p align="center">
+    <img src="./docs/intro_images/reduce.png" alt="using reduce" width="150"/>
+</p>
 
 Nested-Pandas is motivated by time-domain astronomy use cases, where we see
 typically two levels of information, information about astronomical objects and

{nested_pandas-0.3.2 → nested_pandas-0.3.4}/README.md

@@ -2,6 +2,9 @@
 
 [![Template](https://img.shields.io/badge/Template-LINCC%20Frameworks%20Python%20Project%20Template-brightgreen)](https://lincc-ppt.readthedocs.io/en/latest/)
 
+[![PyPI](https://img.shields.io/pypi/v/nested-pandas?color=blue&logo=pypi&logoColor=white)](https://pypi.org/project/nested-pandas/)
+[![Conda](https://img.shields.io/conda/vn/conda-forge/nested-pandas.svg?color=blue&logo=condaforge&logoColor=white)](https://anaconda.org/conda-forge/nested-pandas)
+
 [![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/lincc-frameworks/nested-pandas/smoke-test.yml)](https://github.com/lincc-frameworks/nested-pandas/actions/workflows/smoke-test.yml)
 [![codecov](https://codecov.io/gh/lincc-frameworks/nested-pandas/branch/main/graph/badge.svg)](https://codecov.io/gh/lincc-frameworks/nested-pandas)
 [![Read the Docs](https://img.shields.io/readthedocs/nested-pandas)](https://nested-pandas.readthedocs.io/)
@@ -15,7 +18,40 @@ tooling and support for nested dataframes packed into values of top-level
 dataframe columns. [Pyarrow](https://arrow.apache.org/docs/python/index.html) 
 is used internally to aid in scalability and performance.
 
-![image](./nestedframe.png)
+Nested-Pandas allows data like this:
+
+<p align="center">
+    <img src="./docs/intro_images/pandas_dfs.png" alt="pandas dataframes" width="400"/>
+</p>
+
+To instead be represented like this:
+
+<p align="center">
+    <img src="./docs/intro_images/nestedframe.png" alt="nestedframe" width="400"/>
+</p>
+
+Where the nested data is represented as nested dataframes:
+
+```python
+   # Each row of "object_nf" now has it's own sub-dataframe of matched rows from "source_df"
+   object_nf.loc[0]["nested_sources"]
+```
+
+<p align="center">
+    <img src="./docs/intro_images/loc_into_nested.png" alt="sub-dataframe" width="225"/>
+</p>
+
+Allowing powerful and straightforward operations, like:
+
+```python
+   # Compute the mean flux for each row of "object_nf"
+   import numpy as np
+   object_nf.reduce(np.mean, "nested_sources.flux")
+```
+
+<p align="center">
+    <img src="./docs/intro_images/reduce.png" alt="using reduce" width="150"/>
+</p>
 
 Nested-Pandas is motivated by time-domain astronomy use cases, where we see
 typically two levels of information, information about astronomical objects and

{nested_pandas-0.3.2 → nested_pandas-0.3.4}/benchmarks/asv.conf.json

@@ -37,7 +37,7 @@
     // The Pythons you'd like to test against. If not provided, defaults
     // to the current version of Python used to run `asv`.
     "pythons": [
-        "3.10"
+        "3.11"
     ],
     // The matrix of dependencies to test. Each key is the name of a
     // package (in PyPI) and the values are version numbers.  An empty

nested_pandas-0.3.4/docs/gettingstarted/quickstart.ipynb

@@ -0,0 +1,367 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Quickstart\n",
+    "\n",
+    "This notebook provides a brief introduction to nested-pandas, including the motivation and basics for working with the data structure. For more in-depth descriptions, see the other tutorial notebooks."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Installation\n",
+    "\n",
+    "With a valid Python environment, nested-pandas and it's dependencies are easy to install using the `pip` package manager. The following command can be used to install it:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# % pip install nested-pandas"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Overview\n",
+    "\n",
+    "Nested-Pandas is tailored towards efficient analysis of nested data sets. This includes data that would normally be represented in a Pandas DataFrames with multiple rows needed to represent a single \"thing\" and therefor columns whose values will be identical for that item.\n",
+    "\n",
+    "As a concrete example, consider an astronomical data set storing information about observations of physical objects, such as stars and galaxies. One way to represent this in Pandas is to create one row per observation with an ID column indicating to which physical object the observation corresponds. However this approach ends up repeating a lot of data over each observation of the same object such as its location on the sky (RA, dec), its classification, etc. Further, any operations processing the data as time series requires the user to first perform a (potentially expensive) group-by operation to aggregate all of the data for each object.\n",
+    "\n",
+    "Let's create a flat pandas dataframe with three objects: object 0 has three observations, object 1 has three observations, and object 2 has 4 observations."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import pandas as pd\n",
+    "\n",
+    "# Represent nested time series information as a classic pandas dataframe.\n",
+    "my_data_frame = pd.DataFrame(\n",
+    "    {\n",
+    "        \"id\": [0, 0, 0, 1, 1, 1, 2, 2, 2, 2],\n",
+    "        \"ra\": [10.0, 10.0, 10.0, 15.0, 15.0, 15.0, 12.1, 12.1, 12.1, 12.1],\n",
+    "        \"dec\": [0.0, 0.0, 0.0, -1.0, -1.0, -1.0, 0.5, 0.5, 0.5, 0.5],\n",
+    "        \"time\": [60676.0, 60677.0, 60678.0, 60675.0, 60676.5, 60677.0, 60676.6, 60676.7, 60676.8, 60676.9],\n",
+    "        \"brightness\": [100.0, 101.0, 99.8, 5.0, 5.01, 4.98, 20.1, 20.5, 20.3, 20.2],\n",
+    "    }\n",
+    ")\n",
+    "my_data_frame"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Note that we cannot cleanly compress this by adding more columns (such as such as t0, t1, and so forth), because the number of observations is not bounded and may vary from object to object.\n",
+    "\n",
+    "Beyond astronomical data we might be interested in tracking patients blood pressure over time, the measure of intensities of emitted light at different wavelengths, or storing a list of the type of rock found at different depths of core samples. In each case it is possible to represent this data with multiple rows (such as one row for each patient + measurement pair) and associate them together by ids.\n",
+    "\n",
+    "Nested-pandas is designed for exactly this type of data by allowing columns to contain nested data. We can have regular columns with the (single) value for the objects’ unvarying characteristics (location on the sky, patentient birth date, location of the core sample) and nested columns for the values of each observation.\n",
+    "\n",
+    "Let's see an example:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from nested_pandas.nestedframe import NestedFrame\n",
+    "\n",
+    "# Create a nested data set\n",
+    "nf = NestedFrame.from_flat(\n",
+    "    my_data_frame,\n",
+    "    base_columns=[\"ra\", \"dec\"],  # the columns not to nest\n",
+    "    nested_columns=[\"time\", \"brightness\"],  # the columns to nest\n",
+    "    on=\"id\",  # column used to associate rows\n",
+    "    name=\"lightcurve\",  # name of the nested column\n",
+    ")\n",
+    "nf"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The above dataframe is a `NestedFrame`, which extends the capabilities of the Pandas `DataFrame` to support columns with nested information. \n",
+    "\n",
+    "We now have the top level dataframe with 3 rows, each of which corresponds to a single object. The table has three columns beyond \"id\". Two columns, \"ra\" and \"dec\", have a single value for the object (in this case the position on the sky). The last column \"lightcurve\" contains a nested table with a series of observation times and observation brightnesses for the object. As we will see below, this nested table allows the user to easily access to the all of the observations for a given object.\n",
+    "\n",
+    "## Accessing Nested Data\n",
+    "\n",
+    "We can inspect the contents of the \"lightcurve\" column using pandas API tooling like `loc`."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "nf.loc[0][\"lightcurve\"]"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Here we see that within the \"lightcurve\" column there are tables with their own data. In this case we have 2 columns (\"time\" and \"brightness\") that represent a time series of observations. \n",
+    "\n",
+    "Note that `loc` itself accesses the row, so the combination of `nf.loc[0][\"lightcurve\"]` means we are looking at value in the \"lightcurve\" column for a single row (row 0). If we just use `nf.loc[0]` we would retrieve the entire row, including the nested \"lightcurve\" column and all other columns. Similarly if we use `nf[\"lightcurve]` we retrieve the nested column for all rows. What makes the nesting useful is that once we access the nested entry for a specific row, we can treat the value as a table in its own right.\n",
+    "\n",
+    "As in Pandas, we can still access individual entries from a column based on the row index. Thus we can access the values (in a table) in row 0 of the nested column as `nf[\"lightcurve\"][0]` as well."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "nf[\"lightcurve\"][0]"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "We can also use dot notation to access all the values in a nested sub column:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "nf[\"lightcurve.time\"]"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Note that \"lightcurve.time\" contains the time values for all rows, but also preserves the nesting information. The id column of the returned data maps the top-level row (in `nf`) to where this value resides.\n",
+    "\n",
+    "Similarly, we can access the values for a given top-level row by index. To get all the `time` values for row 0 we could specify:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "nf[\"lightcurve.time\"][0]"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Here the `[0]` is telling our nested frame to access the values of the series `nf[\"lightcurve.time\"]` where the id = 0. If we try `nf[\"lightcurve.time\"][0][0]` we again match id = 0 and return the same frame. \n",
+    "\n",
+    "To access a single element within the series, we need to use its location:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "nf[\"lightcurve.time\"][0].iloc[0]"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Inspecting Nested Frames\n",
+    "\n",
+    "We can inspect the available columns using some custom properties of the `NestedFrame`."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Shows which columns have nested data\n",
+    "nf.nested_columns"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Provides a dictionary of \"base\" (top-level) and nested column labels\n",
+    "nf.all_columns"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Pandas Operations\n",
+    "\n",
+    "Nested-pandas extends the Pandas API, meaning any operation you could do in Pandas is available within nested-pandas. However, nested-pandas has additional functionality and tooling to better support working with nested datasets. For example, let's look at `query`:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Normal queries work as expected, rejecting rows from the dataframe that don't meet the criteria\n",
+    "nf.query(\"ra > 11.2\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The above query is native Pandas, however with nested-pandas we can use hierarchical column names to extend `query` to nested layers."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Applies the query to \"nested\", filtering based on \"time > 60676.0\"\n",
+    "nf_g = nf.query(\"lightcurve.time > 60676.0\")\n",
+    "nf_g"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "This query does not affect the rows of the top-level dataframe, but rather applies the query to the \"nested\" dataframes. If we look at one of them, we can see the effect of the query."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# All t <= 60676.0 have been removed\n",
+    "nf_g.loc[0][\"lightcurve\"]"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "A limited set of functions have been extended in this way so far, with the aim being to fully support this hierarchical access where applicable in the Pandas API."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Reduce Function\n",
+    "\n",
+    "Finally, we'll end with the flexible `reduce` function. `reduce` functions similarly to Pandas' `apply` but flattens (reduces) the inputs from nested layers into array inputs to the given apply function. For example, let's find the mean flux for each dataframe in \"nested\":"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import numpy as np\n",
+    "\n",
+    "# use hierarchical column names to access the flux column\n",
+    "# passed as an array to np.mean\n",
+    "nf.reduce(np.mean, \"lightcurve.brightness\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "This can be used to apply any custom functions you need for your analysis, and just to illustrate that point further let's define a custom function that just returns it's inputs."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "def show_inputs(*args):\n",
+    "    return args"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Applying some inputs via reduce, we see how it sends inputs to a given function.  The output frame `nf_inputs` consists of two columns containing the output of the “ra” column and the “lightcurve.time” column."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "nf_inputs = nf.reduce(show_inputs, \"ra\", \"lightcurve.time\")\n",
+    "nf_inputs"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "nf_inputs.loc[0]"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "nested",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.10.4"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}