TACO Reader

https://github.com/tacofoundation/tacoreader
Admin
TACO Reader is a query engine for AI-ready geospatial and satellite imagery datasets, enabling...
Tokens:11,148
Snippets:78
Trust Score:4.2
License:MIT
Update:5 months ago
Show doc for...
Tokens:
Raw
### Install pre-commit Hooks

Source: https://github.com/tacofoundation/tacoreader/blob/main/CONTRIBUTING.md

Install pre-commit to automatically run linters and formatters before each commit.

```bash
poetry run pre-commit install
```

--------------------------------

### Install and Activate Poetry Environment

Source: https://github.com/tacofoundation/tacoreader/blob/main/CONTRIBUTING.md

Install project dependencies using Poetry and activate the virtual environment.

```bash
poetry install
poetry shell
```

--------------------------------

### Run Formatting and Unit Tests

Source: https://github.com/tacofoundation/tacoreader/blob/main/CONTRIBUTING.md

Check that your changes pass formatting tests with 'make check' and all unit tests with 'make test'.

```bash
make check
```

```bash
make test
```

--------------------------------

### tacoreader.use() / tacoreader.get_backend()

Source: https://context7.com/tacofoundation/tacoreader/llms.txt

Sets or reads the global default backend for all subsequent load() calls. Can be overridden per-call with load(..., backend='...').

```APIDOC
## `tacoreader.use()` / `tacoreader.get_backend()` — DataFrame backend selection

Sets or reads the global default backend for all subsequent `load()` calls. Can be overridden per-call with `load(..., backend='...')`. For multiprocessing/PyTorch DataLoader usage, set the backend before forking and load datasets in `__init__`, not in `__getitem__`.

```python
import tacoreader

# Switch to Pandas backend globally
tacoreader.use("pandas")
ds = tacoreader.load("data.tacozip")
df = ds.data  # pandas DataFrame
print(type(df._data))  # <class 'pandas.core.frame.DataFrame'>

# Switch to Polars (requires: pip install polars)
tacoreader.use("polars")
ds = tacoreader.load("data.tacozip")
df = ds.data  # polars DataFrame

# Per-call override (ignores global backend)
ds_arrow = tacoreader.load("data.tacozip", backend="pyarrow")

print(tacoreader.get_backend())  # 'polars'

# PyTorch DataLoader safe pattern (set before fork)
import torch
class SatelliteDataset(torch.utils.data.Dataset):
    def __init__(self, path):
        tacoreader.use("pyarrow")          # set BEFORE fork
        self.ds = tacoreader.load(path)    # load in __init__
        self.tdf = self.ds.data

    def __len__(self):
        return len(self.tdf)

    def __getitem__(self, idx):
        vsi_path = self.tdf.read(idx)      # workers only read
        import rasterio
        with rasterio.open(vsi_path) as src:
            return src.read()
```
```

--------------------------------

### Load and Query Dataset with Automatic Cleanup

Source: https://context7.com/tacofoundation/tacoreader/llms.txt

Loads a dataset from a .tacozip file and performs a SQL query. The connection is automatically closed when exiting the 'with' block.

```python
with tacoreader.load("sentinel2.tacozip") as ds:
    result = ds.sql("SELECT * FROM data WHERE cloud_cover < 5").data
    child_vsi = result.read("tile_042")
    print(child_vsi)
# DuckDB connection closed automatically
```

--------------------------------

### Commit and Push Changes

Source: https://github.com/tacofoundation/tacoreader/blob/main/CONTRIBUTING.md

Add all changes, commit them with a descriptive message, and push your branch to GitHub.

```bash
git add .
git commit -m "Your detailed description of your changes."
git push origin name-of-your-bugfix-or-feature
```

--------------------------------

### Load and Query Dataset with Manual Cleanup

Source: https://context7.com/tacofoundation/tacoreader/llms.txt

Loads a dataset and manually closes the connection in a finally block. Ensure to close the parent dataset connection to release resources.

```python
ds = tacoreader.load("sentinel2.tacozip")
try:
    filtered = ds.filter_bbox(minx=-10.0, miny=35.0, maxx=5.0, maxy=44.0)
    tdf = filtered.data
    vsi = tdf.read(0)
finally:
    ds.close()  # filtered (child) shares this connection — only close parent
```

--------------------------------

### Set Local Python Version with pyenv

Source: https://github.com/tacofoundation/tacoreader/blob/main/CONTRIBUTING.md

If using pyenv, set the local Python version for the project. Use 'pyenv versions' to see available versions.

```bash
pyenv local <x.y.z>
```

--------------------------------

### Load TACO Dataset with tacoreader.load()

Source: https://context7.com/tacofoundation/tacoreader/llms.txt

