# Hot Spot Time Series Worker

Processes hot spot time series analysis jobs to analyze temporal patterns in hot spots.

## Overview

The hot spot time series worker performs hot spot analysis across multiple time periods to identify temporal patterns in spatial clustering.

## Job Type

`hotspot_timeseries`

## Input Parameters

```json
{
  "dataset_id": 123,
  "value_field": "population",
  "time_field": "date",
  "time_periods": ["2020", "2021", "2022"],
  "neighbor_type": "distance",
  "distance": 1000
}
```

### Parameters

- `dataset_id` (required): Source dataset ID
- `value_field` (required): Numeric field to analyze
- `time_field` (required): Field containing time period identifiers
- `time_periods` (required): Array of time period values to analyze
- `neighbor_type` (optional): "distance" or "knn" (default: "distance")
- `distance` (required if neighbor_type="distance"): Distance threshold
- `k_neighbors` (required if neighbor_type="knn"): Number of nearest neighbors

## Output

Creates a new dataset with time series hot spot results:

- Hot spot analysis for each time period
- Temporal patterns in clustering
- Time period identifiers
- Gi* z-scores and p-values for each period

## Algorithm

The worker:

1. Filters data by time period
2. Performs hot spot analysis for each period
3. Combines results with time period information
4. Stores results in output table

## Example

```bash
# Enqueue a hot spot time series job via API
curl -X POST "https://example.com/api/hotspot_timeseries_run.php" \
  -H "Content-Type: application/json" \
  -d '{
    "dataset_id": 123,
    "value_field": "population",
    "time_field": "year",
    "time_periods": ["2020", "2021", "2022"],
    "neighbor_type": "distance",
    "distance": 1000
  }'
```

## Background Jobs

This analysis runs as a background job. The worker:

1. Fetches queued `hotspot_timeseries` jobs
2. Validates input parameters
3. Performs hot spot analysis for each time period
4. Combines results
5. Creates output dataset
6. Marks job as completed

## Performance Considerations

- Processing time depends on dataset size and number of time periods
- Each time period requires separate hot spot analysis
- Consider limiting number of time periods for large datasets
- Results can be large for many time periods

## Related Documentation

- [Hot Spot Analysis Tool](../analysis-tools/hotspot.md)
- [Analysis API](../api/analysis.md)
- [Workers Overview](index.md)