spectre-core 0.0.1__py3-none-any.whl

spectre_core/spectrograms/transform.py

@@ -0,0 +1,267 @@
+# SPDX-FileCopyrightText: © 2024 Jimmy Fitzpatrick <jcfitzpatrick12@gmail.com>
+# This file is part of SPECTRE
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+import numpy as np
+from datetime import datetime, timedelta
+from typing import Optional
+
+from spectre_core.spectrograms.array_operations import find_closest_index
+from spectre_core.spectrograms.spectrogram import Spectrogram
+from spectre_core.cfg import DEFAULT_DATETIME_FORMAT
+
+
+def _average_array(array: np.ndarray, average_over: int, axis=0) -> np.ndarray:
+
+    # Check if average_over is an integer
+    if type(average_over) != int:
+        raise TypeError(f"average_over must be an integer. Got {type(average_over)}")
+
+    # Get the size of the specified axis which we will average over
+    axis_size = array.shape[axis]
+    # Check if average_over is within the valid range
+    if not 1 <= average_over <= axis_size:
+        raise ValueError(f"average_over must be between 1 and the length of the axis ({axis_size})")
+    
+    max_axis_index = len(np.shape(array)) - 1
+    if axis > max_axis_index: # zero indexing on specifying axis, so minus one
+        raise ValueError(f"Requested axis is out of range of array dimensions. Axis: {axis}, max axis index: {max_axis_index}")
+
+    # find the number of elements in the requested axis
+    num_elements = array.shape[axis]
+
+    # find the number of "full blocks" to average over
+    num_full_blocks = num_elements // average_over
+    # if num_elements is not exactly divisible by average_over, we will have some elements left over
+    # these remaining elements will be padded with nans to become another full block
+    remainder = num_elements % average_over
+    
+    # if there exists a remainder, pad the last block
+    if remainder != 0:
+        # initialise an array to hold the padding shape
+        padding_shape = [(0, 0)] * array.ndim
+        # pad after the last column in the requested axis
+        padding_shape[axis] = (0, average_over - remainder)
+        # pad with nan values (so to not contribute towards the mean computation)
+        array = np.pad(array, padding_shape, mode='constant', constant_values=np.nan)
+    
+    # initalise a list to hold the new shape
+    new_shape = list(array.shape)
+    # update the shape on the requested access (to the number of blocks we will average over)
+    new_shape[axis] = num_full_blocks + (1 if remainder else 0)
+    # insert a new dimension, with the size of each block
+    new_shape.insert(axis + 1, average_over)
+    # and reshape the array to sort the array into the relevant blocks.
+    reshaped_array = array.reshape(new_shape)
+    # average over the newly created axis, essentially averaging over the blocks.
+    averaged_array = np.nanmean(reshaped_array, axis=axis + 1)
+    # return the averaged array
+    return averaged_array
+
+
+def frequency_chop(input_spectrogram: Spectrogram, 
+                   start_frequency: float | int, 
+                   end_frequency: float | int) -> Optional[Spectrogram]:
+    
+    is_entirely_below_frequency_range = (start_frequency < input_spectrogram.frequencies[0] and end_frequency < input_spectrogram.frequencies[0])
+    is_entirely_above_frequency_range = (start_frequency > input_spectrogram.frequencies[-1] and end_frequency > input_spectrogram.frequencies[-1])
+    # if the requested frequency range is out of bounds for the spectrogram return None
+    if is_entirely_below_frequency_range or is_entirely_above_frequency_range:
+        return None
+    
+    #find the index of the nearest matching frequency bins in the spectrogram
+    start_index = find_closest_index(start_frequency, input_spectrogram.frequencies)
+    end_index = find_closest_index(end_frequency, input_spectrogram.frequencies)
+    
+    # enforce distinct start and end indices
+    if start_index == end_index:
+        raise ValueError(f"Start and end indices are equal! Got start_index: {start_index} and end_index: {end_index}")  
+    
+    # if start index is more than end index, swap the ordering so to enforce start_index <= end_index
+    if start_index > end_index:
+        start_index, end_index = end_index, start_index
+    
+    # chop the spectrogram accordingly
+    transformed_dynamic_spectra = input_spectrogram.dynamic_spectra[start_index:end_index+1, :]
+    transformed_frequencies = input_spectrogram.frequencies[start_index:end_index+1]
+    
+    # return the spectrogram instance
+    return Spectrogram(transformed_dynamic_spectra,
+                       input_spectrogram.times,
+                       transformed_frequencies,
+                       input_spectrogram.tag,
+                       chunk_start_time = input_spectrogram.chunk_start_time,
+                       microsecond_correction = input_spectrogram.microsecond_correction,
+                       spectrum_type = input_spectrogram.spectrum_type)
+
+
+def time_chop(input_spectrogram: Spectrogram, 
+              start_time: str, 
+              end_time: str, 
+              time_format: str = DEFAULT_DATETIME_FORMAT) -> Optional[Spectrogram]:
+    
+    # parse the strings as datetimes
+    start_datetime = datetime.strptime(start_time, time_format)
+    end_datetime = datetime.strptime(end_time, time_format)
+
+    # if the requested time range is out of bounds for the spectrogram return None
+    is_entirely_below_time_range = (start_datetime < input_spectrogram.datetimes[0] and end_datetime < input_spectrogram.datetimes[0])
+    is_entirely_above_time_range = (start_datetime > input_spectrogram.datetimes[-1] and end_datetime > input_spectrogram.datetimes[-1])
+    if is_entirely_below_time_range or is_entirely_above_time_range:
+        return None
+    
+    start_index = find_closest_index(start_datetime, input_spectrogram.datetimes)
+    end_index = find_closest_index(end_datetime, input_spectrogram.datetimes)
+    
+    if start_index == end_index:
+        raise ValueError(f"Start and end indices are equal! Got start_index: {start_index} and end_index: {end_index}")
+    
+    if start_index > end_index:
+        start_index, end_index = end_index, start_index
+
+    # chop the spectrogram 
+    transformed_dynamic_spectra = input_spectrogram.dynamic_spectra[:, start_index:end_index+1]
+
+    # chop the times array
+    transformed_times = input_spectrogram.times[start_index:end_index+1]
+    #translate the chopped times array to start at zero
+    transformed_times -= transformed_times[0]
+
+    # compute the new start datetime following the time chop
+    transformed_start_datetime = input_spectrogram.datetimes[start_index]
+    # parse the chunk start time (as string)
+    transformed_chunk_start_time = datetime.strftime(transformed_start_datetime, DEFAULT_DATETIME_FORMAT)
+    # and compute the microsecond correction
+    transformed_microsecond_correction = transformed_start_datetime.microsecond
+
+    return Spectrogram(transformed_dynamic_spectra, 
+                       transformed_times, 
+                       input_spectrogram.frequencies, 
+                       input_spectrogram.tag, 
+                       chunk_start_time = transformed_chunk_start_time,
+                       microsecond_correction = transformed_microsecond_correction,
+                       spectrum_type = input_spectrogram.spectrum_type)
+
+
+def time_average(input_spectrogram: Spectrogram, 
+                 average_over: int) -> Spectrogram:
+    
+    # spectre does not currently support averaging of non-datetime assigned spectrograms
+    if input_spectrogram.chunk_start_time is None:
+        raise ValueError(f"Input spectrogram is missing chunk start time. Averaging is not yet supported for non-datetime assigned spectrograms")
+    
+    # if the user has requested no averaging, just return the same instance unchanged
+    if average_over == 1:
+        return input_spectrogram
+
+    # average the dynamic spectra array
+    transformed_dynamic_spectra = _average_array(input_spectrogram.dynamic_spectra, average_over, axis=1)
+    # average the times array s.t. the ith averaged spectrum is assigned the 
+    transformed_times = _average_array(input_spectrogram.times, average_over)
+
+    # We need to assign timestamps to the averaged spectrums in the spectrograms. The natural way to do this
+    # is to assign the i'th averaged spectrogram to the i'th averaged time stamp. From this,
+    # we then need to compute the chunk start time to assig to the first averaged spectrum,
+    # and update the microsecond correction.
+    
+    # define the initial spectrum as the spectrum at time index 0 in the spectrogram
+    # then, averaged_t0 is the seconds elapsed between the input intial spectrum and the averaged intial spectrum
+    averaged_t0 = float(transformed_times[0])
+    # compute the updated chunk start time and the updated microsecond correction based on averaged_t0
+    corrected_start_datetime = input_spectrogram.datetimes[0] + timedelta(seconds = averaged_t0)
+    # then, compute the transformed chunk start time and microsecond correction
+    transformed_chunk_start_time = corrected_start_datetime.strftime(DEFAULT_DATETIME_FORMAT)
+    transformed_microsecond_correction = corrected_start_datetime.microsecond
+
+    # finally, translate the averaged time seconds to begin at t=0 [s]
+    transformed_times -= transformed_times[0]
+    return Spectrogram(transformed_dynamic_spectra, 
+                       transformed_times, 
+                       input_spectrogram.frequencies, 
+                       input_spectrogram.tag,
+                       chunk_start_time = transformed_chunk_start_time,
+                       microsecond_correction = transformed_microsecond_correction,
+                       spectrum_type = input_spectrogram.spectrum_type)
+
+def frequency_average(input_spectrogram: Spectrogram, 
+                      average_over: int) -> Spectrogram:
+    
+    # if the user has requested no averaging, just return the same instance unchanged
+    if average_over == 1:
+        return input_spectrogram
+
+    # We need to assign physical frequencies to the averaged spectrums in the spectrograms.
+    # is to assign the i'th averaged spectral component to the i'th averaged frequency.
+    # average the dynamic spectra array
+    transformed_dynamic_spectra = _average_array(input_spectrogram.dynamic_spectra, average_over, axis=0)
+    transformed_frequencies = _average_array(input_spectrogram.frequencies, average_over)
+
+    return Spectrogram(transformed_dynamic_spectra, 
+                       input_spectrogram.times, 
+                       transformed_frequencies, 
+                       input_spectrogram.tag,
+                       chunk_start_time = input_spectrogram.chunk_start_time, 
+                       microsecond_correction = input_spectrogram.microsecond_correction,
+                       spectrum_type = input_spectrogram.spectrum_type)
+
+
+def _time_elapsed(datetimes: np.ndarray) -> np.ndarray:
+    # Extract the first datetime to use as the reference point
+    base_time = datetimes[0]
+    # Calculate elapsed time in seconds for each datetime in the list
+    elapsed_time = [(dt - base_time).total_seconds() for dt in datetimes]
+    # Convert the list of seconds to a NumPy array of type float32
+    return np.array(elapsed_time, dtype=np.float32)
+
+# we assume that the spectrogram list is ORDERED chronologically
+# we assume there is no time overlap in any of the spectrograms in the list
+def join_spectrograms(spectrograms: list[Spectrogram]) -> Spectrogram:
+
+    # check that the length of the list is non-zero
+    num_spectrograms = len(spectrograms)
+    if num_spectrograms == 0:
+        raise ValueError(f"Input list of spectrograms is empty!")
+    
+    # extract the first element of the list, and use this as a reference for comparison
+    # input validations.
+    reference_spectrogram = spectrograms[0] 
+
+    # perform checks on each spectrogram in teh list
+    for spectrogram in spectrograms:
+        if not np.all(np.equal(spectrogram.frequencies, reference_spectrogram.frequencies)):
+            raise ValueError(f"All spectrograms must have identical frequency ranges")
+        if spectrogram.tag != reference_spectrogram.tag:
+            raise ValueError(f"All tags must be equal for each spectrogram in the input list!")
+        if spectrogram.spectrum_type != reference_spectrogram.spectrum_type:
+            raise ValueError(f"All units must be equal for each spectrogram in the input list!")
+        if spectrogram.chunk_start_time is None:
+            raise ValueError(f"All spectrograms must have chunk_start_time set. Received {spectrogram.chunk_start_time}")
+
+
+    # build a list of the time array of each spectrogram in the list
+    conc_datetimes = np.concatenate([s.datetimes for s in spectrograms])
+    # find the total number of time stamps
+    num_total_time_bins = len(conc_datetimes)
+    # find the total number of frequency bins (we can safely now use the first)
+    num_total_freq_bins = len(reference_spectrogram.frequencies)
+    # create an empty numpy array to hold the joined spectrograms
+    transformed_dynamic_spectra = np.empty((num_total_freq_bins, num_total_time_bins))
+
+    start_index = 0
+    for spectrogram in spectrograms:
+        end_index = start_index + len(spectrogram.times)
+        transformed_dynamic_spectra[:, start_index:end_index] = spectrogram.dynamic_spectra
+        start_index = end_index
+
+    transformed_times = _time_elapsed(conc_datetimes)
+    
+    transformed_microsecond_correction = conc_datetimes[0].microsecond
+
+    return Spectrogram(transformed_dynamic_spectra, 
+                       transformed_times, 
+                       reference_spectrogram.frequencies, 
+                       reference_spectrogram.tag, 
+                       chunk_start_time = reference_spectrogram.chunk_start_time,
+                       microsecond_correction = transformed_microsecond_correction,
+                       spectrum_type = reference_spectrogram.spectrum_type) 
+