The primary entry point for loading TACO datasets. Auto-detects format and supports local paths, remote URLs, and multiple files. The 'backend' parameter controls metadata table materialization.

```python
import tacoreader

# --- Local ZIP ---
ds = tacoreader.load("sentinel2.tacozip")

# --- Local folder dataset ---
ds = tacoreader.load("/data/landsat8/")

# --- Remote TacoCat (cached to disk by default) ---
ds = tacoreader.load("https://datasets.example.com/sen2/.tacocat")

# --- Force re-download, skipping disk cache ---
ds = tacoreader.load("https://datasets.example.com/sen2/.tacocat", cache=False)

# --- Polars backend ---
ds = tacoreader.load("sentinel2.tacozip", backend="polars")

# --- Load multiple files → auto-concatenated ---
ds = tacoreader.load(["part_0001.tacozip", "part_0002.tacozip", "part_0003.tacozip"])

# --- pathlib.Path support ---
from pathlib import Path
ds = tacoreader.load(Path("data") / "sentinel2.tacozip")

print(ds)
# <TacoDataset 'sentinel2-l2a-2023'>
# ├── Version: 1.0.0
# ├── Description: Sentinel-2 L2A imagery over Europe...
# ├── Tasks: segmentation, classification
# ├── Spatial Extent: [-25.00°, 34.00°, 45.00°, 72.00°]
# ├── Temporal Extent: 2023-01-01 → 2023-12-31
# │
# └── Level 0: 12450 rows (RSUT: True)
```

--------------------------------

### Clone tacoreader Repository

Source: https://github.com/tacofoundation/tacoreader/blob/main/CONTRIBUTING.md

Clone your forked tacoreader repository locally. Replace YOUR_NAME with your GitHub username.

```bash
cd <directory_in_which_repo_should_be_created>
git clone git@github.com:YOUR_NAME/tacoreader.git
```

--------------------------------

### Create a New Branch

Source: https://github.com/tacofoundation/tacoreader/blob/main/CONTRIBUTING.md

Create a new branch for your bugfix or feature development.

```bash
git checkout -b name-of-your-bugfix-or-feature
```

--------------------------------

### Select DataFrame Backend Globally or Per-Call

Source: https://context7.com/tacofoundation/tacoreader/llms.txt

Set the default DataFrame backend (e.g., pandas, polars, pyarrow) globally using `tacoreader.use()` or override it for a specific `load()` call. Ensure backend is set before forking for multiprocessing.

```python
import tacoreader

# Switch to Pandas backend globally
tacoreader.use("pandas")
ds = tacoreader.load("data.tacozip")
df = ds.data  # pandas DataFrame
print(type(df._data))  # <class 'pandas.core.frame.DataFrame'>
```

```python
# Switch to Polars (requires: pip install polars)
tacoreader.use("polars")
ds = tacoreader.load("data.tacozip")
df = ds.data  # polars DataFrame
```

```python
# Per-call override (ignores global backend)
ds_arrow = tacoreader.load("data.tacozip", backend="pyarrow")

print(tacoreader.get_backend())  # 'polars'
```

```python
# PyTorch DataLoader safe pattern (set before fork)
import torch
class SatelliteDataset(torch.utils.data.Dataset):
    def __init__(self, path):
        tacoreader.use("pyarrow")          # set BEFORE fork
        self.ds = tacoreader.load(path)    # load in __init__
        self.tdf = self.ds.data

    def __len__(self):
        return len(self.tdf)

    def __getitem__(self, idx):
        vsi_path = self.tdf.read(idx)      # workers only read
        import rasterio
        with rasterio.open(vsi_path) as src:
            return src.read()
```

--------------------------------

### Regenerate Test Fixtures

Source: https://github.com/tacofoundation/tacoreader/blob/main/tests/fixtures/README.md

Run this command to regenerate test fixtures. Requires 'tacotoolbox'. Use when tacotoolbox updates the format or when adding new test cases.

```bash
python regenerate.py
```

--------------------------------

### Manage TacoReader Cache

Source: https://context7.com/tacofoundation/tacoreader/llms.txt

Inspect cache locations, monitor cache size, override cache directory via environment variables, and clear all caches. Use `cache=False` to skip caching for a single load.

```python
import os
import tacoreader
from tacoreader._cache import get_cache_dir, get_cache_stats, get_tacocat_cache_dir

# Inspect cache location (platform-specific)
print(get_cache_dir())
# Linux:   /home/user/.cache/tacoreader
# macOS:   /Users/user/Library/Caches/tacoreader
# Windows: C:/Users/user/AppData/Local/tacoreader/Cache

# First load: downloads & caches metadata to disk
ds = tacoreader.load("https://datasets.example.com/sen2/.tacocat")

# Second load: served from disk cache (fast, no network)
ds2 = tacoreader.load("https://datasets.example.com/sen2/.tacocat")

# Check cache size
stats = get_cache_stats()
print(stats)
# {'entries': 3, 'size_mb': 12.4, 'path': '/home/user/.cache/tacoreader/tacocat'}
```

