Update ambiguous column descriptions

Authored by Opus 4.6

Several columns in `resources/table_descriptions.json` remain unclear even after reading their full descriptions and table context. These fall into 7 main categories:

### Main Categories of Remaining Ambiguity

1. **Empty descriptions** — columns with "no description" field
2. **Undefined thresholds** — metrics lacking specific cutoff values or interpretation ranges
3. **Confusing near-duplicates** — pairs of columns with overlapping meanings and unclear distinction
4. **Unclear numbering schemes** — numbered keypoints lacking anatomical mapping
5. **Unexplained variability** — data quality or source varies per-row with no way to detect it
6. **Mystery metrics** — custom formulas or composite metrics with insufficient detail
7. **Semantic ambiguities** — relationships between columns described as "not exact" or contradictory

---
```yaml
## Flagged Columns

# Columns that remain unclear even AFTER reading their descriptions
# and the containing table descriptions

electrodes:
- reference
# "the reference electrode or referencing scheme used"
# Unclear: what are the possible values? A channel number? A string like "GND"? A probe name?

epochs:
- interval_names
# "names of other intervals tables that contain trial data from the epoch"
# Unclear: is this a list of strings? A single name? How are multiple names formatted?
- tags
# "user-defined tags"
# Unclear: what is the format? None? Comma-separated? JSON? How are they actually used?

performance:
- is_first_block_aud
# "whether the rewarded modality of the first block in the task was auditory"
# Unclear: this appears per-block row but seems like per-session metadata.
# Does every row in a session have the same value? If so, why repeat it?

trials:
- trial_index_in_block
# Description: (EMPTY)
# Completely unclear.
- stim_name
# "the stimulus presented; corresponds to a unique stimulus definition, randomized over trials"
# Unclear: what are the actual possible values? (vis1, vis2, sound1, sound2, catch, ...)
- rewarded_modality
# "indicates the name of the rewarded modality in each block; not an exact correspondence with the values in `stim_name`"
# Unclear: what does "not an exact correspondence" mean precisely?
# When would rewarded_modality == "vis" but stim_name != "vis1" or "vis2"?
- is_task_control_correct
# Description says the task control script may be incorrect due to "latencies incurred by hardware or processing"
# and may be incorrect due to "bugs in the task control script"
# Unclear: so True doesn't guarantee correctness? What is this column actually useful for?
- is_instruction
# "the stimulus presented was not random, but specifically chosen to inform the subject of a change in rewarded modality"
# Unclear: does EVERY instruction trial have is_instruction=True, or can some be missed/marked False?

units:
- default_qc
# "typically combines multiple metrics (e.g., ISI violations, presence ratio, amplitude cutoff) into a single pass/fail criterion"
# Unclear: which specific metrics? What are the exact thresholds used?
- decoder_label
# "predicted cell type or classification label from an automated decoder/classifier"
# Unclear: which decoder? What are the possible label values?
- decoder_probability
# "confidence/probability score from the decoder for the assigned label"
# Unclear: which decoder? What probability model underlies the score?
- activity_drift
# Detailed custom metric using anderson_ksamp test with normalization "dividing by 100 and clipping values to [0, 1]"
# Unclear: why 100? Why clip? Is this a standardized metric or custom to this dataset?
# How to interpret gray areas (~0.05)?
- d_prime
# "classification accuracy metric based on linear discriminant analysis (LDA) in PCA space"
# Note: "d' = 2 corresponds to ~84% classification accuracy" — so this is NOT the classical d'prime statistic?
# Unclear: confusing name collision with behavioral d'prime in performance table
- is_not_drift
# "whether the unit has low activity drift (`activity_drift < 0.1`); false wherever `activity_drift` is nan"
# Unclear: False means EITHER high drift OR NaN? These are semantically different but mapped to same value.
- peak_channel
# "channel number ... 0-indexed or 1-indexed depending on convention"
# Unclear: WHICH convention is used in THIS dataset?
- peak_electrode
# "index in `electrodes` table of channel with largest amplitude waveform"
# vs. `peak_channel` (above)
# Unclear: what is the difference? Why both exist?
- spike_amplitudes
# "values may be from raw data extraction or template scaling factors depending on spike sorting method"
# Unclear: you cannot compare amplitudes between two units if they use different sources.
# How do you know which source was used for each unit?
- rp_contamination
# "estimated contamination rate based on refractory period violations; similar to isi_violations_ratio; quantifies false positives"
# vs. `rp_violations` and `isi_violations_ratio`
# Unclear: exact formula or relationship to isi_violations_ratio?
- recovery_slope
# "slope of the waveform during the recovery/repolarization phase after the trough"
# vs. `repolarization_slope` ("slope of the waveform during the repolarization phase; similar to recovery_slope")
# Unclear: what is the practical difference between "recovery" and "repolarization"?
# The descriptions suggest they are the same thing.
- silhouette
# "compares the mean distance between a spike and other spikes in its cluster to the mean distance to spikes in the nearest other cluster"
# Unclear: the description is mathematically confusing. How does one interpret specific values?
# (e.g., is 0.3 good? is -0.1 bad? relative to other metrics?)
- spread
# "spatial spread of the unit's waveform across electrodes in micrometers; measures how far from the peak electrode the waveform is still detectable"
# Unclear: what threshold defines "still detectable"? (noise floor? SNR threshold?)
- structure
# "brain structure/region name where the unit was recorded; may use standardized ontology (e.g., Allen CCF region names)"
# vs. `location` ("anatomical location or brain region name where the unit was recorded; may be manually annotated or automatically determined")
# Unclear: what is the semantic difference between "structure" and "location"?
# Both sound like they describe brain regions. When/why do they differ?
- channels
# "1-indexed channel numbers on the probe that the unit was recorded on (1 is the tip of the probe)"
# vs. `peak_channel`, `peak_electrode`, `electrodes`
# Unclear: this is a multichannel unit. Does `channels` list ALL recording channels,
# or only a subset? How is the order determined?
- num_spikes
# "total number of detected spikes for this unit across all observation intervals"
# vs. `spike_times` (provided as raw data)
# Unclear: is `num_spikes == len(spike_times)`? If so, why store both?

dlc_eye_camera:
- cr1_x, cr2_x, ... cr12_x (and y, likelihood variants)
# Individual columns all have description: "no description"
# Table description mentions "cr" = corneal reflection but does not explain the numbering (1-12)
# Unclear: what do the 12 numbers represent? 12 different reference points around the CR? Time steps?
# Different eyes?
- eye1_x, eye2_x, ... eye12_x (and y, likelihood variants)
# Same as above — "no description", table says "eye" = inner eyelid perimeter
# Unclear: why 12 points? Anatomical landmarks around the eye? How to use them?
- pupil1_x, pupil2_x, ... pupil12_x (and y, likelihood variants)
# Same as above — "no description", table says "pupil" = pupil perimeter
# Unclear: why 12 points? Are they equally spaced around the pupil?

eye_tracking:
- cr_is_bad_frame, eye_is_bad_frame, pupil_is_bad_frame
# "[bool] frames which should not be used due to low confidence ... (typically caused by blinking, grooming, poor lighting)"
# Unclear: what confidence threshold triggers marking as bad? (0.5? 0.7?)
- cr_phi, eye_phi, pupil_phi
# "counterclockwise rotation of major-axis ... relative to horizontal-axis of video, in radians"
# Unclear: is 0 rad always pointing right? Up? What direction is positive rotation?

lp_front_camera:
- ear_base_l_pca_error, ear_tip_l_pca_error, ... (and all other `*_pca_error` columns)
# "Euclidean distance in pixels between the original keypoint prediction and its prediction after projection to and from PCA space"
# Unclear: PCA of what? (all frames? all keypoints? all animals?) High error = bad prediction?
# Is there an error threshold for flagging bad frames?
- ear_base_l_temporal_norm, ear_tip_l_temporal_norm, ... (and all other `*_temporal_norm` columns)
# "Euclidean distance in pixels between keypoint predictions on successive time bins"
# Unclear: what is the size of a "time bin"? 1 frame? 10 ms? What does a high value mean?
- (all `*_likelihood`, `*_x`, `*_y` columns with description: "no description")
# Lightning Pose table description is detailed, but all individual column descriptions are empty
# Unclear: what are the 12 facial features being tracked? Which numbered keypoints correspond to which anatomy?

lp_side_camera:
- (same issues as lp_front_camera, including all empty descriptions and unclear numbering)

facemap_front_camera:
- data
# "motion SVD for video from front camera; shape is number of frames by number of components (500)"
# Unclear: what does each of the 500 SVD components represent? How are they ordered?
# (by variance? by anatomical region? arbitrary?)
# How should users interpret or use individual components?

facemap_side_camera:
- data
# Same as facemap_front_camera
```
## Next Steps

These ambiguities should be resolved by:
- Adding descriptions to empty-description columns
- Documenting thresholds, formulas, and parameter choices
- Clarifying relationships between similar columns
- Mapping numbered keypoints to anatomical structures