flood-adapt 0.3.0__py3-none-any.whl

flood_adapt/objects/events/event_set.py

@@ -0,0 +1,84 @@
+import os
+from pathlib import Path
+from typing import List, Optional
+
+import tomli
+from pydantic import BaseModel
+
+from flood_adapt.objects.events.events import Event, Mode
+from flood_adapt.objects.object_model import Object
+
+
+class SubEventModel(BaseModel):
+    """The accepted input for a sub event in FloodAdapt.
+
+    Attributes
+    ----------
+    name : str
+        The name of the sub event.
+    frequency : float
+        The frequency of the sub event.
+    """
+
+    name: str
+    frequency: float
+
+
+class EventSet(Object):
+    """BaseModel describing the expected variables and data types for parameters of EventSet.
+
+    An EventSet is a collection of events that can be used to create a scenario and perform a probabilistoc risk assessment.
+
+    Attributes
+    ----------
+    name : str
+        The name of the event.
+    description : str, default=""
+        The description of the event.
+    mode : Mode, default=Mode.risk
+        The mode of the event.
+    sub_events : List[SubEventModel]
+        The sub events of the event set.
+    """
+
+    _events: Optional[List[Event]] = None
+
+    mode: Mode = Mode.risk
+    sub_events: List[SubEventModel]
+
+    def load_sub_events(
+        self,
+        sub_events: Optional[List[Event]] = None,
+        file_path: Optional[Path] = None,
+    ) -> None:
+        """Load sub events from a list or from a file path."""
+        if sub_events is not None:
+            self._events = sub_events
+        elif file_path is not None:
+            from flood_adapt.objects.events.event_factory import EventFactory
+
+            sub_events = []
+            for sub_event in self.sub_events:
+                sub_toml = (
+                    Path(file_path).parent / sub_event.name / f"{sub_event.name}.toml"
+                )
+                sub_events.append(EventFactory.load_file(sub_toml))
+
+            self._events = sub_events
+        else:
+            raise ValueError("Either `sub_events` or `file_path` must be provided.")
+
+    @classmethod
+    def load_file(cls, file_path: Path | str | os.PathLike):
+        """Load object from file."""
+        with open(file_path, mode="rb") as fp:
+            event_set = tomli.load(fp)
+        event_set = EventSet(**event_set)
+        event_set.load_sub_events(file_path=file_path)
+        return event_set
+
+    def save_additional(self, output_dir: Path | str | os.PathLike) -> None:
+        for sub_event in self._events:
+            sub_dir = Path(output_dir) / sub_event.name
+            sub_dir.mkdir(parents=True, exist_ok=True)
+            sub_event.save(sub_dir / f"{sub_event.name}.toml")

flood_adapt/objects/events/events.py