```python
# Override cache dir via env var
os.environ["TACOREADER_CACHE_DIR"] = "/mnt/fast-ssd/tacoreader-cache"
ds3 = tacoreader.load("https://datasets.example.com/sen2/.tacocat")

# Clear all caches (memory + disk) when remote data changes
tacoreader.clear_cache()
ds4 = tacoreader.load("https://datasets.example.com/sen2/.tacocat")  # re-downloads

# Skip cache for single load
ds_fresh = tacoreader.load("https://datasets.example.com/sen2/.tacocat", cache=False)
```

--------------------------------

### Hierarchical Navigation with TacoDataFrame.read()

Source: https://context7.com/tacofoundation/tacoreader/llms.txt

Navigates down a hierarchical dataset by integer position or string ID. Returns a TacoDataFrame for FOLDER types or a VSI path string for FILE types.

```python
import tacoreader
import rasterio

ds = tacoreader.load("multispectral.tacozip")
tdf = ds.data  # level-0 TacoDataFrame

# Navigate by integer position
child = tdf.read(0)  # TacoDataFrame (if FOLDER) or str (if FILE)

# Navigate by sample ID
child = tdf.read("tile_042")

# Deep navigation: level0 → level1 → level2 (leaf file)
l0 = ds.data
l1 = l0.read(0)        # TacoDataFrame at level 1 (e.g., sensors)
l2 = l1.read("band_R") # str VSI path to a GeoTIFF

# Open the raster directly with rasterio
with rasterio.open(l2) as src:
    red_band = src.read(1)
    print(src.meta)
    # {'driver': 'GTiff', 'dtype': 'uint16', 'width': 512, 'height': 512, ...}

# Cascade filter + navigation: only see filtered children
filtered = ds.filter_bbox(minx=-10.0, miny=35.0, maxx=5.0, maxy=44.0, level=1)
tdf_filtered = filtered.data
child_filtered = tdf_filtered.read(0)
print(len(child_filtered))  # Only children inside bbox, not all children
```

--------------------------------

### Chain SQL Queries Lazily with TacoDataset.sql()

Source: https://context7.com/tacofoundation/tacoreader/llms.txt

Creates a new TacoDataset by wrapping a SQL query. Queries are not executed until '.data' is accessed. Navigation columns are preserved when 'SELECT *' is used.

```python
import tacoreader

ds = tacoreader.load("sentinel2.tacozip")

# Chain SQL queries lazily — nothing runs until .data
europe = ds.sql("SELECT * FROM data WHERE continent = 'Europe'")
low_cloud = europe.sql("SELECT * FROM data WHERE cloud_cover < 5")
summer = low_cloud.sql("SELECT * FROM data WHERE month BETWEEN 6 AND 8")

# Materialize: executes the full chained view pipeline
tdf = summer.data
print(tdf.shape)   # (3821, 14)
print(tdf.columns) # ['id', 'type', 'date', 'cloud_cover', 'month', ..., 'internal:gdal_vsi']

# Selective column query — include navigation columns to preserve .read()
nav = ds.navigation_columns()  # ['id', 'type', 'internal:current_id', 'internal:offset', 'internal:size']
user_cols = ["date", "cloud_cover", "satellite"]
filtered = ds.sql(f"SELECT {', '.join(user_cols + nav)} FROM data WHERE cloud_cover < 10")
tdf = filtered.data
vsi_path = tdf.read(0)  # navigation still works
print(vsi_path)  # /vsisubfile/12345_67890,/data/sentinel2.tacozip
```

--------------------------------

### Run Tox for Cross-Python Version Testing

Source: https://github.com/tacofoundation/tacoreader/blob/main/CONTRIBUTING.md

Run tox to test your changes across different Python versions. This is also triggered in CI/CD.

```bash
tox
```

--------------------------------

### Use TacoDataset as a Context Manager

Source: https://context7.com/tacofoundation/tacoreader/llms.txt

Utilize the `TacoDataset` context manager for deterministic DuckDB connection cleanup. Child datasets from `.sql()` share the parent's connection.

```python
import tacoreader

# Example usage (assuming ds is a TacoDataset instance)
# with ds:
#     # Perform operations that require the DuckDB connection
#     pass # Connection is automatically closed upon exiting the 'with' block
```

--------------------------------

### tacoreader.load()

Source: https://context7.com/tacofoundation/tacoreader/llms.txt

