Modernize CLI: Consolidate redundant scripts, implement robust CLI, add pyproject.toml, and enhance documentation with type hints and docstrings

Author: argahsuknesib

.gitignore

@@ -1,2 +1,5 @@
 /data
 /venv
+__pycache__/
+*.py[cod]
+.pytest_cache/

README.md

@@ -1,23 +1,76 @@
 # Feather RDF Mapper
 
-A simple mapper to map and convert .feather data files into RDF triples in a specified ontology, specifically in the N-Triples format.
+A robust CLI tool to map and convert `.feather` data files into RDF triples (N-Triples format) based on a specified ontology.
+
+## Features
+
+- **Flexible Input**: Process a single `.feather` file or an entire directory recursively.
+- **Metric Filtering**: Filter for specific metrics (e.g., `environment.temperature`, `org.dyamand.types.health.SpO2`).
+- **Resampling**: Support for resampling data at a specified rate (in seconds).
+- **Event Limiting**: Limit the number of processed events for quick testing.
+- **Modern Packaging**: Uses `pyproject.toml` for easy installation and dependency management.
+
+## Installation
+
+It is highly recommended to use a virtual environment.
+
+```bash
+# Clone the repository
+git clone <repo-url>
+cd stream-aggregator-evaluation-mapper
+
+# Install the package in editable mode
+pip install -e .
+```
+
+This will install all necessary dependencies and provide the `feather-mapper` command globally in your environment.
 
 ## Usage
 
-Note: It is highly advised to use a venv with the required packages installed, as described in the [requirements](./requirements.txt) file.
+You can run the mapper using the installed `feather-mapper` command:
+
+```bash
+feather-mapper -i <input_path> -o <output_file> [options]
+```
+
+Alternatively, you can still run it as a script:
+
+```bash
+python3 mapper/cli.py -i <input_path> -o <output_file> [options]
+```
+
+### Arguments
+
+- `-i`, `--input`: (Required) Path to a single `.feather` file or a directory containing `.feather` files.
+- `-o`, `--output`: (Required) Path to the output `.nt` (RDF) file.
+- `-m`, `--metrics`: (Optional) Space-separated list of metrics to filter by.
+- `-n`, `--limit`: (Optional) Maximum number of total events to process.
+- `-s`, `--sample-rate`: (Optional) Resampling rate in seconds.
+
+### Examples
+
+**Process a single file for specific metrics:**
+```bash
+feather-mapper -i data/participant6.feather -o output/results.nt -m environment.temperature wearable.skt
+```
+
+**Process a directory with resampling and an event limit:**
+```bash
+feather-mapper -i /path/to/dataset/ -o output/spo2_data.nt -m org.dyamand.types.health.SpO2 -n 1000 -s 2.0
+```
+
+## Testing
+
+To run the unit tests:
 
-- Specify the name of the .feather file and the .nt file in the `mapper.py` file inside the mapper folder.
-- Run the file as a script with,
 ```bash
-python3 mapper.py
+python3 -m unittest discover mapper/tests
 ```
-- The .nt file will be created.
 
 ## License
 
-This code is copyrighted by [Ghent University - imec](https://www.ugent.be/ea/idlab/en) and 
-released under the [MIT Licence](./LICENCE)
+This code is copyrighted by [Ghent University - imec](https://www.ugent.be/ea/idlab/en) and released under the [MIT Licence](./LICENCE).
 
 ## Contact
 
-For any questions, please contact [Kush](mailto:kushagrasingh.bisen@ugent.be).
+For any questions, please contact [Kush](mailto:kushagrasingh.bisen@ugent.be).

mapper/__init__.py

@@ -0,0 +1 @@
+# Mapper package

mapper/cli.py

@@ -0,0 +1,56 @@
+import argparse
+import sys
+import os
+
+# Add the parent directory to sys.path to allow running this script directly
+sys.path.append(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+from mapper.process import process_input
+from mapper.core import logger
+
+def main() -> None:
+    """
+    Entrypoint for the Feather to RDF Mapper CLI.
+    Parses command line arguments and initiates the data processing.
+    """
+    parser = argparse.ArgumentParser(description="Feather to RDF (Turtle) Mapper CLI")
+    
+    parser.add_argument("-i", "--input", required=True, 
+                        help="Path to a single .feather file or a directory containing .feather files")
+    
+    parser.add_argument("-o", "--output", required=True, 
+                        help="Path to the output .nt (RDF) file")
+    
+    parser.add_argument("-m", "--metrics", nargs="+", 
+                        help="List of metrics to filter by (e.g., environment.temperature wearable.skt)")
+    
+    parser.add_argument("-n", "--limit", type=int, 
+                        help="Maximum number of total events to process")
+    
+    parser.add_argument("-s", "--sample-rate", type=float, 
+                        help="Resampling rate in seconds (optional)")
+
+    args = parser.parse_args()
+
+    # Ensure output directory exists
+    output_dir = os.path.dirname(args.output)
+    if output_dir and not os.path.exists(output_dir):
+        os.makedirs(output_dir)
+
+    try:
+        process_input(
+            input_path=args.input,
+            output_file=args.output,
+            metrics=args.metrics,
+            limit=args.limit,
+            sample_rate=args.sample_rate
+        )
+    except KeyboardInterrupt:
+        logger.info("Process interrupted by user.")
+        sys.exit(0)
+    except Exception as e:
+        logger.error(f"An unexpected error occurred: {e}")
+        sys.exit(1)
+
+if __name__ == "__main__":
+    main()