Read Events¶
The read command streams detection events from the detector. Events contain hit patterns, timing, environmental data, and optional GNSS information.
Purpose of Event Reading¶
Detection events are the core data from cosmic ray measurements:
- Hit patterns: Which detector channels registered the event (hit1, hit2, hit3, hit_type)
- ADC values: Energy information in raw and calibrated units (adc, adc_raw, adc_mv)
- Timing: Microsecond-precision timestamps and intervals (received_us, detected_us, timedelta_us)
- Environmental: Temperature, pressure, humidity
- GNSS: Geolocation when available (latitude, longitude, altitude, satellites)
Basic Event Reading (JSONL Format)¶
By default, events are saved as JSONL (one JSON object per line) for easy processing and archival:
$ uv run kazunoko read 5
{"type": "event", "status": "ok", "received_us": 1766796457448117, "hit1": 1, "hit2": 0, "hit3": 0, "adc": 1205, "hit_type": 1, "adc_raw": 1195, "adc_mv": 1100, "tmp_c": 0, "atm_pa": 0, "hmd_pct": 0, "uptime_ms": 53675, "timedelta_us": 884636, "detected_us": 1766584357752874, "gnss_time_us": 0, "gnss_latitude": 0, "gnss_longitude": 0, "gnss_altitude": 0, "gnss_satellites": 0, "gnss_fix_quality": 0, "gnss_hdop": 0, "gnss_fix_valid": false}
{"type": "event", "status": "ok", "received_us": 1766796457449001, "hit1": 1, "hit2": 1, "hit3": 0, "adc": 1210, "hit_type": 3, "adc_raw": 1200, "adc_mv": 1105, "tmp_c": 0, "atm_pa": 0, "hmd_pct": 0, "uptime_ms": 53760, "timedelta_us": 79886, "detected_us": 1766584357837760, "gnss_time_us": 0, "gnss_latitude": 0, "gnss_longitude": 0, "gnss_altitude": 0, "gnss_satellites": 0, "gnss_fix_quality": 0, "gnss_hdop": 0, "gnss_fix_valid": false}
{"type": "event", "status": "ok", "received_us": 1766796457450003, "hit1": 0, "hit2": 1, "hit3": 1, "adc": 1215, "hit_type": 6, "adc_raw": 1205, "adc_mv": 1110, "tmp_c": 0, "atm_pa": 0, "hmd_pct": 0, "uptime_ms": 53850, "timedelta_us": 78224, "detected_us": 1766584357916076, "gnss_time_us": 0, "gnss_latitude": 0, "gnss_longitude": 0, "gnss_altitude": 0, "gnss_satellites": 0, "gnss_fix_quality": 0, "gnss_hdop": 0, "gnss_fix_valid": false}
{"type": "event", "status": "ok", "received_us": 1766796457451005, "hit1": 1, "hit2": 1, "hit3": 1, "adc": 1220, "hit_type": 7, "adc_raw": 1210, "adc_mv": 1115, "tmp_c": 0, "atm_pa": 0, "hmd_pct": 0, "uptime_ms": 53930, "timedelta_us": 77958, "detected_us": 1766584357994000, "gnss_time_us": 0, "gnss_latitude": 0, "gnss_longitude": 0, "gnss_altitude": 0, "gnss_satellites": 0, "gnss_fix_quality": 0, "gnss_hdop": 0, "gnss_fix_valid": false}
{"type": "event", "status": "ok", "received_us": 1766796457452007, "hit1": 0, "hit2": 0, "hit3": 1, "adc": 1225, "hit_type": 4, "adc_raw": 1215, "adc_mv": 1120, "tmp_c": 0, "atm_pa": 0, "hmd_pct": 0, "uptime_ms": 54010, "timedelta_us": 78008, "detected_us": 1766584358072000, "gnss_time_us": 0, "gnss_latitude": 0, "gnss_longitude": 0, "gnss_altitude": 0, "gnss_satellites": 0, "gnss_fix_quality": 0, "gnss_hdop": 0, "gnss_fix_valid": false}
Alternative Output Formats¶
Events can be converted to other formats for different analysis tools:
CSV (Comma-Separated Values)¶
For import into spreadsheets or data analysis tools:
$ uv run kazunoko read 5 --format csv
event,ok,1766796457448117,1,0,0,1205,1,1195,1100,0,0,0,53675,884636,1766584357752874,0,0,0,0,0,0,0,false
event,ok,1766796457449001,1,1,0,1210,3,1200,1105,0,0,0,53760,79886,1766584357837760,0,0,0,0,0,0,0,false
event,ok,1766796457450003,0,1,1,1215,6,1205,1110,0,0,0,53850,78224,1766584357916076,0,0,0,0,0,0,0,false
event,ok,1766796457451005,1,1,1,1220,7,1210,1115,0,0,0,53930,77958,1766584357994000,0,0,0,0,0,0,0,false
event,ok,1766796457452007,0,0,1,1225,4,1215,1120,0,0,0,54010,78008,1766584358072000,0,0,0,0,0,0,0,false
SSV (Space-Separated Values)¶
For command-line processing and pipelines:
$ uv run kazunoko read 5 --format ssv
event ok 1766796457448117 1 0 0 1205 1 1195 1100 0 0 0 53675 884636 1766584357752874 0 0 0 0 0 0 0 false
event ok 1766796457449001 1 1 0 1210 3 1200 1105 0 0 0 53760 79886 1766584357837760 0 0 0 0 0 0 0 false
event ok 1766796457450003 0 1 1 1215 6 1205 1110 0 0 0 53850 78224 1766584357916076 0 0 0 0 0 0 0 false
event ok 1766796457451005 1 1 1 1220 7 1210 1115 0 0 0 53930 77958 1766584357994000 0 0 0 0 0 0 0 false
event ok 1766796457452007 0 0 1 1225 4 1215 1120 0 0 0 54010 78008 1766584358072000 0 0 0 0 0 0 0 false
LTSV (Labeled-Tab Separated Values)¶
For human-readable, self-documenting format with field names:
$ uv run kazunoko read 5 --format ltsv
type=event status=ok received_us=1766796457448117 hit1=1 hit2=0 hit3=0 adc=1205 hit_type=1 adc_raw=1195 adc_mv=1100 tmp_c=0 atm_pa=0 hmd_pct=0 uptime_ms=53675 timedelta_us=884636 detected_us=1766584357752874 gnss_time_us=0 gnss_latitude=0 gnss_longitude=0 gnss_altitude=0 gnss_satellites=0 gnss_fix_quality=0 gnss_hdop=0 gnss_fix_valid=false
type=event status=ok received_us=1766796457449001 hit1=1 hit2=1 hit3=0 adc=1210 hit_type=3 adc_raw=1200 adc_mv=1105 tmp_c=0 atm_pa=0 hmd_pct=0 uptime_ms=53760 timedelta_us=79886 detected_us=1766584357837760 gnss_time_us=0 gnss_latitude=0 gnss_longitude=0 gnss_altitude=0 gnss_satellites=0 gnss_fix_quality=0 gnss_hdop=0 gnss_fix_valid=false
type=event status=ok received_us=1766796457450003 hit1=0 hit2=1 hit3=1 adc=1215 hit_type=6 adc_raw=1205 adc_mv=1110 tmp_c=0 atm_pa=0 hmd_pct=0 uptime_ms=53850 timedelta_us=78224 detected_us=1766584357916076 gnss_time_us=0 gnss_latitude=0 gnss_longitude=0 gnss_altitude=0 gnss_satellites=0 gnss_fix_quality=0 gnss_hdop=0 gnss_fix_valid=false
type=event status=ok received_us=1766796457451005 hit1=1 hit2=1 hit3=1 adc=1220 hit_type=7 adc_raw=1210 adc_mv=1115 tmp_c=0 atm_pa=0 hmd_pct=0 uptime_ms=53930 timedelta_us=77958 detected_us=1766584357994000 gnss_time_us=0 gnss_latitude=0 gnss_longitude=0 gnss_altitude=0 gnss_satellites=0 gnss_fix_quality=0 gnss_hdop=0 gnss_fix_valid=false
type=event status=ok received_us=1766796457452007 hit1=0 hit2=0 hit3=1 adc=1225 hit_type=4 adc_raw=1215 adc_mv=1120 tmp_c=0 atm_pa=0 hmd_pct=0 uptime_ms=54010 timedelta_us=78008 detected_us=1766584358072000 gnss_time_us=0 gnss_latitude=0 gnss_longitude=0 gnss_altitude=0 gnss_satellites=0 gnss_fix_quality=0 gnss_hdop=0 gnss_fix_valid=false
Use Case: Post-Processing JSONL to Other Formats¶
JSONL is the recommended format for archival and programmatic processing. You can convert JSONL files to other formats after collection:
Python Post-Processing¶
#!/usr/bin/env python3
"""
convert_events.py - Convert events.jsonl to different formats
"""
from pathlib import Path
import json
import csv
def main():
"""Convert JSONL events file to multiple formats."""
events_path = Path("events.jsonl")
# Read all events
events = []
with events_path.open() as f:
for line in f:
if line.strip():
events.append(json.loads(line))
if not events:
print("No events found")
return
# Get field names from first event
fieldnames = list(events[0].keys())
# Convert to CSV
csv_path = events_path.with_suffix(".csv")
with csv_path.open("w", newline="") as f:
writer = csv.DictWriter(f, fieldnames=fieldnames)
writer.writeheader()
writer.writerows(events)
print(f"Saved {csv_path}")
# Convert to TSV (Tab-Separated Values)
tsv_path = events_path.with_suffix(".tsv")
with tsv_path.open("w", newline="") as f:
writer = csv.DictWriter(f, fieldnames=fieldnames, delimiter="\t")
writer.writeheader()
writer.writerows(events)
print(f"Saved {tsv_path}")
# Convert to LTSV (Labeled-Tab Separated Values)
ltsv_path = events_path.with_stem(events_path.stem + "_labeled").with_suffix(".ltsv")
with ltsv_path.open("w") as f:
for event in events:
pairs = [f"{k}={v}" for k, v in event.items()]
f.write("\t".join(pairs) + "\n")
print(f"Saved {ltsv_path}")
if __name__ == "__main__":
main()
Recommendation:
- Archival: Always save events as JSONL (preserves all data, structured, queryable)
- Analysis: Convert to CSV for spreadsheets, TSV for data science tools
- Human inspection: Use LTSV format for reading individual events
- Streaming: Use
--format csvor--format ltsvdirectly if not saving to file