@@ -0,0 +1,221 @@
+import os
+from enum import Enum
+from pathlib import Path
+from typing import Any, ClassVar, List, Optional, Protocol, runtime_checkable
+
+import tomli
+from pydantic import (
+    Field,
+    field_serializer,
+    field_validator,
+    model_validator,
+)
+
+from flood_adapt.config.config import Settings
+from flood_adapt.objects.forcing.forcing import (
+    ForcingSource,
+    ForcingType,
+    IForcing,
+)
+from flood_adapt.objects.forcing.forcing_factory import ForcingFactory
+from flood_adapt.objects.forcing.time_frame import TimeFrame
+from flood_adapt.objects.object_model import Object
+
+
+class Mode(str, Enum):
+    """Class describing the accepted input for the variable mode in Event."""
+
+    single_event = "single_event"
+    risk = "risk"
+
+
+class Template(str, Enum):
+    """Class describing the accepted input for the variable template in Event."""
+
+    Synthetic = "Synthetic"
+    Hurricane = "Hurricane"
+    Historical = "Historical"
+
+    @property
+    def description(self) -> str:
+        match self:
+            case Template.Historical:
+                return "Select a time period for a historic event. This method can use offshore wind and pressure fields for the selected time period to simulate nearshore water levels or download gauged waterlevels to perform a realistic simulation. These water levels are used together with rainfall and river discharge input to simulate flooding in the site area."
+            case Template.Hurricane:
+                return "Select a historical hurricane track from the hurricane database, and shift the track if desired."
+            case Template.Synthetic:
+                return "Customize a synthetic event by specifying the waterlevels, wind, rainfall and river discharges without being based on a historical event."
+            case _:
+                raise ValueError(f"Invalid event template: {self}")
+
+
+@runtime_checkable
+class PathBasedForcing(Protocol):
+    """Protocol for forcing classes that have a path attribute.
+
+    Performing an isinstance check on this class will return True if the class has a path attribute (even if it is None).
+    """
+
+    path: Path
+
+
+class Event(Object):
+    """The accepted input for an event in FloodAdapt.
+
+    Attributes
+    ----------
+    name : str
+        The name of the event.
+    description : str, default=""
+        The description of the event.
+    time : TimeFrame
+        The time frame of the event.
+    template : Template
+        The template of the event.
+    mode : Mode
+        The mode of the event.
+    rainfall_multiplier : float
+        The rainfall multiplier of the event.
+    forcings : dict[ForcingType, list[IForcing]]
+        The forcings of the event.
+    """
+
+    ALLOWED_FORCINGS: ClassVar[dict[ForcingType, List[ForcingSource]]]
+
+    time: TimeFrame
+    template: Template
+    mode: Mode = Mode.single_event
+
+    forcings: dict[ForcingType, list[IForcing]] = Field(default_factory=dict)
+    rainfall_multiplier: float = Field(default=1.0, ge=0)
+
+    @classmethod
+    def get_allowed_forcings(cls) -> dict[str, List[str]]:
+        return {k.value: [s.value for s in v] for k, v in cls.ALLOWED_FORCINGS.items()}
+
+    def get_forcings(self) -> list[IForcing]:
+        """Return a list of all forcings in the event."""
+        return [forcing for forcings in self.forcings.values() for forcing in forcings]
+
+    def save_additional(self, output_dir: Path | str | os.PathLike) -> None:
+        """Save any additional files associated with the event."""
+        for forcing in self.get_forcings():
+            forcing.save_additional(output_dir)
+
+    @classmethod
+    def load_file(cls, file_path: Path | str | os.PathLike) -> "Event":
+        """Load object from file.
+
+        Parameters
+        ----------
+        file_path : Path | str | os.PathLike
+            Path to the file to load.
+
+        """
+        with open(file_path, mode="rb") as fp:
+            toml = tomli.load(fp)
+
+        event = cls.model_validate(toml)
+
+        # Update all forcings with paths to absolute paths
+        for forcing in event.get_forcings():
+            if isinstance(forcing, PathBasedForcing):
+                if forcing.path.exists():
+                    continue
+                elif forcing.path == Path(forcing.path.name):
+                    # convert relative path to absolute path
+                    in_dir = Path(file_path).parent / forcing.path.name
+                    if not in_dir.exists():
+                        raise FileNotFoundError(
+                            f"Failed to load Event. File {forcing.path} does not exist in {in_dir.parent}."
+                        )
+                    forcing.path = in_dir
+                else:
+                    raise FileNotFoundError(
+                        f"Failed to load Event. File {forcing.path} does not exist."
+                    )
+
+        return event
+
+    @staticmethod
+    def _parse_forcing_from_dict(
+        forcing_attrs: dict[str, Any] | IForcing,
+        ftype: Optional[ForcingType] = None,
+        fsource: Optional[ForcingSource] = None,
+    ) -> IForcing:
+        if isinstance(forcing_attrs, IForcing):
+            # forcing_attrs is already a forcing object
+            return forcing_attrs
+        elif isinstance(forcing_attrs, dict):
+            # forcing_attrs is a dict with valid forcing attributes
+            if "type" not in forcing_attrs and ftype:
+                forcing_attrs["type"] = ftype
+            if "source" not in forcing_attrs and fsource:
+                forcing_attrs["source"] = fsource
+
+            return ForcingFactory.load_dict(forcing_attrs)
+        else:
+            raise ValueError(
+                f"Invalid forcing attributes: {forcing_attrs}. "
+                "Forcings must be one of:\n"
+                "1. Instance of IForcing\n"
+                "2. dict with the keys `type` (ForcingType), `source` (ForcingSource) specifying the class, and with valid forcing attributes for that class."
+            )
+
+    @field_validator("forcings", mode="before")
+    @classmethod
+    def create_forcings(
+        cls, value: dict[str, list[dict[str, Any]]]
+    ) -> dict[ForcingType, list[IForcing]]:
+        forcings = {}
+        for ftype, forcing_list in value.items():
+            ftype = ForcingType(ftype)
+            forcings[ftype] = [
+                cls._parse_forcing_from_dict(forcing, ftype) for forcing in forcing_list
+            ]
+        return forcings
+
+    @model_validator(mode="after")
+    def validate_forcings(self):
+        def validate_concrete_forcing(concrete_forcing):
+            type = concrete_forcing.type
+            source = concrete_forcing.source
+
+            # Check type
+            if type not in self.__class__.ALLOWED_FORCINGS:
+                allowed_types = ", ".join(
+                    t.value for t in self.__class__.ALLOWED_FORCINGS.keys()
+                )
+                raise ValueError(
+                    f"Forcing type {type.value} is not allowed. Allowed types are: {allowed_types}"
+                )
+
+            # Check source
+            if source not in self.__class__.ALLOWED_FORCINGS[type]:
+                allowed_sources = ", ".join(
+                    s.value for s in self.__class__.ALLOWED_FORCINGS[type]
+                )
+                raise ValueError(
+                    f"Forcing source {source.value} is not allowed for forcing type {type.value}. "
+                    f"Allowed sources are: {allowed_sources}"
+                )
+
+        if Settings().validate_allowed_forcings:
+            # Validate forcings
+            for _, concrete_forcings in self.forcings.items():
+                for concrete_forcing in concrete_forcings:
+                    validate_concrete_forcing(concrete_forcing)
+
+        return self
+
+    @field_serializer("forcings")
+    @classmethod
+    def serialize_forcings(
+        cls, value: dict[ForcingType, List[IForcing]]
+    ) -> dict[str, List[dict[str, Any]]]:
+        dct = {}
+        for ftype, forcing_list in value.items():
+            dct[ftype.value] = [
+                forcing.model_dump(exclude_none=True) for forcing in forcing_list
+            ]
+        return dct

