Metadata-Version: 2.4
Name: transform-tabular
Version: 0.8.0
Summary: Transform columns of pandas DataFrames with element-wise, column-aggregate, and column-threaded operations
Author: Daniele Gregori
License: MIT
Project-URL: Homepage, https://github.com/Daniele-Gregori/PyPI-packages/tree/main/packages/transform-tabular
Project-URL: Repository, https://github.com/Daniele-Gregori/PyPI-packages
Project-URL: Issues, https://github.com/Daniele-Gregori/PyPI-packages/issues
Project-URL: Documentation, https://resources.wolframcloud.com/FunctionRepository/resources/TransformTabular/
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: pandas>=1.3.0
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == "test"

# transform-tabular

[![Tests](https://github.com/Daniele-Gregori/PyPI-packages/actions/workflows/transform-tabular.yml/badge.svg)](https://github.com/Daniele-Gregori/PyPI-packages/actions/workflows/transform-tabular.yml)
[![PyPI version](https://img.shields.io/pypi/v/transform-tabular)](https://pypi.org/project/transform-tabular/)
[![Python versions](https://img.shields.io/pypi/pyversions/transform-tabular)](https://pypi.org/project/transform-tabular/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)



Apply a single function element-wise across an entire DataFrame, or a selection of its columns.

Two special markers extend this to column-aware operations:

- **`ColumnwiseValue(func)`** — computes a scalar aggregate per column (e.g. mean, max). The scalar is then used in the element-wise expression, so every row in that column sees the same aggregate.
- **`ColumnwiseThread(func)`** — applies a list-to-list transformation per column (e.g. sort, cumulative sum). Each row receives the corresponding element from the transformed list.

This package is a Python port of the Wolfram Language resource function [`TransformTabular`](https://resources.wolframcloud.com/FunctionRepository/resources/TransformTabular/).


## Usage

```python
from transform_tabular import transform_tabular, ColumnwiseValue, ColumnwiseThread
import pandas as pd
```

### Syntax

```python
transform_tabular(df, func)                # apply func element-wise to all columns
transform_tabular(df, func, columns)       # apply func only to selected columns
transform_tabular(func)                    # operator form: returns a reusable transformer
transform_tabular(func, columns)           # operator form with column selection
```

**Parameters**

| Parameter | Type | Description |
|-----------|------|-------------|
| `df` | `DataFrame` | Input DataFrame |
| `func` | callable | Function applied element-wise to each cell. May reference `ColumnwiseValue` / `ColumnwiseThread` markers. |
| `columns` | optional | Column selection: a name (`str`), index (`int`), list of names/indices, or `slice`. Defaults to all columns. |

The function `func` is applied element-wise. The optional third argument can be either a list of columns, a list of column indices, a single column, or a slice.

### Basic transformation

Increment all numeric columns by 1:

```python
df = pd.DataFrame({"a": [1, 2, 3], "b": [4, 5, 6]})
transform_tabular(df, lambda x: x + 1)
#    a  b
# 0  2  5
# 1  3  6
# 2  4  7
```

### Column selection

Transform only specific columns:

```python
df = pd.DataFrame({"a": [1, 2, 3], "b": [10, 20, 30], "c": [100, 200, 300]})
transform_tabular(df, lambda x: x * 2, ["a", "c"])
#    a   b    c
# 0  2  10  200
# 1  4  20  400
# 2  6  30  600
```

### ColumnwiseValue (column-level aggregation)

`ColumnwiseValue(func)` wraps a function `func(column_as_list) -> scalar`. The scalar is pre-computed per column and then participates in the element-wise arithmetic — every row in a given column sees that column's aggregate.

Subtract the mean from each element (centering):

```python
df = pd.DataFrame({"x": [1, 2, 3, 4, 5], "y": [10, 20, 30, 40, 50]})
cv_mean = ColumnwiseValue(lambda col: sum(col) / len(col))
transform_tabular(df, lambda x: x - cv_mean)
#      x     y
# 0 -2.0 -20.0
# 1 -1.0 -10.0
# 2  0.0   0.0
# 3  1.0  10.0
# 4  2.0  20.0
```

### ColumnwiseThread (column-level transformation)

`ColumnwiseThread(func)` wraps a function `func(column_as_list) -> list_of_same_length`. The transformation is pre-computed per column and each row receives its corresponding element from the resulting list.

Compute a cumulative sum for each column independently:

```python
from itertools import accumulate

df = pd.DataFrame({"a": [1, 2, 3], "b": [4, 5, 6]})
ct_acc = ColumnwiseThread(lambda col: list(accumulate(col)))
transform_tabular(df, lambda x: ct_acc)
#    a   b
# 0  1   4
# 1  3   9
# 2  6  15
```

### Combined ColumnwiseValue and ColumnwiseThread

Both markers can be used together. For example, compute the cumulative sum of each column and then subtract its mean:

```python
from itertools import accumulate

df = pd.DataFrame({"a": [1, 2, 3], "b": [4, 5, 6]})
ct_acc = ColumnwiseThread(lambda col: list(accumulate(col)))
cv_mean = ColumnwiseValue(lambda col: sum(col) / len(col))
transform_tabular(df, lambda x: ct_acc - cv_mean)
#      a     b
# 0 -1.0  -1.0
# 1  1.0   4.0
# 2  4.0  10.0
```

### Operator form

`transform_tabular` can be curried to produce a reusable transformer:

```python
double_all = transform_tabular(lambda x: x * 2)
double_all(pd.DataFrame({"a": [1, 2], "b": [3, 4]}))
#    a  b
# 0  2  6
# 1  4  8
```

## See also

For further examples and details, see the documentation for the original Wolfram Language resource function: [TransformTabular](https://resources.wolframcloud.com/FunctionRepository/resources/TransformTabular/).

## Author

Daniele Gregori

## License

MIT
