AR1/docs/api/analysis.md

# Analysis API

Endpoints for running spatial analysis tools.

## Hot Spot Analysis

**Endpoint**: `POST /api/analysis_hotspot_run.php`

Run Getis-Ord Gi* hot spot analysis on a dataset.

### Request Body

```json
{
  "dataset_id": 123,
  "value_field": "population",
  "neighbor_type": "distance",
  "distance": 1000,
  "output_mode": "static"
}
```

### Parameters

- `dataset_id` (required): Dataset ID to analyze
- `value_field` (required): Numeric field to analyze
- `neighbor_type` (optional): "distance" or "knn" (default: "distance")
- `distance` (required if neighbor_type="distance"): Distance threshold in dataset units
- `k_neighbors` (required if neighbor_type="knn"): Number of nearest neighbors
- `output_mode` (optional): "static", "view", or "materialized_view" (default: "static")

### Response

```json
{
  "status": "success",
  "job_id": 456,
  "message": "Hot spot analysis job queued"
}
```

### Background Job

The analysis runs as a background job. Use the `job_id` to check status via [Jobs API](jobs.md).

### Example

```bash
curl -X POST "https://example.com/api/analysis_hotspot_run.php" \
  -H "Content-Type: application/json" \
  -H "Cookie: PHPSESSID=..." \
  -d '{
    "dataset_id": 123,
    "value_field": "population",
    "neighbor_type": "distance",
    "distance": 1000
  }'
```

## Outlier Analysis

**Endpoint**: `POST /api/analysis/outlier_run.php`

Identify statistical outliers in a dataset.

### Request Body

```json
{
  "dataset_id": 123,
  "value_field": "income",
  "method": "zscore",
  "threshold": 2.0
}
```

### Parameters

- `dataset_id` (required): Dataset ID to analyze
- `value_field` (required): Numeric field to analyze
- `method` (optional): "zscore" or "mad" (default: "zscore")
- `threshold` (optional): Z-score threshold or MAD multiplier (default: 2.0)

### Response

```json
{
  "status": "success",
  "job_id": 457,
  "message": "Outlier analysis job queued"
}
```

## KDE (Kernel Density Estimation)

**Endpoint**: `POST /api/analysis_kde.php`

Generate kernel density estimation surface from point data.

### Request Body

```json
{
  "dataset_id": 123,
  "bandwidth": 1000,
  "cell_size": 100,
  "weight_field": null
}
```

### Parameters

- `dataset_id` (required): Point dataset ID
- `bandwidth` (optional): Bandwidth in dataset units (default: auto-calculated)
- `cell_size` (optional): Output cell size (default: auto-calculated)
- `weight_field` (optional): Field to weight points

### Response

```json
{
  "status": "success",
  "job_id": 458,
  "message": "KDE analysis job queued"
}
```

## Nearest Neighbor Analysis

**Endpoint**: `POST /api/nearest_run.php`

Find nearest neighbors between two datasets.

### Request Body

```json
{
  "source_dataset_id": 123,
  "target_dataset_id": 124,
  "max_distance": 5000,
  "limit": 1
}
```

### Parameters

- `source_dataset_id` (required): Source dataset ID
- `target_dataset_id` (required): Target dataset ID
- `max_distance` (optional): Maximum search distance
- `limit` (optional): Maximum neighbors per feature (default: 1)

### Response

```json
{
  "status": "success",
  "job_id": 459,
  "message": "Nearest neighbor analysis job queued"
}
```

## Dissolve Analysis

**Endpoint**: `POST /api/run_dissolve.php`

Dissolve features based on attribute values.

### Request Body

```json
{
  "dataset_id": 123,
  "dissolve_field": "category",
  "aggregation": {
    "population": "sum",
    "area": "sum"
  }
}
```

### Parameters

- `dataset_id` (required): Dataset ID
- `dissolve_field` (required): Field to dissolve on
- `aggregation` (optional): Aggregation functions for numeric fields

### Response

```json
{
  "status": "success",
  "job_id": 460,
  "message": "Dissolve analysis job queued"
}
```

## Clip Analysis

**Endpoint**: `POST /api/datasets_clip_run.php`

Clip features to a boundary geometry.

### Request Body

```json
{
  "dataset_id": 123,
  "clip_geometry": {
    "type": "Polygon",
    "coordinates": [ ... ]
  }
}
```

### Parameters

- `dataset_id` (required): Dataset ID to clip
- `clip_geometry` (required): GeoJSON geometry for clipping boundary

### Response

```json
{
  "status": "success",
  "job_id": 461,
  "message": "Clip analysis job queued"
}
```

## Erase Analysis

**Endpoint**: `POST /api/analysis_erase_run.php`

Erase features from a dataset using another dataset.

### Request Body

```json
{
  "input_dataset_id": 123,
  "erase_dataset_id": 124
}
```

### Parameters

- `input_dataset_id` (required): Input dataset ID
- `erase_dataset_id` (required): Erase dataset ID

### Response

```json
{
  "status": "success",
  "job_id": 462,
  "message": "Erase analysis job queued"
}
```

## Zonal Statistics

**Endpoint**: `POST /api/zonal_stats.php`

Calculate statistics for raster data within polygon zones.

### Request Body

```json
{
  "raster_dataset_id": 125,
  "zone_dataset_id": 123,
  "statistics": ["mean", "sum", "count"]
}
```

### Parameters

- `raster_dataset_id` (required): Raster dataset ID
- `zone_dataset_id` (required): Polygon zone dataset ID
- `statistics` (optional): Statistics to calculate (default: all)

### Response

```json
{
  "status": "success",
  "job_id": 463,
  "message": "Zonal statistics job queued"
}
```

## Output Modes

Analysis results can be stored in different formats:

- **static**: Results stored in a permanent table (default)
- **view**: Results stored as a database view (updates with source data)
- **materialized_view**: Results stored as a materialized view (requires refresh)

## Job Status

All analysis operations run as background jobs. Use the returned `job_id` to check status:

```bash
GET /api/job_status.php?job_id=456
```

See [Jobs API](jobs.md) for details.

## Related Documentation

- [Analysis Tools](../analysis-tools/index.md)
- [Workers](../workers/index.md)
- [Jobs API](jobs.md)