smashbox 1.0__py2.py3-none-any.whl

smashbox/init/param.py

@@ -0,0 +1,799 @@
+import smashbox
+import os
+import yaml
+from smashbox.tools.tools import check_asset_path, print_tree
+
+
+class param:
+    """
+    Class param(): object which own :
+        - one attribute `param` with all necessary parameters fro building
+        an hydrological model with SmashBoxfunctions
+        - Some functions to maniuplate these parameters (stored in attribute param)
+
+    attributes
+    ----------
+
+    param : class smashboxparam()
+        Class which stores the main parameters
+
+    """
+
+    def __init__(self):
+
+        # self._parent_class=parent_class
+        self.param = smashboxparam()
+        """parent variable for class smashboxparam with all main parameters
+        of smashbox.
+        """
+
+    def list_param(self):
+        """
+        List all parameters in self.param
+
+        Examples
+        --------
+
+        >>> es=smashbox.SmashBox()
+        >>> sb.newmodel("RealCollobrier")
+        >>> sb.RealCollobrier.list_param()
+
+        """
+        for name, value in vars(type(self.param)).items():
+            if isinstance(value, property):
+                print(f"{name}={getattr(self.param, name)}")
+
+    def set_param(self, attr, value):
+        """
+        Setter for class attribute param().
+
+        parameters
+        ----------
+        attr : str
+        name of the attributes
+
+        value: any
+        value of the attribute
+
+        example
+        -------
+
+        self.set_param("flowdir", "path/to/the/flowdir")
+        """
+        setattr(self.param, attr, value)
+
+    def set_param_as_dict(self, param_dict):
+        """
+        Setter for class attribute param() from a dictionary of keys/values.
+
+        parameters
+        ----------
+        param_dict : dict
+        Dictionary with keys and values
+
+        example
+        -------
+
+        self.set_param_as_dict({"flowdir": "path/to/the/flowdir","epsg":2154})
+        """
+        for key, value in param_dict.items():
+            self.set_param(key, value)
+
+    def get_param(self, attr):
+        """
+        Getter for class attribute param().
+
+        parameters
+        ----------
+        attr : str
+        name of the attributes
+
+        return:
+        -------
+        any, the value stored in the attribute `attr`.
+        example
+
+        self.get_param("flowdir", "path/to/the/flowdir")
+        """
+        getattr(self.param, attr)
+
+    def write_param(self, filename="param.yaml"):
+        """
+        Dump all param attribute in a yaml file.
+
+        parameters
+        ----------
+        filename : str
+        name of file to save the parameter formated in yaml
+
+        exemple:
+        --------
+
+        self.get_param("flowdir", "path/to/the/flowdir")
+        """
+        with open(filename, "w") as file:
+            yaml.dump(self.param.__dict__, file)
+
+    def load_param(self, filename=None):
+        """
+        Load the parameters stored in a yaml file.
+
+        parameters
+        ----------
+        filename : str
+        name of file to save the parameter formated in yaml
+
+        exemple:
+        --------
+
+        self.get_param("flowdir", "path/to/the/flowdir")
+        """
+        if os.path.exists(filename):
+
+            with open(filename, "r") as file:
+
+                param = yaml.safe_load(file)
+
+                for key, value in param.items():
+                    self.set_param(key, value)
+
+    def list_assets_files(self):
+        """
+        List all assets files owned by SmashBox. Thes files are data such as
+        the flow directions and outlets database.
+
+        """
+        print_tree(os.path.join(smashbox.__path__[0], "asset"))
+
+
+class smashboxparam:
+    """
+    The class `smashboxparam` contains the main parameters needed to build an
+    SmashBox model. Thes parameters are stored in different attributes.
+
+    """
+
+    def __init__(self):
+        """
+        Initialisation of the attributes of class smashboxparam. All attributes
+        have a default value.
+        """
+        self._assets_dir = None
+        """Path to the asset directory. str"""
+        if not os.path.exists(
+            os.path.join(os.path.expanduser("~"), ".smashbox", "asset")
+        ):
+            self._assets_dir = os.path.join(smashbox.__path__[0], "asset")
+            """Path to the asset directory. str"""
+        else:
+            self._assets_dir = os.path.join(
+                os.path.expanduser("~"), ".smashbox", "asset"
+            )
+            """Path to the asset directory. str"""
+
+        self._flowdir = os.path.join(self._assets_dir, "flwdir", "flowdir_fr_1000m.tif")
+        """Path to the flow direction file formated in geotif. str"""
+
+        self._outlets_database = os.path.join(self._assets_dir, "outlets", "db_sites.csv")
+        """ Path to the outlet database iformatted in csv. str."""
+
+        self._setup_file = os.path.join(
+            self._assets_dir,
+            "setup",
+            "setup_rhax_gr4_dt3600.yaml",
+        )
+        """Path to a Smash setup file to be used. Format yaml. If only the name
+            of the file is given, the file will be searched in the asset directory.
+        """
+        self._bbox = None  # {"left": 0, "bottom": 0, "right": 0, "top": 0}
+        """Bounding box of the area to be modeled. dict | None, Optional.
+            bbox is a dictionary with
+            the following convention:
+            bbox={"left": c_weast, "bottom": y_south, "right": x_east, "top": x_north}
+        """
+
+        self._epsg = 2154
+        """EPSG code of the coordinate system used. Integer."""
+
+        self._outletsID = []
+        """List of the outlets (key or name) to include in the mesh.
+            If the list is left empty, all outlets found in the area
+            defined by bbox will be included. If None, no outlet will be added.
+            The outlet name must be chosen
+            among the list of the outlet_database file in the column defined
+            by the attribute outlets_database_fields ('id')
+        """
+
+        self._outlets_shapefile = None
+        """Path to the shape file containing the oultlet boundaries. Optional"""
+
+        self._smash_parameters = os.path.join(self._assets_dir, "params")
+        """Path to a directory with calibrated smash parameters. String | None.
+            All parameters must be stroed separetly in geotiff file.
+        """
+
+        self._smash_parameters_dt = None
+        """Time-step for which the smash_parameters has been originaly calibrated. 
+        int | float. If not None and if the model parameters is different, the parameters 
+        "ct", "kexc", "llr" will be transformed according the relation 
+        described in A.Ficchi, 2017.
+        """
+
+        self._outlets_database_fields = {
+            "coord_x": "X_L93",
+            "coord_y": "Y_L93",
+            "area": "SURF",
+            "id": "CODE_SITE",
+        }
+        """Dictionary with the name of the useful column field {key: field name}.
+        dict.
+        """
+
+        self.enhanced_smash_input_data = False
+        """
+        Use an enhanced version of the smash.model() method. The reading of the input atmospheric data functions used by smash have been rewritten in a different way provide more options and flexibility.
+        - read same type of data like SMASH: precipitation, snow, temperature and evapotranspration. 
+        Support Geotiff format only.
+        - Merge all reading function in one.
+        - Configure the pattern of the date to search in the filename. Use common date formatters.
+        Handle the occurence number (starting from 0) with %n at the end of the date pattern. ex: %Y%m%d%H%1.
+        - Improve logs: new log clearly warn user about which files have been read and which files are missing.
+        - Fix a mistake during the reading of the evapotranspration. In SMASH the 
+        evapotranspiration from the previous day is read instead of the current one.
+        - Read several data source by priority: each kind of data may have different source.
+        If one is missing, the model will read the second one, ect...
+        - Partially handle the reading of the continuous evapotranspiration in an operationnal context.
+        To do that, a sim-link of the etp data (delayed by 1 day) is created named with the date 
+        of the current day.   
+        - Handle time zone to shift the desagregation curve of the PET during the day.
+        - Improve the speed of the reading. Technically, an index of the dates and the 
+        corresponding data files is created. To eficiency run through the long list of data files
+        and performs a regex search to match a date, a simple searh algorithm is build on top of 
+        the main loop to avoid performing a regex on thousand files. 
+        This improvement is noticable for model running on few time-step. It is particulary 
+        important when running smash in an operationnal context.
+        """
+
+    @property
+    def asset_dir(self):
+        """
+        Type:
+        -----
+        Property/Setter: str | os.PathLike
+
+        Description:
+        ------------
+        Path to the asset directory. Default value is the asset directory of
+        SmashBox copied in the user space.
+
+        exemple
+        -------
+        self.asset_dir = "path/to/my/asset/dir"
+
+        """
+        return self._assets_dir
+
+    @asset_dir.setter
+    def asset_dir(self, value: os.PathLike):
+        """
+        Setter. Path to the asset directory.
+        value : os.PathLike
+
+        exemple
+        -------
+        self.asset_dir = "path/to/my/asset/dir"
+
+        """
+        if os.path.isdir(value):
+            self._asset_dir = value
+        else:
+            raise ValueError(f"{value} is not a valid directory.")
+
+    @property
+    def outlets_database(self):
+        """
+        Type:
+        -----
+        Property/Setter: str | os.PathLike.
+
+        Description:
+        ------------
+        Path to the outlet database formatted in csv. Field name,
+        coordinates (X and Y) and the surface of the catchment must exists.
+        Field name can be configure with attribute outlets_database_fields.
+
+        exemple
+        -------
+        self.outlets_database = "path/to/my/database.csv"
+
+        """
+        return self._outlets_database
+
+    @outlets_database.setter
+    def outlets_database(self, value: os.PathLike):
+        """
+        Setter. Path to the outlet database formatted in csv. Field name,
+        coordinates (X and Y) and the surface of the catchment must exists.
+        Field name can be configure with attribute outlets_database_fields.
+        value : os.PathLike
+
+        exemple
+        -------
+        self.outlets_database = "path/to/my/database.csv"
+
+        """
+        self._outlets_database = check_asset_path(
+            os.path.join(self.asset_dir, "outlets"), value
+        )
+
+    @property
+    def setup_file(self):
+        """
+        Type:
+        -----
+        Property/Setter: str | os.PathLike.
+
+        Description:
+        ------------
+        Path to the smash setup file formatted in yaml. If only the name
+            of the file is given, the infered path will be the asset directory.
+
+        exemple
+        -------
+        self.setup_file = "path/to/my/setup.yaml"
+
+        """
+        return self._setup_file
+
+    @setup_file.setter
+    def setup_file(self, value: os.PathLike):
+        """
+        Setter. Path to the smash setup file formatted in yaml.
+        value : os.PathLike
+
+        exemple
+        -------
+        self.setup_file = "path/to/my/setup.yaml"
+
+        """
+        self._setup_file = check_asset_path(os.path.join(self.asset_dir, "setup"), value)
+        # self._parent_class._parent_class.mysetup.load_setup(self._setup_file)
+
+    @property
+    def flowdir(self):
+        """
+        Type:
+        -----
+        Property/Setter: str | os.PathLike.
+
+        Description:
+        ------------
+        The path to the flowdir (flow direction) file formatted in Geotif. Refer to the Smash
+        documentation for more details: `https://smash.recover.inrae.fr/user_guide/
+        data_and_format_description/cance.html#flow-direction`
+
+        """
+        return self._flowdir
+
+    @flowdir.setter
+    def flowdir(self, value: os.PathLike):
+        """
+        Setter. Path to the flowdir file formatted in Geotif.
+        value : os.PathLike
+
+        exemple
+        -------
+        self.flowdir = "path/to/my/flowdir.tif"
+
+        """
+        self._flowdir = check_asset_path(os.path.join(self.asset_dir, "flowdir"), value)
+
+    @property
+    def bbox(self):
+        """
+        Type:
+        -----
+        Property/Setter: dict
+
+        Description:
+        ------------
+        The Bounding box of the area to be modeled. dict | None, Optional.
+        bbox is a dictionary with the following convention:
+        bbox={"left": c_weast, "bottom": y_south, "right": x_east, "top": x_north}
+
+        exemple
+        -------
+        self.bbox = {'left': 0, 'bottom': 0, 'right': 10, 'top': 10}
+
+        """
+        return self._bbox
+
+    @bbox.setter
+    def bbox(self, value: dict | None):
+        """
+        Setter. Set the bounding box of the domain.
+        value : dict | None
+
+        exemple
+        -------
+        self.bbox = {'left': 0, 'bottom': 0, 'right': 10, 'top': 10}
+
+        """
+        if value is None:
+            self._bbox = value
+
+        if sorted(["left", "bottom", "right", "top"]) == sorted(list(value.keys())):
+            self._bbox = value
+        else:
+            raise ValueError(
+                f"{value} is not a boundingbox. A boundingbox must be a dict"
+                "like {'left': 0, 'bottom': 0, 'right': 0, 'top': 0}"
+            )
+
+    @property
+    def epsg(self):
+        """
+        Type:
+        -----
+        Property/Setter: int
+
+        Descripion:
+        -----------
+        EPSG code of the coordinate system used.
+
+        exemple
+        -------
+        self.epsg = 2154
+
+        """
+        return self._epsg
+
+    @epsg.setter
+    def epsg(self, value: int):
+        """
+        Setter. Set the epsg code of the coordinate system used.
+        value : int
+
+        exemple
+        -------
+        self.epsg = 2154
+
+        """
+        self._epsg = value
+
+    @property
+    def outletsID(self):
+        """
+        Type:
+        -----
+        Property/Setter : list
+
+        Descripion:
+        -----------
+        List of the outlets (key or name) to include in the mesh.
+        If the list is left empty, all outlets found in the area
+        defined by bbox will be included. If None, no outlet will be added.
+        The outlet name must be chosen
+        among the list of the outlet_database file in the column defined
+        by the attribute outlets_database_fields ('id')
+
+        exemple
+        -------
+        self.outletsID = ['V156730', 'V200820']
+
+        """
+        return self._outletsID
+
+    @outletsID.setter
+    def outletsID(self, value: list):
+        """
+        Setter. Set the list of the outlet code (or name) used to build
+        the mesh.
+        value : list of str
+
+        exemple
+        -------
+        self.outletsID = ['V156730', 'V200820']
+
+        """
+        self._outletsID = value
+
+    @property
+    def outlets_shapefile(self):
+        """
+        Type:
+        -----
+        Property/Setter: str | os.PathLike.
+
+        Descripion:
+        -----------
+        Path of the shapefile used to position the outlets.
+
+        exemple
+        -------
+        self.outlets_shapefile = 'path/to/the/shapefile.shp'
+        """
+        return self._outlets_shapefile
+
+    @outlets_shapefile.setter
+    def outlets_shapefile(self, value: None | os.PathLike = None):
+        """
+        Setter. Set the path of the shapefile used to position the outlets.
+        value : None | os.PathLike
+
+        exemple
+        -------
+        self.outlets_shapefile = 'path/to/the/shapefile.shp'
+
+        """
+        if value is None:
+            return
+
+        if os.path.exists(value):
+            self._outlets_shapefile = value
+        else:
+            raise ValueError(f"'{value}' is not a valid path.")
+
+    @property
+    def smash_parameters(self):
+        """
+        Type:
+        -----
+        Property/Setter: str | os.PathLike.
+
+        Path to a directory which contain the calibrated smash parameters.
+        Each parameter must be stored separetly in a geotiff file
+
+        exemple
+        -------
+        self.smash_parameters = 'path/to/the/directory/'
+
+        """
+        return self._smash_parameters
+
+    @smash_parameters.setter
+    def smash_parameters(self, value: None | os.PathLike = None):
+        """
+        Setter. Set the  path to a directory where the smash parameters are
+        stored.
+        value : None | os.PathLike
+
+        exemple
+        -------
+        self.smash_parameters = 'path/to/the/directory/'
+
+        """
+        if value is None:
+            return
+
+        if os.path.isdir(value):
+
+            if len(os.listdir(value)) == 0:
+                raise ValueError(f"'{value}' is an empty directory.")
+
+            for file in os.listdir(value):
+                if not file.endswith(".tif"):
+                    raise ValueError(
+                        f"'{value}' contains files other than geotiff .tif format."
+                        " These files are likely not compatible with SMASH parameters."
+                    )
+
+            self._smash_parameters = value
+        else:
+            raise ValueError(f"'{value}' is not a valid directory.")
+
+    @property
+    def smash_parameters_dt(self):
+        """
+        Type:
+        -----
+        Property/Setter: int | float.
+
+        Time-step for which the smash_parameters has been originaly calibrated.
+        int | float.If not None and if the model parameters is different, the parameters
+        "ct", "kexc", "llr" will be transformed according the relation
+        described in A.Ficchi, 2017.
+
+        exemple
+        -------
+        self.smash_parameters_dt = 900
+
+        """
+        return self._smash_parameters_dt
+
+    @smash_parameters_dt.setter
+    def smash_parameters_dt(self, value: None | os.PathLike = None):
+        """
+        Setter. Set the time-step for which the smash_parameters has been originaly calibrated.
+        int | float. If not None and if the model parameters is different, the parameters
+        "ct", "kexc", "llr" will be transformed according the relation
+        described in A.Ficchi, 2017.
+        value : int | float
+
+        exemple
+        -------
+        self.smash_parameters_dt = 900.
+
+        """
+
+        self._smash_parameters_dt = value
+
+    @property
+    def outlets_database_fields(self):
+        """
+        type:
+        ----
+        Property/Setter: dict
+
+        Description:
+        ------------
+        A dictionary with a corresponding `key` - `column name`. The 'key' of the dictionary
+        must match with desired 'column name' in the selected `outlet_database`.
+        Needed keys are:
+
+            - coord_x : X coordinate of the outlet
+
+            - coord_y : Y coordinate of the outlet
+
+            - area : Surface of the catchment
+
+            - id : Name or label of the outlet
+
+        exemple
+        -------
+        self.outlets_database_fields = '{
+            "coord_x": "X_L93",
+            "coord_y": "Y_L93",
+            "area": "SURF",
+            "id": "ID_EX",
+        }
+
+        """
+        return self._outlets_database_fields
+
+    @outlets_database_fields.setter
+    def outlets_database_fields(self, value: dict):
+        """
+        type:
+        ----
+        Property/Setter: dict
+
+        Description:
+        ------------
+        A dictionary with a corresponding `key` - `column name`. The 'key' of the dictionary
+        must match with desired 'column name' in the selected `outlet_database`.
+        Needed keys are:
+            - coord_x : X coordinate of the outlet
+            - coord_y : Y coordinate of the outlet
+            -.area : Surface of the catchment
+            - id : Name or label of the outlet
+
+        exemple
+        -------
+        self.outlets_database_fields = '{
+            "coord_x": "X_L93",
+            "coord_y": "Y_L93",
+            "area": "SURF",
+            "id": "ID_EX",
+        }
+
+        """
+        if sorted(["coord_x", "coord_y", "area", "id"]) == sorted(list(value.keys())):
+            self._outlets_database_fields = value
+        else:
+            raise ValueError(
+                f"{value} doe not correspond to any outlets_database_fields."
+                " outlets_database_fields must look like"
+                " {'coord_x': 'X_L93','coord_y': 'Y_L93','area':'SURF','id':'ID_EX'}"
+            )
+        self._outlets_database_fields = value
+
+    @property
+    def enhanced_smash_input_data(self):
+        """
+        type:
+        ----
+        Property/Setter: bool
+
+        Description:
+        ------------
+        Use an enhanced version of the smash.model() method. The reading of the input
+        atmospheric data functions used by smash have been rewritten in a different way
+        provide more options and flexibility.
+        - read same type of data like SMASH: precipitation, snow, temperature and
+        evapotranspration.
+        Support Geotiff format only.
+        - Merge all reading function in one.
+        - Configure the pattern of the date to search in the filename. Use common date
+        formatters. Handle the occurence number (starting from 0) with %n at the end of
+        the date pattern. ex: %Y%m%d%H%1.
+        - Improve logs: new log clearly warn user about which files have been read and
+        which files are missing.
+        - Fix a mistake during the reading of the evapotranspration. In SMASH the
+        evapotranspiration from the previous day is read instead of the current one.
+        - Read several data source by priority: each kind of data may have different source.
+        If one is missing, the model will read the second one, ect...
+        - Partially handle the reading of the continuous evapotranspiration in an
+        operationnal context. To do that, a sim-link of the etp data (delayed by 1 day)
+        is created named with the date
+        of the current day.
+        - Handle time zone to shift the desagregation curve of the PET during the day.
+        - Improve the speed of the reading. Technically, an index of the dates and the
+        corresponding data files is created. To eficiency run through the long list of data files
+        and performs a regex search to match a date, a simple searh algorithm is build on top of
+        the main loop to avoid performing a regex on thousand files.
+        This improvement is noticable for model running on few time-step. It is particulary
+        important when running smash in an operationnal context.
+
+        new setup options:
+        ------------------
+        prcp_date_pattern=%Y%m%d%H%0
+        prcp_directories:
+            1 : '/home/maxime/DATA/REUNION/PLUIE_REUNION/tests_tr/ANTILOPE_J1'
+            2 : '/home/maxime/DATA/REUNION/PLUIE_REUNION/tests_tr/ANTILOPE_TR'
+            3 : '/home/maxime/DATA/REUNION/PLUIE_REUNION/tests_tr/GRID_LESOL_500m'
+        pet_directories:
+            1 : "/home/maxime/DATA/REUNION/ETPJ_continue"
+            2 : "/home/maxime/DATA/REUNION/ETPJ_interannuelle_250_lnZ"
+        continuous_pet:
+            1: true
+            2: false
+        timezone: "UTC"
+
+        """
+        return self._enhanced_smash_input_data
+
+    @enhanced_smash_input_data.setter
+    def enhanced_smash_input_data(self, value: bool):
+        """
+        type:
+        ----
+        Property/Setter: bool
+
+        Description:
+        ------------
+        Use an enhanced version of the smash.model() method. The reading of the input
+        atmospheric data functions used by smash have been rewritten in a different way
+        provide more options and flexibility.
+        - read same type of data like SMASH: precipitation, snow, temperature and
+        evapotranspration.
+        Support Geotiff format only.
+        - Merge all reading function in one.
+        - Configure the pattern of the date to search in the filename. Use common date
+        formatters. Handle the occurence number (starting from 0) with %n at the end of
+        the date pattern. ex: %Y%m%d%H%1.
+        - Improve logs: new log clearly warn user about which files have been read and
+        which files are missing.
+        - Fix a mistake during the reading of the evapotranspration. In SMASH the
+        evapotranspiration from the previous day is read instead of the current one.
+        - Read several data source by priority: each kind of data may have different source.
+        If one is missing, the model will read the second one, ect...
+        - Partially handle the reading of the continuous evapotranspiration in an
+        operationnal context. To do that, a sim-link of the etp data (delayed by 1 day)
+        is created named with the date
+        of the current day.
+        - Handle time zone to shift the desagregation curve of the PET during the day.
+        - Improve the speed of the reading. Technically, an index of the dates and the
+        corresponding data files is created. To eficiency run through the long list of data files
+        and performs a regex search to match a date, a simple searh algorithm is build on top of
+        the main loop to avoid performing a regex on thousand files.
+        This improvement is noticable for model running on few time-step. It is particulary
+        important when running smash in an operationnal context.
+
+        new setup options:
+        ------------------
+        prcp_date_pattern=%Y%m%d%H%0
+        prcp_directories:
+            1 : '/home/maxime/DATA/REUNION/PLUIE_REUNION/tests_tr/ANTILOPE_J1'
+            2 : '/home/maxime/DATA/REUNION/PLUIE_REUNION/tests_tr/ANTILOPE_TR'
+            3 : '/home/maxime/DATA/REUNION/PLUIE_REUNION/tests_tr/GRID_LESOL_500m'
+        pet_directories:
+            1 : "/home/maxime/DATA/REUNION/ETPJ_continue"
+            2 : "/home/maxime/DATA/REUNION/ETPJ_interannuelle_250_lnZ"
+        continuous_pet:
+            1: true
+            2: false
+        timezone: "UTC"
+
+        """
+        self._enhanced_smash_input_data = value