observation.py

# ===============================================================================
# Copyright 2025 ross
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
# ===============================================================================
from datetime import datetime
from typing import TYPE_CHECKING

from sqlalchemy import (
    ForeignKey,
    DateTime,
    Integer,
)
from sqlalchemy.orm import mapped_column, relationship, Mapped

from db.base import Base, AutoBaseMixin, ReleaseMixin, lexicon_term

if TYPE_CHECKING:
    from db.sample import Sample
    from db.sensor import Sensor
    from db.analysis_method import AnalysisMethod
    from db.parameter import Parameter


class Observation(Base, AutoBaseMixin, ReleaseMixin):
    __versioned__ = {}

    # NM_Aquifer fields for audits
    nma_pk_waterlevels: Mapped[str] = mapped_column(nullable=True)

    # --- Foreign Keys ---
    sample_id: Mapped[int] = mapped_column(
        ForeignKey("sample.id", ondelete="CASCADE"),
        nullable=False,
    )
    sensor_id: Mapped[int] = mapped_column(
        ForeignKey("sensor.id", ondelete="CASCADE"),
        nullable=True,
    )
    analysis_method_id: Mapped[int] = mapped_column(
        Integer, ForeignKey("analysis_method.id"), nullable=True
    )

    parameter_id: Mapped[int] = mapped_column(
        Integer, ForeignKey("parameter.id"), nullable=False
    )

    # --- Columns ---
    observation_datetime: Mapped[datetime] = mapped_column(
        DateTime(timezone=True), nullable=False, doc="Timestamp of the observation"
    )
    value: Mapped[float] = mapped_column(
        nullable=True,
    )
    unit: Mapped[str] = lexicon_term(nullable=False)
    notes: Mapped[str] = mapped_column(nullable=True)
    nma_data_quality: Mapped[str] = lexicon_term(
        nullable=True,
        comment="Legacy WaterLevels DataQuality mapped to lexicon term",
    )

    # groundwater
    measuring_point_height: Mapped[float] = mapped_column(
        nullable=True,
        doc="Height of the measuring point above the ground surface in ft",
        info={"unit": "ft"},
    )
    groundwater_level_reason: Mapped[str] = lexicon_term(
        nullable=True,
        comment="The reason describes everything that can effect the observation the moment a sample/observation is attempted (e.g. obstruction, dry well, equipment failure); a null value must have an associated reason in the same record. Factors preventing the obtainment of the observation from the beginning of the field event to attempted sampling/observation (e.g. flat tire, locked gate, destroyed well) are not recorded here but in the notes field of the FieldEvent table; in this situation no sample/observation should be recorded.",
    )

    # --- Relationships ---
    # Many-To-One: An Observation can be generated by one piece of Equipment.
    sensor: Mapped["Sensor"] = relationship(
        "Sensor", back_populates="observations", passive_deletes=True
    )

    # Many-To-One: An Observation is derived from one Sample.
    sample: Mapped["Sample"] = relationship(
        "Sample", back_populates="observations", passive_deletes=True
    )

    # Many-To-One: An Observation can be generated using one AnalysisMethod.
    analysis_method: Mapped["AnalysisMethod"] = relationship(
        "AnalysisMethod", back_populates="observations"
    )

    # Many-To-One: An Observation measures one Parameter.
    parameter: Mapped["Parameter"] = relationship(
        "Parameter", back_populates="observations", lazy="selectin"
    )


# ============= EOF =============================================