spectre_core/watchdog/__init__.py

@@ -0,0 +1,6 @@
+# SPDX-FileCopyrightText: © 2024 Jimmy Fitzpatrick <jcfitzpatrick12@gmail.com>
+# This file is part of SPECTRE
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+# dynamically import all event handlers
+import spectre_core.watchdog.library

spectre_core/watchdog/base.py

@@ -0,0 +1,105 @@
+# SPDX-FileCopyrightText: © 2024 Jimmy Fitzpatrick <jcfitzpatrick12@gmail.com>
+# This file is part of SPECTRE
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+from logging import getLogger
+_LOGGER = getLogger(__name__)
+
+import os
+import time
+from queue import Queue
+from typing import Any
+from abc import ABC, abstractmethod
+from math import floor
+
+from watchdog.events import FileSystemEventHandler
+
+from spectre_core.chunks.factory import get_chunk_from_tag
+from spectre_core.file_handlers.configs import CaptureConfig
+from spectre_core.spectrograms.spectrogram import Spectrogram
+from spectre_core.spectrograms.transform import join_spectrograms
+from spectre_core.spectrograms.transform import (
+    time_average, 
+    frequency_average
+)
+
+
+class BaseEventHandler(ABC, FileSystemEventHandler):
+    def __init__(self, 
+                 tag: str, 
+                 exception_queue: Queue, 
+                 extension: str):
+        self._tag = tag
+        self._Chunk = get_chunk_from_tag(tag)
+
+        self._capture_config = CaptureConfig(tag)
+
+        self._extension = extension
+        self._exception_queue = exception_queue  # Queue to propagate exceptions
+
+        self._spectrogram: Spectrogram = None # spectrogram cache
+
+
+    @abstractmethod
+    def process(self, file_path: str) -> None:
+        pass
+
+
+    def on_created(self, event):
+        if not event.is_directory and event.src_path.endswith(self._extension):
+            _LOGGER.info(f"Noticed: {event.src_path}")
+            try:
+                self._wait_until_stable(event.src_path)
+                self.process(event.src_path)
+            except Exception as e:
+                _LOGGER.error(f"An error has occured while processing {event.src_path}",
+                              exc_info=True)
+                self._flush_spectrogram() # flush the internally stored spectrogram
+                # Capture the exception and propagate it through the queue
+                self._exception_queue.put(e)
+
+
+    def _wait_until_stable(self, file_path: str):
+        _LOGGER.info(f"Waiting for file stability: {file_path}")
+        size = -1
+        while True:
+            current_size = os.path.getsize(file_path)
+            if current_size == size:
+                _LOGGER.info(f"File is now stable: {file_path}")
+                break  # File is stable when the size hasn't changed
+            size = current_size
+            time.sleep(0.25)
+
+
+    def _average_in_time(self, spectrogram: Spectrogram) -> Spectrogram:
+        requested_time_resolution = self._capture_config.get('time_resolution') # [s]
+        if requested_time_resolution is None:
+            raise KeyError(f"Time resolution has not been specified in the capture config!")
+        average_over = floor(requested_time_resolution/spectrogram.time_resolution) if requested_time_resolution > spectrogram.time_resolution else 1
+        return time_average(spectrogram, average_over)
+    
+    
+    def _average_in_frequency(self, spectrogram: Spectrogram) -> Spectrogram:
+        frequency_resolution = self._capture_config.get('frequency_resolution') # [Hz]
+        if frequency_resolution is None:
+            raise KeyError(f"Frequency resolution has not been specified in the capture config!")
+        average_over = floor(frequency_resolution/spectrogram.frequency_resolution) if frequency_resolution > spectrogram.frequency_resolution else 1
+        return frequency_average(spectrogram, average_over)
+    
+
+    def _join_spectrogram(self, spectrogram: Spectrogram) -> None:
+        if self._spectrogram is None:
+            self._spectrogram = spectrogram
+        else:
+            self._spectrogram = join_spectrograms([self._spectrogram, spectrogram])
+
+        if self._spectrogram.time_range >= self._capture_config.get("joining_time"):
+            self._flush_spectrogram()
+    
+
+    def _flush_spectrogram(self) -> None:
+        if self._spectrogram:
+            _LOGGER.info(f"Flushing spectrogram to file with chunk start time {self._spectrogram.chunk_start_time}")
+            self._spectrogram.save()
+            _LOGGER.info("Flush successful, resetting spectrogram cache")
+            self._spectrogram = None # reset the cache