flood_adapt/objects/events/historical.py

@@ -0,0 +1,55 @@
+from typing import ClassVar, List
+
+from flood_adapt.objects.events.events import Event, Template
+from flood_adapt.objects.forcing.forcing import (
+    ForcingSource,
+    ForcingType,
+)
+
+
+class HistoricalEvent(Event):
+    """BaseModel describing the expected variables and data types for parameters of HistoricalEvent that extend the parent class Event.
+
+    Attributes
+    ----------
+    name : str
+        The name of the event.
+    description : str, default=""
+        The description of the event.
+    time : TimeFrame
+        The time frame of the event.
+    template : Template, default=Template.Historical
+        The template of the event.
+    mode : Mode, default=Mode.single_event
+        The mode of the event.
+    rainfall_multiplier : float, default=1.0
+        The rainfall multiplier of the event.
+    forcings : dict[ForcingType, list[IForcing]]
+        The forcings of the event.
+    """
+
+    ALLOWED_FORCINGS: ClassVar[dict[ForcingType, List[ForcingSource]]] = {
+        ForcingType.RAINFALL: [
+            ForcingSource.CSV,
+            ForcingSource.METEO,
+            ForcingSource.SYNTHETIC,
+            ForcingSource.CONSTANT,
+        ],
+        ForcingType.WIND: [
+            ForcingSource.CSV,
+            ForcingSource.METEO,
+            ForcingSource.CONSTANT,
+        ],
+        ForcingType.WATERLEVEL: [
+            ForcingSource.MODEL,
+            ForcingSource.CSV,
+            ForcingSource.SYNTHETIC,
+            ForcingSource.GAUGED,
+        ],
+        ForcingType.DISCHARGE: [
+            ForcingSource.CSV,
+            ForcingSource.SYNTHETIC,
+            ForcingSource.CONSTANT,
+        ],
+    }
+    template: Template = Template.Historical

flood_adapt/objects/events/hurricane.py