The primary entry point to load a TACO dataset. It auto-detects the format and returns a TacoDataset with a lazy DuckDB connection. Supports local paths, lists of paths, and remote URLs.

```APIDOC
## tacoreader.load() — Load a TACO dataset

### Description
The primary entry point. Auto-detects format (`.tacozip`, folder, `.tacocat`) and returns a `TacoDataset` with a lazy DuckDB connection. Supports `pathlib.Path` objects, lists of paths (auto-concatenated when 2+), and remote URLs. The `backend` parameter (`'pyarrow'`, `'polars'`, `'pandas'`) controls how `.data` materializes the metadata table.

### Usage Examples

```python
import tacoreader

# --- Local ZIP ---
ds = tacoreader.load("sentinel2.tacozip")

# --- Local folder dataset ---
ds = tacoreader.load("/data/landsat8/")

# --- Remote TacoCat (cached to disk by default) ---
ds = tacoreader.load("https://datasets.example.com/sen2/.tacocat")

# --- Force re-download, skipping disk cache ---
ds = tacoreader.load("https://datasets.example.com/sen2/.tacocat", cache=False)

# --- Polars backend ---
ds = tacoreader.load("sentinel2.tacozip", backend="polars")

# --- Load multiple files → auto-concatenated ---
ds = tacoreader.load(["part_0001.tacozip", "part_0002.tacozip", "part_0003.tacozip"])

# --- pathlib.Path support ---
from pathlib import Path
ds = tacoreader.load(Path("data") / "sentinel2.tacozip")

print(ds)
# <TacoDataset 'sentinel2-l2a-2023'>
# ├── Version: 1.0.0
# ├── Description: Sentinel-2 L2A imagery over Europe...
# ├── Tasks: segmentation, classification
# ├── Spatial Extent: [-25.00°, 34.00°, 45.00°, 72.00°]
# ├── Temporal Extent: 2023-01-01 → 2023-12-31
# │
# └── Level 0: 12450 rows (RSUT: True)
```
```

--------------------------------

### Calculate Percentiles and Statistics

Source: https://context7.com/tacofoundation/tacoreader/llms.txt

Calculate various statistical measures like percentiles, mean, and categorical probabilities from a dataset. Requires band and level parameters.

```python
p25 = ds.stats_p25(band=1)
p50 = ds.stats_p50(band=1)   # median
p75 = ds.stats_p75(band=1)
p95 = ds.stats_p95(band=1)

# Level-1 stats for a specific parent sample
mean_l1 = ds.stats_mean(band=0, level=1, id="tile_042")

# Categorical stats (class probabilities)
class_probs = ds.stats_categorical(band=0)  # np.ndarray of shape (n_classes,)
```

```python
import numpy as np
mean = ds.stats_mean(band=[0, 1, 2, 3])  # shape (4,)
std  = ds.stats_std(band=[0, 1, 2, 3])   # shape (4,)
print("Normalization params:", list(zip(mean.tolist(), std.tolist())))
# [(1823.4, 312.1), (1654.2, 285.7), ...]
```

--------------------------------

### TacoDataFrame.read()

Source: https://context7.com/tacofoundation/tacoreader/llms.txt

Navigates down the hierarchical structure of a TacoDataFrame. It can be used to access child samples by their integer position or string ID. For file-type samples, it returns a VSI path; for folder-type samples, it returns a child TacoDataFrame.

```APIDOC
## `TacoDataFrame.read()` — Hierarchical navigation

Navigates from a materialized `TacoDataFrame` down to its children by integer position or string ID. For `FILE`-type samples returns a GDAL VSI path string (usable with `rasterio`, GDAL, etc.). For `FOLDER`-type samples returns a child `TacoDataFrame`. Works correctly after cascade filters — filtered views are propagated.

```python
import tacoreader
import rasterio

ds = tacoreader.load("multispectral.tacozip")
tdf = ds.data  # level-0 TacoDataFrame

# Navigate by integer position
child = tdf.read(0)  # TacoDataFrame (if FOLDER) or str (if FILE)

# Navigate by sample ID
child = tdf.read("tile_042")

# Deep navigation: level0 → level1 → level2 (leaf file)
l0 = ds.data
l1 = l0.read(0)        # TacoDataFrame at level 1 (e.g., sensors)
l2 = l1.read("band_R") # str VSI path to a GeoTIFF

# Open the raster directly with rasterio
with rasterio.open(l2) as src:
    red_band = src.read(1)
    print(src.meta)
    # {'driver': 'GTiff', 'dtype': 'uint16', 'width': 512, 'height': 512, ...}

# Cascade filter + navigation: only see filtered children
filtered = ds.filter_bbox(minx=-10.0, miny=35.0, maxx=5.0, maxy=44.0, level=1)
tdf_filtered = filtered.data
child_filtered = tdf_filtered.read(0)
print(len(child_filtered))  # Only children inside bbox, not all children
```
```