spectre_core/watchdog/event_handler_register.py

@@ -0,0 +1,15 @@
+# SPDX-FileCopyrightText: © 2024 Jimmy Fitzpatrick <jcfitzpatrick12@gmail.com>
+# This file is part of SPECTRE
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+# Global dictionaries to hold the mappings
+event_handler_map = {}
+
+# classes decorated with @register_event_handler([EVENT_HANDLER_KEY])
+# will be added to event_handler_map
+def register_event_handler(event_handler_key: str):
+    def decorator(cls):
+        event_handler_map[event_handler_key] = cls
+        return cls
+    return decorator
+

spectre_core/watchdog/factory.py

@@ -0,0 +1,22 @@
+# SPDX-FileCopyrightText: © 2024 Jimmy Fitzpatrick <jcfitzpatrick12@gmail.com>
+# This file is part of SPECTRE
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+from spectre_core.watchdog.event_handler_register import event_handler_map
+from spectre_core.watchdog.base import BaseEventHandler
+from spectre_core.file_handlers.configs import CaptureConfig
+from spectre_core.exceptions import EventHandlerNotFoundError
+
+def get_event_handler(event_handler_key: str) -> BaseEventHandler:
+    # try and fetch the capture config mount
+    EventHandler = event_handler_map.get(event_handler_key)
+    if EventHandler is None:
+        valid_event_handler_keys = list(event_handler_map.keys())
+        raise EventHandlerNotFoundError(f"No event handler found for the event handler key: {event_handler_key}. Please specify one of the following event handler keys {valid_event_handler_keys}")
+    return EventHandler
+
+
+def get_event_handler_from_tag(tag: str) -> BaseEventHandler:
+    capture_config = CaptureConfig(tag)
+    event_handler_key = capture_config.get('event_handler_key')
+    return get_event_handler(event_handler_key)

