Refactor Biosignal (1)

docs/changelog/pythonversions/index.md

@@ -79,11 +79,10 @@ _Released: 31-05-2022 | Created: 01-02-2022 | **Not Public**_
 
 ### Added
 
-* Abstract classes `Biosignal` and `BiosignalSource`, and some concrete implementations in the sub-packages
+* Abstract classes `Biosignal` and `__BiosignalSource`, and some concrete implementations in the sub-packages
 `modalities` and `sources`, respectively.
 * Classes `Timeseries`, `Segment`, `Unit`, `Event`.
 * Packages `clinical`: classes `Patient`, `BodyLocation`, `MedicalCondition`, `Medication`, and `SurgicalProcedure`.
 * Package `processing`: classes `Segmenter` and `Filter`.
 * Package `features`: classes `FeatureExtractor` and `FeatureSelector`.
 * Package `ml`: classes `SupervisedModel`, `SupervisedTrainConditions`, `SurpervisingTrainer`, `SupervisedTrainResults`.
-

docs/changelog/serialversions/Biosignal.md

@@ -1,18 +0,0 @@
-# Biosignal
-
-## Serial Version 1
-
-_Date Created: 01-06-2022_
-
-```
-(SERIALVERSION, name, source, patient, acquisition_location, associated_events, timeseries)
-```
-
-* `SERIALVERSION` equals 1.
-* `name` is a `str` with the value of the biosignal's `__name` attribute.
-* `source` is a `BiosignalSource` class, or the state of a `BiosignalSource` object, based on the value of the biosignal's `__source` attribute.
-* `patient` is the state of the `Patient` referenced in the biosignal's `__patient` attribute.
-* `acquisition_location` is a `BodyLocation` with the value of the biosignal's `__acquisition_location` attribute.
-* `associated_events` is a tuple of the states of all `Event`s' referenced in the biosignal's `__associated_events` attribute.
-* `timeseries` is a dictionary of the states of all `Timeseries`s' referenced in the biosignal's `__timeseries` attribute.
-

docs/changelog/serialversions/BiosignalSource.md

@@ -1,16 +0,0 @@
-# BiosignalSource
-
-`BiosignalSource` is usually not instantiated as an object, so there are no states to serialize.
-However, there are some sources that are instantiated, e.g., `Sense`, `Bitalino`. In these cases, the following serial versions apply.
-
-## Serial Version 1
-
-_Date Created: 01-06-2022_
-
-```
-(SERIALVERSION, others)
-```
-
-* `SERIALVERSION` equals 1.
-* `others` is a dictionary of properties an instantiated `BiosignalSource` object may have. 
-

docs/changelog/serialversions/index.rst