--------------------------------

### tacoreader.verbose()

Source: https://context7.com/tacofoundation/tacoreader/llms.txt

Enables or disables structured logging for all tacoreader operations. Supports different levels like 'info', 'debug', or False to disable.

```APIDOC
## `tacoreader.verbose()` — Logging control

Enables or disables structured logging for all tacoreader operations. Use `True`/`"info"` for standard operation logs, `"debug"` for detailed DuckDB query traces and cache decisions, and `False` to suppress all output.

```python
import tacoreader

# Enable standard INFO logging
tacoreader.verbose()

# Enable verbose DEBUG logging (shows DuckDB queries, cache hits, VSI paths)
tacoreader.verbose("debug")

# Disable all logging
tacoreader.verbose(False)

# Practical: debug a slow load
tacoreader.verbose("debug")
ds = tacoreader.load("https://datasets.example.com/huge/.tacocat")
# [DEBUG] HEAD request for .../COLLECTION.json → etag=abc123
# [DEBUG] Cache hit: loaded 3 files from ~/.cache/tacoreader/tacocat/a1b2c3d4
# [DEBUG] Loaded DuckDB spatial extension
# [INFO ] Concatenated 2 datasets (12450 total samples)
tacoreader.verbose(False)
```
```

--------------------------------

### TacoDataset context manager

Source: https://context7.com/tacofoundation/tacoreader/llms.txt

TacoDataset supports the context manager protocol for deterministic DuckDB connection cleanup. Child datasets from .sql() share the parent's connection.

```APIDOC
## `TacoDataset` context manager — Resource management

`TacoDataset` supports the context manager protocol for deterministic DuckDB connection cleanup. Without explicit close, the connection persists until process exit. Child datasets from `.sql()` share the parent's connection and should not be closed independently.

```python
import tacoreader

# Example usage within a context manager
# with tacoreader.load("data.tacozip") as ds:
#     # Use ds here
#     pass # DuckDB connection is closed automatically upon exiting the 'with' block
```
```

--------------------------------

### Control TacoReader Logging Verbosity

Source: https://context7.com/tacofoundation/tacoreader/llms.txt

Enable or disable structured logging for TacoReader operations. Use 'info' for standard logs, 'debug' for detailed traces, or `False` to suppress all output.

```python
import tacoreader

# Enable standard INFO logging
tacoreader.verbose()

# Enable verbose DEBUG logging (shows DuckDB queries, cache hits, VSI paths)
tacoreader.verbose("debug")

# Disable all logging
tacoreader.verbose(False)
```

```python
# Practical: debug a slow load
tacoreader.verbose("debug")
ds = tacoreader.load("https://datasets.example.com/huge/.tacocat")
# [DEBUG] HEAD request for .../COLLECTION.json → etag=abc123
# [DEBUG] Cache hit: loaded 3 files from ~/.cache/tacoreader/tacocat/a1b2c3d4
# [DEBUG] Loaded DuckDB spatial extension
# [INFO ] Concatenated 2 datasets (12450 total samples)
tacoreader.verbose(False)
```

--------------------------------

### TacoDataset.sql()

Source: https://context7.com/tacofoundation/tacoreader/llms.txt

Chains lazy SQL queries on a TacoDataset. The query is not executed until `.data` is accessed. Supports chaining multiple SQL calls.

```APIDOC
## TacoDataset.sql() — Lazy SQL query chaining

### Description
Creates a new `TacoDataset` by wrapping a SQL `CREATE TEMP VIEW` — the query is not executed until `.data` is accessed. Always use `data` as the table name. Calls can be chained. Navigation columns are preserved automatically when `SELECT *` is used.

### Usage Examples

```python
import tacoreader

ds = tacoreader.load("sentinel2.tacozip")

# Chain SQL queries lazily — nothing runs until .data
europe = ds.sql("SELECT * FROM data WHERE continent = 'Europe'")
low_cloud = europe.sql("SELECT * FROM data WHERE cloud_cover < 5")
summer = low_cloud.sql("SELECT * FROM data WHERE month BETWEEN 6 AND 8")

# Materialize: executes the full chained view pipeline
tdf = summer.data
print(tdf.shape)   # (3821, 14)
print(tdf.columns) # ['id', 'type', 'date', 'cloud_cover', 'month', ..., 'internal:gdal_vsi']

