nutrient-analysis

# nutrient-analysis

Query and interpret soil nutrient data from soil-test-tracker to identify deficiencies, track improvement, and guide amendment decisions.

## When to Use

- Finding all fields with a specific nutrient below optimal
- Comparing nutrient values between two different test dates
- Identifying which amendment corrected a deficiency
- Explaining what a status badge (low, deficient, high) means
- Querying trend data for a specific nutrient over time

## Nutrient Status Interpretation

### Deficient

Value is below 50% of the optimal low threshold. Immediate action is needed before planting. Crop yields will be significantly affected.

Examples: pH below 3.0, OM below 1.5%, P below 10 ppm

### Low

Value is between the deficient threshold and the optimal low. Action recommended before next growing season. Minor yield reduction likely.

### Optimal

Value falls within the low-high range. No amendment needed.

### High

Value exceeds the optimal high threshold. Excess may lock out other nutrients. Avoid applying more of this nutrient.

## Analytical Queries

### Find all deficient fields

```bash
curl http://localhost:3004/api/analytics/field-summary
```

Filter in the response where any nutrient has `status: "deficient"`.

### Get nutrient trend for a specific field

```bash
# All nutrients over time
curl "http://localhost:3004/api/analytics/trends?field_id=..."

# Response includes per-nutrient arrays:
# { ph: [{date, value}], nitrogen: [{date, value}], ... }
```

### Compare two specific tests

```bash
# Get both tests
curl http://localhost:3004/api/tests/{test_id_1}
curl http://localhost:3004/api/tests/{test_id_2}

# Calculate delta per nutrient
# delta_ph = test2.ph - test1.ph
```

### Before/after amendment report

```bash
curl "http://localhost:3004/api/analytics/improvement?field_id=..."
```

Returns per-nutrient comparison between the test that prompted the amendment and the most recent test after it.

## Nutrient Relationships

Understanding how nutrients interact helps interpret test results:

| Situation | Cause / Solution |
|---|---|
| Low pH locks out Phosphorus | Raise pH with lime before adding P |
| High K competes with Mg | Balance K and Mg applications |
| Low OM reduces N availability | Compost and cover crops build OM |
| High pH (alkaline) causes Fe, Mn deficiency | Lower pH with sulfur |
| Very low CEC means nutrients leach quickly | Build OM to increase CEC |

## Amendment Matching

To find what amendment was applied for a specific deficiency:

```bash
# List amendments for a field
curl "http://localhost:3004/api/amendments?field_id=..."

# Filter by date range (after the deficient test)
curl "http://localhost:3004/api/amendments?field_id=...&from=2024-04-01"
```

## Radar Chart Interpretation

The Analytics radar chart shows each nutrient as a percentage of the optimal midpoint:
- 100% = exactly at the optimal midpoint
- Below 100% = below midpoint (may be low or deficient depending on distance)
- Above 100% = above midpoint (may be high depending on distance)

A "balanced" radar shows all axes close to 100% with roughly equal extension.

## Troubleshooting

### Improvement report shows no change

The improvement report compares the test linked to an amendment (via `test_id`) against the most recent test after the amendment application date. If the most recent test predates the amendment, no comparison is possible. Add a new test after the amendment was applied.

### Field shows different status than expected

The status is calculated server-side against the current optimal ranges at query time. If you change optimal ranges, previous test statuses are re-evaluated on the next query.