@@ -0,0 +1,64 @@
+from typing import ClassVar, List
+
+from pydantic import BaseModel
+
+from flood_adapt.objects.events.events import Event, Template
+from flood_adapt.objects.forcing import unit_system as us
+from flood_adapt.objects.forcing.forcing import (
+    ForcingSource,
+    ForcingType,
+)
+
+
+class TranslationModel(BaseModel):
+    """BaseModel describing the expected variables and data types for translation parameters of hurricane model."""
+
+    eastwest_translation: us.UnitfulLength = us.UnitfulLength(
+        value=0.0, units=us.UnitTypesLength.meters
+    )
+    northsouth_translation: us.UnitfulLength = us.UnitfulLength(
+        value=0.0, units=us.UnitTypesLength.meters
+    )
+
+
+class HurricaneEvent(Event):
+    """BaseModel describing the expected variables and data types for parameters of HurricaneEvent that extend the parent class Event.
+
+    Attributes
+    ----------
+    name : str
+        The name of the event.
+    description : str, default=""
+        The description of the event.
+    time : TimeFrame
+        The time frame of the event.
+    template : Template, default=Template.Hurricane
+        The template of the event.
+    mode : Mode, default=Mode.single_event
+        The mode of the event.
+    rainfall_multiplier : float, default=1.0
+        The rainfall multiplier of the event.
+    forcings : dict[ForcingType, list[IForcing]]
+        The forcings of the event.
+    track_name : str
+        The name of the hurricane track.
+    """
+
+    ALLOWED_FORCINGS: ClassVar[dict[ForcingType, List[ForcingSource]]] = {
+        ForcingType.RAINFALL: [
+            ForcingSource.CONSTANT,
+            ForcingSource.CSV,
+            ForcingSource.SYNTHETIC,
+            ForcingSource.TRACK,
+        ],
+        ForcingType.WIND: [ForcingSource.TRACK],
+        ForcingType.WATERLEVEL: [ForcingSource.MODEL],
+        ForcingType.DISCHARGE: [
+            ForcingSource.CSV,
+            ForcingSource.SYNTHETIC,
+            ForcingSource.CONSTANT,
+        ],
+    }
+    template: Template = Template.Hurricane
+    hurricane_translation: TranslationModel = TranslationModel()
+    track_name: str

flood_adapt/objects/events/synthetic.py

@@ -0,0 +1,48 @@
+from typing import ClassVar, List
+
+from flood_adapt.objects.events.events import (
+    Event,
+    ForcingSource,
+    ForcingType,
+    Template,
+)
+
+
+class SyntheticEvent(Event):
+    """BaseModel describing the expected variables and data types for parameters of Synthetic that extend the parent class Event.
+
+    Attributes
+    ----------
+    time : TimeFrame
+        The time frame of the event.
+    template : Template, default=Template.Synthetic
+        The template of the event.
+    mode : Mode, default=Mode.single_event
+        The mode of the event.
+    rainfall_multiplier : float, default=1.0
+        The rainfall multiplier of the event.
+    forcings : dict[ForcingType, list[IForcing]]
+        The forcings of the event.
+    """
+
+    ALLOWED_FORCINGS: ClassVar[dict[ForcingType, List[ForcingSource]]] = {
+        ForcingType.RAINFALL: [
+            ForcingSource.CONSTANT,
+            ForcingSource.CSV,
+            ForcingSource.SYNTHETIC,
+        ],
+        ForcingType.WIND: [
+            ForcingSource.CSV,
+            ForcingSource.CONSTANT,
+        ],
+        ForcingType.WATERLEVEL: [
+            ForcingSource.CSV,
+            ForcingSource.SYNTHETIC,
+        ],
+        ForcingType.DISCHARGE: [
+            ForcingSource.CSV,
+            ForcingSource.SYNTHETIC,
+            ForcingSource.CONSTANT,
+        ],
+    }
+    template: Template = Template.Synthetic

flood_adapt/objects/forcing/csv.py

