docs: add comprehensive module and function docstrings

- Added module-level docstrings to all Python files explaining purpose, main functions, and usage
- Significantly expanded read_device() and process() docstrings with:
  - Detailed parameter descriptions with types and defaults
  - Multiple usage examples covering common scenarios
  - Return value documentation with DataFrame and info dict structure
  - "See Also" and "Notes" sections for cross-references
- References to GLOSSARY.md for info dict field descriptions
- Improved consistency and completeness across all documentation

Author: chanshing

src/actipy/__init__.py

@@ -1,3 +1,43 @@
+"""
+Actipy: A Python package for processing accelerometer data.
+
+This package provides tools to read and process data from wearable accelerometer
+devices including Axivity3/6 (.cwa), Actigraph (.gt3x), GENEActiv (.bin), and
+Matrix (.bin) files.
+
+Main Functions
+--------------
+read_device : Read and process accelerometer device file
+process : Process pandas.DataFrame of acceleration time-series
+
+Modules
+-------
+reader : Device file reading and high-level processing
+processing : Signal processing functions (filtering, calibration, resampling, etc.)
+matrix_reader : Matrix device-specific binary file reader
+
+Examples
+--------
+Basic usage with default processing:
+
+>>> import actipy
+>>> data, info = actipy.read_device("sample.cwa.gz")
+
+With custom processing options:
+
+>>> data, info = actipy.read_device(
+...     "sample.cwa.gz",
+...     lowpass_hz=20,
+...     calibrate_gravity=True,
+...     detect_nonwear=True,
+...     resample_hz=50
+... )
+
+See Also
+--------
+For detailed documentation, visit: https://actipy.readthedocs.io/
+"""
+
 name = "actipy"
 __author__ = "Shing Chan, Aiden Doherty"
 __email__ = "shing.chan@ndph.ox.ac.uk, aiden.doherty@ndph.ox.ac.uk"

src/actipy/matrix_reader.py

@@ -1,3 +1,39 @@
+"""
+Binary file reader for Matrix wearable devices.
+
+This module provides a pure Python implementation for reading and parsing
+binary data files from Matrix wearable devices. Unlike other device readers
+in actipy, this does not use Java parsers.
+
+Binary File Structure
+---------------------
+Matrix .bin files consist of:
+1. Remarks block (512 bytes) - metadata text
+2. File header (16 bytes) - signature, packet count, sensor ranges
+3. Data packets - each containing timestamped sensor readings
+
+Each packet contains:
+- Header: CRC32 checksum, timestamps, sample counts
+- Payload: Accelerometer, gyroscope, temperature, heart rate data
+
+Main Functions
+--------------
+bin2csv : Convert Matrix .bin file to CSV format
+extract_metadata : Read file metadata without processing full dataset
+is_matrix_bin_file : Check if file is a valid Matrix binary file
+
+Notes
+-----
+- Supports compressed files (.gz, .zip, .tar.gz, .tgz)
+- Validates data integrity using CRC32 checksums
+- Resamples multi-rate sensor data to uniform time grid
+- Progress tracking via tqdm progress bars
+
+See Also
+--------
+Binary format documentation: Matrix wearable device specification
+"""
+
 import os
 import logging
 import struct

src/actipy/processing.py

@@ -1,3 +1,36 @@
+"""
+Signal processing functions for accelerometer data.
+
+This module provides a suite of signal processing operations for cleaning,
+calibrating, and analyzing accelerometer time-series data. All functions
+operate on pandas DataFrames with DateTimeIndex and return both processed
+data and metadata dictionaries.
+
+Main Processing Functions
+-------------------------
+quality_control : Basic data quality checks and statistics
+lowpass : Butterworth lowpass filtering
+calibrate_gravity : Gravity-based calibration (van Hees et al. 2014)
+flag_nonwear : Detect and flag non-wear periods
+resample : Nearest-neighbor resampling to uniform frequency
+
+Utility Functions
+-----------------
+find_nonwear_segments : Identify non-wear periods without flagging data
+butterfilt : Butterworth filter implementation
+chunker : Generator for processing data in time-based chunks
+
+Memory Efficiency
+-----------------
+Functions that process large datasets (lowpass, calibrate_gravity, resample)
+use chunked processing and memory-mapped temporary files to minimize RAM usage.
+
+Notes
+-----
+All functions preserve the input DataFrame structure and return tuples of
+(processed_data, info_dict) where info_dict contains processing metadata.
+"""
+
 import os
 import tempfile
 import numpy as np

src/actipy/read_cwa.py

@@ -1,3 +1,43 @@
+"""
+Command-line interface for processing accelerometer device files.
+
+This script provides a command-line tool (read_cwa) for reading and processing
+accelerometer data from device files. Despite the name 'read_cwa', it supports
+multiple device formats.
+
+Supported Formats
+-----------------
+- Axivity AX3/AX6 (.cwa)
+- Actigraph (.gt3x)
+- GENEActiv (.bin)
+- Matrix (.bin)
+
+Usage
+-----
+Basic usage with default processing:
+
+    $ read_cwa sample.cwa.gz -o outputs/
+
+With custom processing options:
+
+    $ read_cwa sample.cwa.gz -o outputs/ --lowpass-hz 20 --resample-hz 50 \\
+      --calibrate-gravity --detect-nonwear
+
+Time filtering:
+
+    $ read_cwa sample.cwa.gz -o outputs/ --start-time "2014-05-07 18:00:00" \\
+      --end-time "2014-05-09 18:00:00" --skipdays 1 --cutdays 2
+
+Output
+------
+Creates two files in the output directory:
+- {basename}.csv.gz : Processed acceleration data
+- {basename}-Info.json : Processing metadata and statistics
+
+For full option list, run:
+    $ read_cwa --help
+"""
+
 import time
 from pathlib import Path
 import argparse
@@ -9,16 +49,6 @@
 
 from actipy import read_device
 
-"""
-How to run the script:
-
-```bash
-python src/actipy/read_cwa.py data/test.bin 
-
-python src/actipy/read_cwa.py data/test.bin -o data/prepared/ -r 30 -g -f 20 -w -c x y z -q
-```
-"""
-
 
 def main():
     parser = argparse.ArgumentParser(