# Selective column query — include navigation columns to preserve .read()
nav = ds.navigation_columns()  # ['id', 'type', 'internal:current_id', 'internal:offset', 'internal:size']
user_cols = ["date", "cloud_cover", "satellite"]
filtered = ds.sql(f"SELECT {', '.join(user_cols + nav)} FROM data WHERE cloud_cover < 10")
tdf = filtered.data
vsi_path = tdf.read(0)  # navigation still works
print(vsi_path)  # /vsisubfile/12345_67890,/data/sentinel2.tacozip
```
```

--------------------------------

### Spatial Bounding-Box Filter with TacoDataset.filter_bbox()

Source: https://context7.com/tacofoundation/tacoreader/llms.txt

Filters samples using DuckDB Spatial's ST_Intersects. Supports filtering at level 0 (fast) or cascading through child hierarchy. Geometry column is auto-detected.

```python
import tacoreader

ds = tacoreader.load("global_landsat.tacozip")

# Simple level-0 spatial filter (fast)
europe = ds.filter_bbox(minx=-25.0, miny=34.0, maxx=45.0, maxy=72.0)
print(len(europe.data))  # e.g., 4200

# Explicit column
pacific = ds.filter_bbox(
    minx=120.0, miny=20.0, maxx=170.0, maxy=55.0,
    geometry_col="istac:geometry"
)

# Cascade filter at child level (level=1): filters children matching bbox,

```

--------------------------------

### Verify RSUT Compliance

Source: https://context7.com/tacofoundation/tacoreader/llms.txt

Verifies the RSUT (Raster Spatio-Temporal Unit) compliance of a dataset. This is typically done after complex operations to ensure data integrity.

```python
ds.verify_rsut()  # True / False
```

--------------------------------

### Compute Band Statistics (Mean, Std, Min, Max)

Source: https://context7.com/tacofoundation/tacoreader/llms.txt

Computes weighted aggregate statistics across samples using pre-computed geotiff:stats. Pixel count from stac:tensor_shape is used as weight.

```python
import tacoreader

ds = tacoreader.load("sentinel2.tacozip")

# Mean of band 2 (e.g., red channel) across all level-0 samples
mean_red = ds.stats_mean(band=2)
print(mean_red)        # array([1823.4])

# Multiple bands in one call
mean_rgb = ds.stats_mean(band=[0, 1, 2])
print(mean_rgb.shape)  # (3,)

# Standard deviation (pooled variance formula)
std_rgb = ds.stats_std(band=[0, 1, 2])

# Global min / max
min_val = ds.stats_min(band=0)
max_val = ds.stats_max(band=0)
```

--------------------------------

### TacoDataset.stats_mean(), stats_std(), stats_min(), stats_max(), stats_p*()

Source: https://context7.com/tacofoundation/tacoreader/llms.txt

Computes aggregate statistics (mean, standard deviation, min, max, percentiles) for specified bands across all samples in a TacoDataset. These methods utilize pre-computed statistics stored in the 'geotiff:stats' column and use pixel counts for weighting.

```APIDOC
## `TacoDataset.stats_mean()` / `stats_std()` / `stats_min()` / `stats_max()` / `stats_p*()` — Band statistics

Computes weighted aggregate statistics across all samples using pre-computed per-sample stats stored in the `geotiff:stats` column. Pixel count from `stac:tensor_shape` is used as weight. Level-0 aggregates over all samples; level>0 requires an explicit `id` due to PIT heterogeneity below level 1.

```python
import tacoreader

ds = tacoreader.load("sentinel2.tacozip")

# Mean of band 2 (e.g., red channel) across all level-0 samples
mean_red = ds.stats_mean(band=2)
print(mean_red)        # array([1823.4])

# Multiple bands in one call
mean_rgb = ds.stats_mean(band=[0, 1, 2])
print(mean_rgb.shape)  # (3,)

# Standard deviation (pooled variance formula)
std_rgb = ds.stats_std(band=[0, 1, 2])

# Global min / max
min_val = ds.stats_min(band=0)
max_val = ds.stats_max(band=0)
```
```

--------------------------------

### tacoreader.clear_cache() / tacoreader.get_cache_dir()

Source: https://context7.com/tacofoundation/tacoreader/llms.txt

Clears both in-memory LRU caches and the disk cache for remote TacoCat datasets. The disk cache location can be overridden via TACOREADER_CACHE_DIR.

```APIDOC
## `tacoreader.clear_cache()` / `tacoreader.get_cache_dir()` — Cache management

Clears both in-memory LRU caches (ZIP headers, COLLECTION.json) and the disk cache for remote TacoCat datasets. The disk cache is stored under the platform-specific user cache directory and validated with ETag/Content-Length on each load. Override the cache location via `TACOREADER_CACHE_DIR`.

```python
import os
import tacoreader
from tacoreader._cache import get_cache_dir, get_cache_stats, get_tacocat_cache_dir