spectre_core/watchdog/library/__init__.py

@@ -0,0 +1,10 @@
+# SPDX-FileCopyrightText: © 2024 Jimmy Fitzpatrick <jcfitzpatrick12@gmail.com>
+# This file is part of SPECTRE
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+from spectre_core.dynamic_imports import import_target_modules
+
+import_target_modules(__file__, __name__, "event_handler")
+
+
+

spectre_core/watchdog/library/fixed/event_handler.py

@@ -0,0 +1,41 @@
+# SPDX-FileCopyrightText: © 2024 Jimmy Fitzpatrick <jcfitzpatrick12@gmail.com>
+# This file is part of SPECTRE
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+from logging import getLogger
+_LOGGER = getLogger(__name__)
+
+import os
+
+from spectre_core.watchdog.base import BaseEventHandler
+from spectre_core.watchdog.event_handler_register import register_event_handler
+
+@register_event_handler("fixed")
+class EventHandler(BaseEventHandler):
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+
+
+    def process(self, file_path: str):
+        _LOGGER.info(f"Processing: {file_path}")
+        file_name = os.path.basename(file_path)
+        chunk_start_time, _ = os.path.splitext(file_name)[0].split('_')
+        chunk = self._Chunk(chunk_start_time, self._tag)
+
+        _LOGGER.info("Creating spectrogram")
+        spectrogram = chunk.build_spectrogram()
+
+        _LOGGER.info("Averaging spectrogram")
+        spectrogram = self._average_in_time(spectrogram)
+        spectrogram = self._average_in_frequency(spectrogram)
+
+        _LOGGER.info("Joining spectrogram")
+        self._join_spectrogram(spectrogram)
+
+        bin_chunk = chunk.get_file('bin')
+        _LOGGER.info(f"Deleting {bin_chunk.file_path}")
+        bin_chunk.delete(doublecheck_delete = False)
+
+        hdr_chunk = chunk.get_file('hdr')
+        _LOGGER.info(f"Deleting {hdr_chunk.file_path}")
+        hdr_chunk.delete(doublecheck_delete = False)

