Add lazy DATA helpers (only_text docs, as_memmap, read_events)

README.md

@@ -27,6 +27,35 @@ support (including support for importing FlowJo 10 workspaces).
 If you have any questions about FlowIO, find any bugs, or feel something is missing 
 from the documentation [please submit an issue to the GitHub repository here](https://github.com/whitews/FlowIO/issues/new/).
 
+### Metadata probe and lazy DATA access
+
+For channel / `$TOT` / datatype checks without loading events, open a file with
+`FlowData(path, only_text=True)`. That parses HEADER + TEXT (and ANALYSIS) and
+leaves `events` as `None`, while still exposing DATA offsets and related metadata.
+
+For uniform IEEE float layouts (`$DATATYPE=F` or `D`), you can then memory-map or
+subsample events without a full in-memory load:
+
+```python
+from flowio import FlowData
+
+# Lightweight metadata probe
+meta = FlowData("sample.fcs", only_text=True)
+print(meta.pnn_labels, meta.event_count, meta.data_type)
+
+# Read-only memmap shaped (event_count, channel_count); raw on-disk values
+mm = meta.as_memmap()
+
+# Selected 0-based event rows (preprocessed by default, like as_array())
+rows = meta.read_events(indices=[0, 10, 100])
+
+# Raw stored values without gain/log/time scaling
+raw_rows = meta.read_events(indices=[0, 10, 100], preprocess=False)
+```
+
+ASCII and variable bit-width integer layouts raise `UnsupportedLazyDataError` from
+these helpers; load those files normally (without `only_text=True`) and use
+`read_events()` / `as_array()` on the in-memory events.
 ## Installation
 
 The recommended way to install FlowIO is via the `pip` command:

src/flowio/exceptions.py

@@ -38,3 +38,12 @@ class MultipleDataSetsError(FlowIOException):
     the 'nextdata' keyword.
     """
     pass
+
+
+class UnsupportedLazyDataError(FlowIOException):
+    """
+    Raised when lazy or memory-mapped DATA access is not supported for an FCS layout
+    (for example ASCII datatype, variable channel bit widths, or a non-path file handle
+    when event data was not loaded).
+    """
+    pass