Merge pull request #20 from harp-tech/gl-dev

Surface public API through top-level package

Author: glopesdev

README.md

@@ -4,39 +4,55 @@ A low-level interface to data collected with the [Harp](https://harp-tech.org/)
 
 ## Data model 
 
-To regenerate Pydantic data models from device schema definitions, activate a virtual environment with `dev` dependencies, and run:
+The interface makes use of a Pydantic data model generated from Harp device schema definitions. The schema data classes are used to automatically generate binary readers for each device.
+
+All binary data files from a single device need to be stored in the same folder alongside the device meta-schema, named `device.yml`. Each register file should have the following naming convention `<deviceName>_<registerAddress>.bin`.
+
+For example, for a dataset collected with a `Behavior` device, you might have:
 
 ```
-datamodel-codegen --input ./reflex-generator/schema/device.json --output harp/model.py --output-model-type pydantic_v2.BaseModel
+📦device.harp
+ ┣ 📜Behavior_0.bin
+ ┣ 📜Behavior_1.bin
+...
+ ┗ 📜device.yml
 ```
 
-> [!IMPORTANT]
-> Currently code generation adds an unwanted field at the very end of the data model definition `registers: Optional[Any] = None`. This declaration needs to be removed for serialization to work properly.
-
 ## How to use
 
-### Read Harp device schema from YML file
-
-```python
-from harp.schema import read_schema
-schema = read_schema('device.yml')
-```
-
 ### Create device reader object from schema
 
 ```python
-from harp.reader import create_reader
-reader = create_reader(schema)
+import harp
+reader = harp.create_reader("device.harp")
 ```
 
 ### Read data from named register
 
 ```python
-reader.OperationControl.read("data/Behavior_10.bin")
+reader.OperationControl.read()
 ```
 
 ### Access register metadata
 
 ```python
 reader.OperationControl.register.address
 ```
+
+### Create device reader object with UTC datetime format
+
+```python
+reader = harp.create_reader("device.harp", epoch=harp.REFERENCE_EPOCH)
+```
+
+### Read data with message type information
+
+```python
+reader.OperationControl.read(keep_type=True)
+```
+
+### Read data from a specific file
+
+```python
+reader.OperationControl.read("data/Behavior_10.bin")
+```

harp/__init__.py

@@ -0,0 +1,3 @@
+from harp.io import REFERENCE_EPOCH, MessageType, read
+from harp.reader import create_reader
+from harp.schema import read_schema

harp/io.py

@@ -6,11 +6,13 @@
 import numpy as np
 import pandas as pd
 
-"""The reference epoch for UTC harp time."""
 REFERENCE_EPOCH = datetime(1904, 1, 1)
+"""The reference epoch for UTC harp time."""
 
 
 class MessageType(IntEnum):
+    """Specifies the type of a Harp message."""
+
     NA = 0
     READ = 1
     WRITE = 2
@@ -41,22 +43,33 @@ def read(
     epoch: Optional[datetime] = None,
     keep_type: bool = False,
 ):
-    """
-    Read single-register Harp data from the specified file.
-
-    :param file: Open file object or filename containing binary data from
-      a single device register.
-    :param address: Expected register address. If specified, the address of
-      the first message in the file is used for validation.
-    :param dtype: Expected data type of the register payload. If specified, the
-      payload type of the first message in the file is used for validation.
-    :param length: Expected number of elements in register payload. If specified,
-      the payload length of the first message in the file is used for validation.
-    :param columns: The optional column labels to use for the data values.
-    :param epoch: Reference datetime at which time zero begins. If specified,
-      the result data frame will have a datetime index.
-    :param keep_type: Specifies whether to include a column with the message type.
-    :return: A pandas data frame containing message data, sorted by time.
+    """Read single-register Harp data from the specified file.
+
+    Parameters
+    ----------
+    file
+        Open file object or filename containing binary data from
+        a single device register.
+    address
+        Expected register address. If specified, the address of
+        the first message in the file is used for validation.
+    dtype
+        Expected data type of the register payload. If specified, the
+        payload type of the first message in the file is used for validation.
+    length
+        Expected number of elements in register payload. If specified, the
+        payload length of the first message in the file is used for validation.
+    columns
+        The optional column labels to use for the data values.
+    epoch
+        Reference datetime at which time zero begins. If specified,
+        the result data frame will have a datetime index.
+    keep_type
+        Specifies whether to include a column with the message type.
+
+    Returns
+    -------
+        A pandas data frame containing message data, sorted by time.
     """
     data = np.fromfile(file, dtype=np.uint8)
     if len(data) == 0:

harp/reader.py

@@ -213,6 +213,30 @@ def create_reader(
     epoch: Optional[datetime] = None,
     keep_type: bool = False,
 ):
+    """Creates a device reader object from the specified dataset or schema.
+    
+    Parameters
+    ----------
+    device
+        A path to the device schema, dataset folder, or parsed device schema object
+        describing the device.
+    include_common_registers
+        Specifies whether to include the set of Harp common registers in the
+        parsed device schema object. If a parsed device schema object is provided,
+        this parameter is ignored.
+    epoch
+        The default reference datetime at which time zero begins. If specified,
+        the data frames returned by each register reader will have a datetime index.
+    keep_type
+        Specifies whether to include a column with the message type by default.
+
+    Returns
+    -------
+        A device reader object which can be used to read binary data for each
+        register or to access metadata about each register. Individual registers
+        can be accessed using dot notation using the name of the register as the
+        key.
+    """
     if isinstance(device, Model):
         base_path = Path(device.device)
     else:

harp/schema.py

@@ -14,6 +14,22 @@ def _read_common_registers() -> Registers:
 def read_schema(
     file: Union[str, PathLike, TextIO], include_common_registers: bool = True
 ) -> Model:
+    """Read and parse a device schema from the specified file.
+    
+    Parameters
+    ----------
+    file
+        Open file object or filename containing a YAML text stream describing
+        a device schema.
+    include_common_registers
+        Specifies whether to include the set of Harp common registers in the
+        returned device schema object.
+
+    Returns
+    -------
+        A Pydantic model object representing the Harp device schema.
+    """
+
     if isinstance(file, (str, PathLike)):
         with open(file) as fileIO:
             return read_schema(fileIO)