# Inspect cache location (platform-specific)
print(get_cache_dir())
# Linux:   /home/user/.cache/tacoreader
# macOS:   /Users/user/Library/Caches/tacoreader
# Windows: C:/Users/user/AppData/Local/tacoreader/Cache

# First load: downloads & caches metadata to disk
ds = tacoreader.load("https://datasets.example.com/sen2/.tacocat")

# Second load: served from disk cache (fast, no network)
ds2 = tacoreader.load("https://datasets.example.com/sen2/.tacocat")

# Check cache size
stats = get_cache_stats()
print(stats)
# {'entries': 3, 'size_mb': 12.4, 'path': '/home/user/.cache/tacoreader/tacocat'}

# Override cache dir via env var
os.environ["TACOREADER_CACHE_DIR"] = "/mnt/fast-ssd/tacoreader-cache"
ds3 = tacoreader.load("https://datasets.example.com/sen2/.tacocat")

# Clear all caches (memory + disk) when remote data changes
tacoreader.clear_cache()
ds4 = tacoreader.load("https://datasets.example.com/sen2/.tacocat")  # re-downloads

# Skip cache for single load
ds_fresh = tacoreader.load("https://datasets.example.com/sen2/.tacocat", cache=False)
```
```

--------------------------------

### Filter by Datetime Range

Source: https://context7.com/tacofoundation/tacoreader/llms.txt

Filters a dataset by a datetime range. Handles ISO 8601 slash-ranges, single datetime objects, and tuples. Time column is auto-detected.

```python
import tacoreader
from datetime import datetime

ds = tacoreader.load("sentinel2.tacozip")

# ISO 8601 slash-range string
q1_2023 = ds.filter_datetime("2023-01-01/2023-03-31")
print(len(q1_2023.data))  # e.g., 1832

# Single datetime (point-in-time query)
single_day = ds.filter_datetime(datetime(2023, 6, 15))

# Tuple of datetime objects
spring = ds.filter_datetime(
    (datetime(2023, 3, 1), datetime(2023, 5, 31)),
    time_col="istac:time_start"
)

# Combine with spatial filter
area = ds.filter_bbox(minx=-5.0, miny=36.0, maxx=10.0, maxy=48.0)
area_spring = area.filter_datetime("2023-03-01/2023-05-31")
tdf = area_spring.data
print(tdf.shape)

# Cascade datetime filter (propagates through hierarchy)
cascade = ds.filter_datetime("2023-06-01/2023-08-31", level=1)
```

--------------------------------

### TacoDataset.filter_bbox()

Source: https://context7.com/tacofoundation/tacoreader/llms.txt

Filters samples using a spatial bounding-box. Supports filtering at level 0 or cascading through child hierarchies.

```APIDOC
## TacoDataset.filter_bbox() — Spatial bounding-box filter

### Description
Filters samples using DuckDB Spatial's `ST_Intersects` on WKB-encoded geometry columns. Supports `level=0` (fast, direct) and `level>0` (cascade through child hierarchy). Geometry column is auto-detected from `istac:geometry`, `stac:centroid`, or `istac:centroid` when `geometry_col='auto'`.

### Usage Examples

```python
import tacoreader

ds = tacoreader.load("global_landsat.tacozip")

# Simple level-0 spatial filter (fast)
europe = ds.filter_bbox(minx=-25.0, miny=34.0, maxx=45.0, maxy=72.0)
print(len(europe.data))  # e.g., 4200

# Explicit column
pacific = ds.filter_bbox(
    minx=120.0, miny=20.0, maxx=170.0, maxy=55.0,
    geometry_col="istac:geometry"
)

# Cascade filter at child level (level=1): filters children matching bbox,
```
```

--------------------------------

### Filter Bounding Box and Read Child Data

Source: https://context7.com/tacofoundation/tacoreader/llms.txt

Filters a dataset by a bounding box and then reads the child data within that box. Useful for isolating specific spatial regions.

```python
cascade = ds.filter_bbox(
    minx=-10.0, miny=35.0, maxx=5.0, maxy=44.0,
    level=1
)
tdf = cascade.data
child = tdf.read(0)  # TacoDataFrame with only children in bbox
print(child.shape)
```

--------------------------------

### Concatenate Multiple TacoDataset Instances

Source: https://context7.com/tacofoundation/tacoreader/llms.txt

Merges compatible TacoDataset instances using DuckDB UNION ALL. Supports 'intersection', 'fill_missing', and 'strict' column modes.

