Add time zone metadata (#259)

* Add time zone metadata

Different metadata structure for gt3x and bin

* Bump actions checkout

* PR review modifications

Added IOError catch into readers
Remove GMT from timezone string

* Change to ValueError for bad extension

Author: Asanto32

.github/workflows/docs.yaml

@@ -15,7 +15,7 @@ jobs:
   build-and-publish-docs:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v5
     - name: Fetch LFS files
       run: git lfs pull
     - uses: actions/setup-python@v5

.github/workflows/pypi.yaml

@@ -17,7 +17,7 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v5
       with:
         fetch-depth: ${{ github.event_name == 'pull_request' && 2 || 0 }}
     - uses: actions/setup-python@v5

.github/workflows/release.yaml

@@ -17,7 +17,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
     - name: Check out the repo
-      uses: actions/checkout@v4
+      uses: actions/checkout@v5
       with:
         lfs: true
 

.github/workflows/test.yaml

@@ -21,7 +21,7 @@ jobs:
         python_version: ['3.10', '3.11', '3.12', '3.13']
         resolution: [lowest-direct, highest]
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v5
     - name: Install poetry
       run: pipx install poetry
 
@@ -57,7 +57,7 @@ jobs:
   ruff:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v5
     - name: Install poetry
       run: pipx install poetry
     - uses: actions/setup-python@v5
@@ -75,7 +75,7 @@ jobs:
   mypy:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v5
     - name: Install poetry
       run: pipx install poetry
     - uses: actions/setup-python@v5

src/wristpy/core/models.py

@@ -118,6 +118,7 @@ class WatchData(BaseModel):
     temperature: Optional[Measurement] = None
     idle_sleep_mode_flag: Optional[bool] = None
     dynamic_range: Optional[tuple[float, float]] = None
+    time_zone: Optional[str] = None
 
     @field_validator("acceleration")
     def validate_acceleration(cls, v: Measurement) -> Measurement:

src/wristpy/core/orchestrator.py

@@ -419,6 +419,7 @@ def _run_file(
         "activity_metric": activity_metric,
         "nonwear_algorithm": list(nonwear_algorithm),
         "input_file": str(input),
+        "time_zone": watch_data.time_zone,
     }
 
     results = writers.OrchestratorResults(

src/wristpy/io/readers/readers.py

@@ -23,8 +23,13 @@ def read_watch_data(file_name: Union[pathlib.Path, str]) -> models.WatchData:
     Returns:
         WatchData class
 
-    Raises: IOError if the file extension is not supported or doesn't exist.
+    Raises:
+        ValueError if the file extension is not supported.
+        IOError if the file cannot be read using actfast.
     """
+    file_type = pathlib.Path(file_name).suffix
+    if file_type not in (".gt3x", ".bin"):
+        raise ValueError(f"File type {file_type} is not supported.")
     try:
         data = actfast.read(file_name)
     except Exception as e:
@@ -39,12 +44,14 @@ def read_watch_data(file_name: Union[pathlib.Path, str]) -> models.WatchData:
                 measurements=sensor_values, time=time
             )
 
-    file_type = pathlib.Path(file_name).suffix
     idle_sleep_mode_flag = False
     if file_type == ".gt3x":
         idle_sleep_mode_flag = (
             data["metadata"]["device_feature_enabled"]["sleep_mode"].lower() == "true"
         )
+        time_zone = data["metadata"]["info"]["TimeZone"]
+    elif file_type == ".bin":
+        time_zone = data["metadata"]["Configuration Info"]["Time Zone"][4:]
 
     dynamic_range = _extract_dynamic_range(
         metadata=data["metadata"],
@@ -59,6 +66,7 @@ def read_watch_data(file_name: Union[pathlib.Path, str]) -> models.WatchData:
         temperature=measurements.get("temperature"),
         idle_sleep_mode_flag=idle_sleep_mode_flag,
         dynamic_range=dynamic_range,
+        time_zone=str(time_zone),
     )
 
 

tests/unit/test_readers.py

@@ -12,7 +12,7 @@
 
 def test_read_invalid_extenstion(sample_data_txt: pathlib.Path) -> None:
     """Test the read_watch_data function with an invalid file extension."""
-    with pytest.raises(IOError):
+    with pytest.raises(ValueError, match="File type .txt is not supported."):
         readers.read_watch_data(sample_data_txt)
 
 
@@ -42,7 +42,7 @@ def test_geneactiv_bin_loader(sample_data_bin: pathlib.Path) -> None:
 
 def test_nonexistent_file() -> None:
     """Test the correct error is raised for nonexistent file."""
-    with pytest.raises(IOError):
+    with pytest.raises(IOError, match="Error reading file:"):
         readers.read_watch_data("nonexistent_file.gt3x")
 
 
@@ -74,3 +74,23 @@ def test_extract_dynamic_range_gt3x(sample_data_gt3x: pathlib.Path) -> None:
     assert (
         result == expected_dynamic_range
     ), f"Expected dynamic range of: {expected_dynamic_range}, result was: {result}"
+
+
+def test_timezone_extraction_gt3x(sample_data_gt3x: pathlib.Path) -> None:
+    """Test extracting timezone metadata from .gt3x files."""
+    expected_timezone = "-05:00:00"
+    watch_data = readers.read_watch_data(sample_data_gt3x)
+
+    assert (
+        watch_data.time_zone == expected_timezone
+    ), f"Expected timezone of: {expected_timezone}, result was: {watch_data.time_zone}"
+
+
+def test_timezone_extraction_bin(sample_data_bin: pathlib.Path) -> None:
+    """Test extracting timezone metadata from .bin files."""
+    expected_timezone = "-05:00"
+    watch_data = readers.read_watch_data(sample_data_bin)
+
+    assert (
+        watch_data.time_zone == expected_timezone
+    ), f"Expected timezone of: {expected_timezone}, result was: {watch_data.time_zone}"