@@ -8,7 +8,7 @@ Below you can check the current and past versions of the .biosignal files (first
 +------------------------------+------------+------------+------------+---------------------+
 | :code:`Biosignal`            | 1          | 1          | 1          | **2**               |
 +------------------------------+------------+------------+------------+---------------------+
-| :code:`BiosignalSource`      | 1          | 1          | 1          | 1                   |
+| :code:`__BiosignalSource`      | 1          | 1          | 1          | 1                   |
 +------------------------------+------------+------------+------------+---------------------+
 | :code:`Timeseries`           | 1          | **2**      | 2          | 2                   |
 +------------------------------+------------+------------+------------+---------------------+
@@ -37,7 +37,7 @@ Any Biosignal and associated objects are stateful, so that they can be serialize
    :maxdepth: 1
 
    Biosignal
-   BiosignalSource
+   __BiosignalSource
 
 .. tip::
    How this structure is created can be inspected in more detail in the methods :code:`__getstate__` and :code:`__setstate__` of each of these class.

docs/learn/basic/ltbio101.md

@@ -35,16 +35,16 @@ For example, to instantiate an `ECG` from a file, one could use the following in
 ecg = ECG('pathToFile', HSM, name='My First Biosignal')
 ```
 
-In the above example, `HSM` is the `BiosignalSource` representing "Hospital de Santa Maria" 🏥, a hospital in Lisbon, Portugal.
+In the above example, `HSM` is the `__BiosignalSource` representing "Hospital de Santa Maria" 🏥, a hospital in Lisbon, Portugal.
 This class _knows_ how to read biosignals from EDF files collected at HSM. 
-As depicted in the above Figure, there can be as many `BiosignalSource` subclasses as the user needs. The ones you see are just examples, 
+As depicted in the above Figure, there can be as many `__BiosignalSource` subclasses as the user needs. The ones you see are just examples, 
 like [ScientISST](scientisst.com/sense) and [BITalino](https://www.pluxbiosignals.com/collections/bitalino) devices, public databases like 
-MITDB and Seer, and many others. A `BiosignalSource` is an entity with knowledge about where (devices, hospitals, databases, etc.) and how 
+MITDB and Seer, and many others. A `__BiosignalSource` is an entity with knowledge about where (devices, hospitals, databases, etc.) and how 
 biosignals are acquired. It has static procedures to ease the reading of biosignals from files of that source, and the respective patient 
 metadata, clinical records, and event annotations. These have their own classes as well, as shall be described ahead.
-Other sources can be easily implemented by deriving `BiosignalSource`. This scalable property is of vital importance, since biosignal
+Other sources can be easily implemented by deriving `__BiosignalSource`. This scalable property is of vital importance, since biosignal
 researchers get data from a large variety of sources that increases by the day. Hence, you have the possibility of working with data from 
-new sources only by creating your own `BiosignalSource`, therefore personalising the framework to your research needs.
+new sources only by creating your own `__BiosignalSource`, therefore personalising the framework to your research needs.
 
 ------------
 
@@ -58,7 +58,7 @@ _Biosignals_ to modify themselves, without you having to remember their metadata
 
 **The Concept as a Class:** A `Biosignal` object is a non-empty set of channels measuring one biological or physiological variable. Each 
 channel is represented by a `Timeseries` object (see UML above). Optionally, it may also have an associated `Patient`, an associated 
-`BodyLocation`, one ore more associated `Event`s, an associated `BiosignalSource`, and a name. All this metadata is introduced later; for now it's crucial you understand how
+`BodyLocation`, one ore more associated `Event`s, an associated `__BiosignalSource`, and a name. All this metadata is introduced later; for now it's crucial you understand how
 channels and samples are organised.
 
 ------------
@@ -96,7 +96,7 @@ endevours. If you want to have it all in one place regarding one biosignal (and
 with more properties:
 
 * 🤕 **Patient**: An object `Patient` where you can drop any information regarding the 
-patient that can be useful to process the biosignal. If reading from a file or fetching a database, `BiosignalSource` might fill this property
+patient that can be useful to process the biosignal. If reading from a file or fetching a database, `__BiosignalSource` might fill this property
 automatically for you.
 
 * 🧍‍♀️ **Location**: An object `BodyLocation` to remember where the sensors were placed.
@@ -128,7 +128,7 @@ You have three ways 🤯 of instantiating a `Biosignal`.
 
 ### Way 1: Instantiate from files
 
-Give the path to the directory where the files are located and specify the source (`BiosignalSource`) from where the files come from:
+Give the path to the directory where the files are located and specify the source (`__BiosignalSource`) from where the files come from:
 ```
 biosignal = ECG("path_to_files", HSM)
 ```
@@ -139,7 +139,7 @@ you'll want to create your own source.
 
 ### Way 2: Instantiate from a Database [comming 🔜]
 
-Give the patient code, the source (`BiosignalSource`) corresponding to a database, and the interval of time (in tuple) you want to fetch from the database:
+Give the patient code, the source (`__BiosignalSource`) corresponding to a database, and the interval of time (in tuple) you want to fetch from the database:
 ```
 biosignal = ECG(patient_code=101, source=HSM, ('2022-01-01 16:00', '2022-01-01 17:30'))
 ```

docs/learn/basic/properties.md

@@ -1,7 +1,7 @@
 # Enrich your Biosignals
 
 You have noticed by now that ``Biosignal`` objects gather all information about a biosignal in an holistic way, and not just the data
-samples. But ``Biosignal`` objects will only hold the information you give or that their `BiosignalSource` deducted.
+samples. But ``Biosignal`` objects will only hold the information you give or that their `__BiosignalSource` deducted.
 
 ## Print to see me
 
@@ -145,7 +145,7 @@ You can **get** any of the following properties of a `Biosignal`:
 * `channel_names` returns a set with the channel labels (in `string` or `BodyLocation`).
 * `sampling_frequency` returns the the sampling frequency of every channel, if equal (in `float`).
 * `acquisition_location` returns the body location where the biosignal was acquired (in `BodyLocation`).
-* `source` returns the source where the Biosignal was acquired: hospital, device, etc. (in `BiosignalSource`).
+* `source` returns the source where the Biosignal was acquired: hospital, device, etc. (in `__BiosignalSource`).
 * `patient_code` returns the code of the patient whose the biosignal belongs (in `int` or `string`).
 * `type` returns the biosignal modality (in any `Biosignal` subclass).
 * `initial_datetime` returns the initial datetime of the channel that starts the earliest (in `datetime`).

resources/config.ini

@@ -1,2 +0,0 @@
-[DEFAULT]
-Sense = /Users/saraiva/Desktop/LongTermBiosignals/resources/Sense_CSV_tests/sense_defaults.json

src/ltbio/__init__.pyi

@@ -0,0 +1,2 @@
+
+__all__ = ["biosignals", "clinical"]

src/ltbio/_core/__init__.py

@@ -0,0 +1,12 @@
+# -- encoding: utf-8 --
+# ===================================
+# ScientISST LTBio | Long-Term Biosignals
+
+# Package: 
+# Module: 
+# Description:
+
+# Contributors: João Saraiva
+# Created: 
+# Last Updated: 
+# ===================================

src/ltbio/_core/exceptions.py

@@ -0,0 +1,145 @@
+# -- encoding: utf-8 --
+# ===================================
+# ScientISST LTBio | Long-Term Biosignals
+from datetime import datetime
+
+from datetimerange import DateTimeRange
+
+#from ltbio.biosignals._Timeline import Timeline
+#from ltbio.biosignals._Timeseries import Timeseries
+#from ltbio.biosignals.units import Unit, Frequency
+#from ltbio.clinical import BodyLocation
+
+
+# Package:
+# Module: 
+# Description:
+
+# Contributors: João Saraiva
+# Created: 
+# Last Updated: 
+# ===================================
+
+
+class TimeseriesError(Exception):
+    def __init__(self, why: str):
+        super().__init__(why)
+
+
+class EmptyTimeseriesError(TimeseriesError):
+    def __init__(self):
+        super().__init__(f"Trying to create a Timeseries with no samples.")
+
+
+
+
+class IncompatibleTimeseriesError(Exception):
+    def __init__(self, why: str):
+        super().__init__(f"These Timeseries are incompatible because {why}")
+
+
+class DifferentSamplingFrequenciesError(IncompatibleTimeseriesError):
+    def __init__(self, *frequencies):
+        super().__init__(f"these different sampling frequencies were found: {','.join(frequencies)}. "
+                         f"Try to resample first.")
+
+
+class DifferentUnitsError(IncompatibleTimeseriesError):
+    def __init__(self, *units):
+        super().__init__(f"these different units were found: {','.join(units)}. "
+                         f"Try to convert first.")
+
+
+class DifferentDomainsError(IncompatibleTimeseriesError):
+    def __init__(self, *timelines):
+        note = "they have different domains: "
+        note += '; '.join([f"({i+1}): {domain}" for i, domain in enumerate(timelines)])
+        super().__init__(note)
+
+
+class IncompatibleBiosignalsError(Exception):
+    def __init__(self, why: str):
+        super().__init__(f"These Biosignals are incompatible because {why}")
+
+
+class DifferentPatientsError(IncompatibleTimeseriesError):
+    def __init__(self, first, second):
+        super().__init__(f"at least two different patients were found: {first} and {second}. "
+                         f"Try to drop the patients first.")
+
+class SegmentError(Exception):
+    def __intit__(self, description: str):
+        super().__init__(description)
+
+class NotASegmentError(SegmentError):
+    def __init__(self, segment, intend_use=""):
+        super().__init__(f"{type(segment)} is not a segment. {intend_use}")
+
+class SamplesNotValidError(SegmentError):
+    def __init__(self, samples, why):
+        super().__init__(f"Samples are not valid, because {why}.")
+
+class EmptySegmentError(SegmentError):
+    def __init__(self):
+        super().__init__(f"Trying to create a Segment with no samples.")
+
+class IncompatibleSegmentsError(Exception):
+    def __init__(self, why: str):
+        super().__init__(f"These Segments are incompatible because {why}")
+
+class DifferentLengthsError(IncompatibleSegmentsError):
+    def __init__(self, first: int, second: int):
+        super().__init__(f"the first has length {first} and the second has length {second}.")
+
+
+class TimeError(Exception):
+    ...
+
+
+class ChannelsWithDifferentStartTimepointsError(TimeError):
+    def __init__(self, first_name, first_start, second_name, second_start, additional: str = ''):
+        super().__init__(f"{first_name} starts at {first_start} and {second_name} starts at {second_start}. " + additional)
+
+
+class OverlappingError(TimeError):
+    def __init__(self, what: str):
+        super().__init__(f"There is an overlap between {what}")
+
+
+class OverlappingSegmentsError(TimeseriesError, OverlappingError):
+    def __init__(self, first_start: datetime, first_end: datetime, second_start: datetime, second_end: datetime):
+        super().__init__(f"two segments to be added to the Timeseries. "
+                         f"First Segment starts at {first_start} and ends at {first_end}. "
+                         f"Second Segment starts at {second_start} and ends at {second_end}.")
+
+class TimeseriesOverlappingError(OverlappingError):
+    def __init__(self, first, second, *overlap: DateTimeRange):
+        super().__init__(f"Timeseries {first} and Timeseries {second}" + f" on {overlap}." if overlap else ".")
+
+
+class OperationError(Exception):
+    ...
+
+
+class UndoableOperationError(OperationError):
+    def __init__(self, operation, by_nature: bool):
+        note = f"Operation {operation} is undoable"
+        if by_nature:
+            note += " by nature, i.e. there is no mathematical way of reversing it or, at least, it's not implemented."
+        else:
+            note += ", most likely because this operation was what created this object."
+        super().__init__(note)
+
+
+class BiosignalError(Exception):
+    ...
+
+
+class ChannelNotFoundError(BiosignalError, IndexError, AttributeError):
+    def __init__(self, name):
+        super().__init__(f"There is no channel named '{name}'.")
+
+
+class EventNotFoundError(BiosignalError, IndexError, AttributeError):
+    def __init__(self, name: str):
+        super().__init__(f"There is no event named '{name}'.")