spectre_core/watchdog/library/sweep/event_handler.py

@@ -0,0 +1,55 @@
+# SPDX-FileCopyrightText: © 2024 Jimmy Fitzpatrick <jcfitzpatrick12@gmail.com>
+# This file is part of SPECTRE
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+from logging import getLogger
+_LOGGER = getLogger(__name__)
+
+import os
+
+from spectre_core.chunks.base import BaseChunk
+from spectre_core.watchdog.base import BaseEventHandler
+from spectre_core.watchdog.event_handler_register import register_event_handler
+
+@register_event_handler("sweep")
+class EventHandler(BaseEventHandler):
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+
+        self.previous_chunk: BaseChunk = None # cache for previous chunk
+        
+
+    def process(self, file_path: str):
+        _LOGGER.info(f"Processing: {file_path}")
+        file_name = os.path.basename(file_path)
+        chunk_start_time, _ = os.path.splitext(file_name)[0].split('_')
+        chunk = self._Chunk(chunk_start_time, self._tag)
+
+        _LOGGER.info("Creating spectrogram")
+        spectrogram = chunk.build_spectrogram(previous_chunk = self.previous_chunk)
+
+        _LOGGER.info("Averaging spectrogram")
+        spectrogram = self._average_in_time(spectrogram)
+        spectrogram = self._average_in_frequency(spectrogram)
+
+        _LOGGER.info("Joining spectrogram")
+        self._join_spectrogram(spectrogram)
+
+        # if the previous chunk has not yet been set, it means we were processing the first chunk
+        # so we don't need to handle the previous chunk
+        if self.previous_chunk is None:
+            # instead, only set it for the next time this method is called
+            self.previous_chunk = chunk
+            
+        # otherwise the previous chunk is defined (and by this point has already been processed)
+        else:
+            bin_chunk = self.previous_chunk.get_file('bin')
+            _LOGGER.info(f"Deleting {bin_chunk.file_path}")
+            bin_chunk.delete(doublecheck_delete = False)
+
+            hdr_chunk = self.previous_chunk.get_file('hdr')
+            _LOGGER.info(f"Deleting {hdr_chunk.file_path}")
+            hdr_chunk.delete(doublecheck_delete = False)
+
+            # and reassign the current chunk to be used as the previous chunk at the next call of this method
+            self.previous_chunk = chunk