@@ -0,0 +1,68 @@
+import csv
+from pathlib import Path
+
+import pandas as pd
+
+
+def read_csv(csvpath: Path) -> pd.DataFrame:
+    """Read a timeseries file and return a pd.DataFrame.
+
+    Parameters
+    ----------
+    csvpath : Path
+        Path to the CSV file.
+
+    Returns
+    -------
+    pd.DataFrame
+        Dataframe with time as index and (a) data column(s).
+    """
+    num_columns = None
+    has_header = None
+    with open(csvpath, "r") as f:
+        try:
+            # read the first 1024 bytes to determine if there is a header
+            has_header = csv.Sniffer().has_header(f.read(1024))
+        except csv.Error:
+            has_header = False
+        f.seek(0)
+        reader = csv.reader(f, delimiter=",")
+        try:
+            first_row = next(reader)
+            num_columns = len(first_row) - 1  # subtract 1 for the index column
+        except StopIteration:
+            raise ValueError(f"The CSV file is empty: {csvpath}.")
+
+    if has_header is None:
+        raise ValueError(
+            f"Could not determine if the CSV file has a header: {csvpath}."
+        )
+    if num_columns is None:
+        raise ValueError(
+            f"Could not determine the number of columns in the CSV file: {csvpath}."
+        )
+    elif num_columns < 1:
+        raise ValueError(f"CSV file must have at least one data column: {csvpath}.")
+    columns = [f"data_{i}" for i in range(num_columns)]
+    dtype = {name: float for name in columns}
+
+    df = pd.read_csv(
+        csvpath,
+        index_col=0,
+        names=columns,
+        header=0 if has_header else None,
+        parse_dates=True,
+        infer_datetime_format=True,
+        dtype=dtype,
+    )
+
+    # Any index that cannot be converted to datetime will be NaT
+    df.index = pd.to_datetime(df.index, errors="coerce")
+    df.index.names = ["time"]
+    if len(df.index) > 2:
+        df.index.freq = pd.infer_freq(df.index)
+
+    # Drop rows where the index is NaT
+    df = df[~df.index.isna()]
+
+    return df

flood_adapt/objects/forcing/discharge.py

@@ -0,0 +1,66 @@
+import os
+from pathlib import Path
+from typing import Annotated
+
+import pandas as pd
+
+from flood_adapt.misc.utils import (
+    copy_file_to_output_dir,
+    validate_file_extension,
+)
+from flood_adapt.objects.forcing import unit_system as us
+from flood_adapt.objects.forcing.forcing import (
+    ForcingSource,
+    IDischarge,
+)
+from flood_adapt.objects.forcing.time_frame import TimeFrame
+from flood_adapt.objects.forcing.timeseries import (
+    CSVTimeseries,
+    SyntheticTimeseries,
+    TimeseriesFactory,
+)
+
+
+class DischargeConstant(IDischarge):
+    source: ForcingSource = ForcingSource.CONSTANT
+
+    discharge: us.UnitfulDischarge
+
+    def to_dataframe(self, time_frame: TimeFrame) -> pd.DataFrame:
+        time = pd.date_range(
+            start=time_frame.start_time,
+            end=time_frame.end_time,
+            freq=time_frame.time_step,
+            name="time",
+        )
+        data = [self.discharge.value for _ in range(len(time))]
+        return pd.DataFrame(index=time, data=data, columns=[self.river.name])
+
+
+class DischargeSynthetic(IDischarge):
+    source: ForcingSource = ForcingSource.SYNTHETIC
+
+    timeseries: SyntheticTimeseries
+
+    def to_dataframe(self, time_frame: TimeFrame) -> pd.DataFrame:
+        df = TimeseriesFactory.from_object(self.timeseries).to_dataframe(
+            time_frame=time_frame
+        )
+        df.columns = [self.river.name]
+        return df
+
+
+class DischargeCSV(IDischarge):
+    source: ForcingSource = ForcingSource.CSV
+
+    path: Annotated[Path, validate_file_extension([".csv"])]
+
+    units: us.UnitTypesDischarge = us.UnitTypesDischarge.cms
+
+    def to_dataframe(self, time_frame: TimeFrame) -> pd.DataFrame:
+        return CSVTimeseries.load_file(
+            path=self.path, units=us.UnitfulDischarge(value=0, units=self.units)
+        ).to_dataframe(time_frame=time_frame)
+
+    def save_additional(self, output_dir: Path | str | os.PathLike) -> None:
+        self.path = copy_file_to_output_dir(self.path, Path(output_dir))