```python
import tacoreader

ds1 = tacoreader.load("sentinel2_2022.tacozip")
ds2 = tacoreader.load("sentinel2_2023.tacozip")
ds3 = tacoreader.load("sentinel2_2024.tacozip")

# Default: intersection — keeps only columns present in ALL datasets
combined = tacoreader.concat([ds1, ds2, ds3])
print(combined)
# Level 0: 37350 rows (RSUT: True)

# fill_missing: keep all columns, pad absent ones with NULL
combined_full = tacoreader.concat([ds1, ds2], column_mode="fill_missing")

# strict: raise TacoSchemaError if columns differ
combined_strict = tacoreader.concat([ds1, ds2], column_mode="strict")

# After concat, all standard APIs still work
filtered = combined.filter_bbox(minx=-25.0, miny=34.0, maxx=45.0, maxy=72.0)
tdf = filtered.data
vsi = tdf.read("tile_0001")

# Multiple-path shortcut: load() auto-concats a list
ds = tacoreader.load(["part_0001.tacozip", "part_0002.tacozip"])
```

--------------------------------

### Concatenate Datasets After RSUT Compliance Check

Source: https://context7.com/tacofoundation/tacoreader/llms.txt

Checks if two datasets are RSUT compliant before concatenating them. RSUT (Raster Spatio-Temporal Unit) compliance is important for certain geospatial operations.

```python
ds1 = tacoreader.load("part1.tacozip")
ds2 = tacoreader.load("part2.tacozip")
if ds1.is_rsut() and ds2.is_rsut():
    combined = tacoreader.concat([ds1, ds2])
```

--------------------------------

### tacoreader.concat()

Source: https://context7.com/tacofoundation/tacoreader/llms.txt

Concatenates multiple TacoDataset instances into a single dataset. It supports different column modes for handling schema mismatches and can automatically concatenate datasets from a list of paths.

```APIDOC
## `tacoreader.concat()` — Concatenate multiple datasets

Merges two or more compatible `TacoDataset` instances into a single dataset using DuckDB `UNION ALL` views. Schemas must be structurally identical (same PIT hierarchy). Three column modes: `"intersection"` (default), `"fill_missing"` (NULL-pad missing columns), `"strict"` (fail on any mismatch). Shows a `tqdm` progress bar for 3+ datasets.

```python
import tacoreader

ds1 = tacoreader.load("sentinel2_2022.tacozip")
ds2 = tacoreader.load("sentinel2_2023.tacozip")
ds3 = tacoreader.load("sentinel2_2024.tacozip")

# Default: intersection — keeps only columns present in ALL datasets
combined = tacoreader.concat([ds1, ds2, ds3])
print(combined)
# Level 0: 37350 rows (RSUT: True)

# fill_missing: keep all columns, pad absent ones with NULL
combined_full = tacoreader.concat([ds1, ds2], column_mode="fill_missing")

# strict: raise TacoSchemaError if columns differ
combined_strict = tacoreader.concat([ds1, ds2], column_mode="strict")

# After concat, all standard APIs still work
filtered = combined.filter_bbox(minx=-25.0, miny=34.0, maxx=45.0, maxy=72.0)
tdf = filtered.data
vsi = tdf.read("tile_0001")

# Multiple-path shortcut: load() auto-concats a list
ds = tacoreader.load(["part_0001.tacozip", "part_0002.tacozip"])
```
```

--------------------------------

### TacoDataset.filter_datetime()

Source: https://context7.com/tacofoundation/tacoreader/llms.txt

Filters a TacoDataset by a datetime range. It can handle ISO 8601 slash-ranges, single datetime objects, and tuples of datetime objects. The time column is auto-detected but can be specified.

```APIDOC
## `TacoDataset.filter_datetime()` — Temporal range filter

Filters by a datetime range using `TRY_CAST` to handle both `TIMESTAMP` and `STRING`-encoded date columns. Accepts ISO 8601 slash-ranges, single `datetime` objects, and tuples. Time column is auto-detected from `istac:time_start` or `stac:time_start`.

```python
import tacoreader
from datetime import datetime

ds = tacoreader.load("sentinel2.tacozip")

# ISO 8601 slash-range string
q1_2023 = ds.filter_datetime("2023-01-01/2023-03-31")
print(len(q1_2023.data))  # e.g., 1832

# Single datetime (point-in-time query)
single_day = ds.filter_datetime(datetime(2023, 6, 15))

# Tuple of datetime objects
spring = ds.filter_datetime(
    (datetime(2023, 3, 1), datetime(2023, 5, 31)),
    time_col="istac:time_start"
)

# Combine with spatial filter
area = ds.filter_bbox(minx=-5.0, miny=36.0, maxx=10.0, maxy=48.0)
area_spring = area.filter_datetime("2023-03-01/2023-05-31")
tdf = area_spring.data
print(tdf.shape)

# Cascade datetime filter (propagates through hierarchy)
cascade = ds.filter_datetime("2023-06-01/2023-08-31", level=1)
```
```
Tokens:
Raw