spectre_core/watchdog/watcher.py

@@ -0,0 +1,50 @@
+# SPDX-FileCopyrightText: © 2024 Jimmy Fitzpatrick <jcfitzpatrick12@gmail.com>
+# This file is part of SPECTRE
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+from logging import getLogger
+_LOGGER = getLogger(__name__)
+
+from queue import Queue, Empty
+
+from watchdog.observers import Observer
+
+from spectre_core.watchdog.factory import get_event_handler_from_tag
+from spectre_core.cfg import CHUNKS_DIR_PATH
+
+class Watcher:
+    def __init__(self, 
+                 tag: str):
+        self._observer: Observer = Observer()
+        self._exception_queue: Queue = Queue()  # A thread-safe queue for exceptions
+
+        EventHandler = get_event_handler_from_tag(tag)
+        self._event_handler = EventHandler(tag, 
+                                           self._exception_queue,
+                                           "bin")
+
+
+    def start(self):
+        _LOGGER.info("Starting watcher...")
+
+        # Schedule and start the observer
+        self._observer.schedule(self._event_handler, 
+                               CHUNKS_DIR_PATH, 
+                               recursive=True)
+        self._observer.start()
+
+        try:
+            # Monitor the observer and handle exceptions
+            while self._observer.is_alive():
+                try:
+                    exc = self._exception_queue.get(block=True, timeout=0.25)
+                    if exc:
+                        raise exc  # Propagate the exception
+                except Empty:
+                    pass  # Continue looping if no exception in queue
+        finally:
+            # Ensure the observer is properly stopped
+            self._observer.stop()
+            self._observer.join()
+
+