---

name: io description: "Resolve data sources, load and save HyperTools data, and open numeric LSL streams." disable-model-invocation: true metadata: disco-role: operating license: MIT

IO

Use this route for hyp.load, hyp.save, hypertools.io.sources, hyp.io.lsl_stream, and the streaming helpers that turn resolved input into a form the visualization layer can consume.

Use this sub-skill when the user wants to

• Load built-in datasets, local files, remote URLs, Hugging Face ids, Google Sheets/Drive links, Dropbox links, FiveThirtyEight datasets, or Kaggle datasets.
• Save arrays, DataFrames, lists of arrays, fitted models, and other serializable results to disk.
• Check how a string resolves to a dataset source, or why a source failed.
• Open a live numeric LSL stream for later plotting.
• Inspect or normalize stream rows with hypertools.io.streaming.is_stream and row_to_vector.

Route elsewhere when the task is really about

• Plotting, animating, or exporting a figure/movie from loaded or streaming data: use ../visualization/.
• Choosing, tuning, or reusing reduce/align/normalize/ndims stages after a load: use ../pipeline/.
• Any model-selection or plotting-style work that does not start with source resolution or file/stream I/O.

Read first

• references/io-reference.md for source precedence, file formats, trust rules, remote handling, and LSL semantics.
• references/troubleshooting.md for missing extras, unsupported extensions, pickle trust, and LSL/network failures.
• scripts/smoke_io.py to run a tiny local round-trip check; add --lsl-local-smoke when pylsl is installed and you want a real local outlet/inlet check.

Fast routing guide

• Decide whether a string is a built-in name, local path, explicit prefix, or URL before doing anything else.
• If a remote payload is pickle-backed, require an explicit trust decision.
• If the extension is not a supported data format, expect pickle fallback unless the bytes clearly match a known binary format.
• If the input is an LSL outlet or stream generator, keep it numeric and hand the rendering step to the visualization route.
• If a raw string might be data or just text, use hypertools.io.sources.is_loadable_string before routing it.
• If hyp.load(..., reduce=..., ndims=..., align=..., normalize=...) is used on ordinary data, the pipeline owns those stage choices; streaming datasets reject those kwargs at load time.

Success signals

• hyp.load(...) returns raw data, a DataFrame/array/list/dict, or a streaming IterableDataset.
• hyp.save(...) creates the requested file and round-trips through hyp.load(...).
• hyp.io.lsl_stream(...) returns a generator of numeric vectors.
• The smoke script prints a round-trip success message and, when requested, a local LSL success message.