wolfhece.multicriteria.analysis =============================== .. py:module:: wolfhece.multicriteria.analysis .. autoapi-nested-parse:: This module contains the objects needed to perform a multi-criteria analysis on spatially distributed hydrodynamic data. The module tests are located in the folder: tests/multicriteria/test_analysis.py, in HECEPython repository. Authors: Utashi Ciraane, HECE, University of Liège, Belgium. Module Contents --------------- .. py:class:: Operator Bases: :py:obj:`enum.StrEnum` .. autoapi-inheritance-diagram:: wolfhece.multicriteria.analysis.Operator :parts: 1 :private-bases: Mathematical operators used in the module. .. py:attribute:: AVERAGE :value: 'average' .. py:attribute:: BETWEEN :value: 'between' .. py:attribute:: BETWEEN_STRICT :value: 'strictly between' .. py:attribute:: EQUAL :value: 'equal' .. py:attribute:: INFERIOR :value: 'inferior' .. py:attribute:: INFERIOR_OR_EQUAL :value: 'inferior or equal' .. py:attribute:: OUTSIDE :value: 'outside' .. py:attribute:: OUTSIDE_STRICT :value: 'strictly outside' .. py:attribute:: PERCENTAGE :value: 'percentage' .. py:attribute:: PRODUCT :value: 'product' .. py:attribute:: SUM :value: 'sum' .. py:attribute:: SUPERIOR :value: 'superior' .. py:attribute:: SUPERIOR_OR_EQUAL :value: 'superior or equal' .. py:attribute:: THRESHOLD :value: 'threshold' .. py:attribute:: WEIGHTED_SUM :value: 'weighted sum' .. py:class:: Format(*args, **kwds) Bases: :py:obj:`enum.Enum` .. autoapi-inheritance-diagram:: wolfhece.multicriteria.analysis.Format :parts: 1 :private-bases: Types of data formats used in the module. .. py:attribute:: FLOAT32 .. py:attribute:: FLOAT64 .. py:attribute:: INT32 .. py:attribute:: INT64 .. py:class:: Status(*args, **kwds) Bases: :py:obj:`enum.Enum` .. autoapi-inheritance-diagram:: wolfhece.multicriteria.analysis.Status :parts: 1 :private-bases: Status of objects in the module .. py:attribute:: PROGRESS_BAR_DISABLE :value: False .. py:class:: Constant(*args, **kwds) Bases: :py:obj:`enum.Enum` .. autoapi-inheritance-diagram:: wolfhece.multicriteria.analysis.Constant :parts: 1 :private-bases: This class contains the constants used throughout the module. .. py:attribute:: EPSG :value: 31370 .. py:attribute:: ONE :value: 1 .. py:attribute:: ZERO :value: 0 .. py:attribute:: CONDITION :value: 'condition' .. py:data:: CustomScoreRoutine .. py:class:: Variable(variable: numpy.ma.MaskedArray | numpy.ndarray | wolfhece.wolf_array.WolfArray, dtype: Union[numpy.dtype, str] = Format.FLOAT32.value) This class is used to store variable (data: array) that will be used in the multi-criteria analysis. The types of variable allowed are: - np.ma.MaskedArray: A numpy masked array. - np.ndarray: A numpy array. - WolfArray: A WolfArray object from the wolfhece library. .. py:attribute:: _variable :type: numpy.ma.MaskedArray :value: None .. py:attribute:: _dtype .. py:property:: variable :type: numpy.ma.MaskedArray Return the variable. :return: The variable as a numpy masked array. .. py:property:: dtype :type: type Return the data type of the variable. :return: The data type of the variable. .. py:class:: Criteria(threshold: Union[float, int, tuple], condition: Literal[Operator, Operator, Operator, Operator, Operator, Operator, Operator, Operator] = Operator.SUPERIOR_OR_EQUAL) This class is used to define a criteria included in the multi-criteria analysis It contains a threshold and a condition:. - superior, - inferior, - equal, - superior or equal, - inferior or equal, - between, - strictly between, - outside, - strictly outside. The condition defines how the threshold is applied to select values in the variable true (1) or False (0). .. py:attribute:: _available_conditions .. py:attribute:: _needs_tuple .. py:attribute:: _criteria :type: dict .. py:property:: threshold :type: float Get the threshold of the criteria. :return: The threshold as a float. .. py:property:: condition :type: str Get the condition. :return: The condition as a string. .. py:property:: criteria :type: dict Return the criteria. :return: The criteria as a dictionary. .. py:method:: _number_to_tuple(value: Union[float, int]) -> tuple Convert a number to a tuple of two elements. :param value: The number to convert. :return: A tuple with the number as both elements. .. py:method:: _tuple_to_number(value: tuple) -> float Convert a tuple of two elements to a number. :param value: The tuple to convert. :return: The first element of the tuple as a float. .. py:class:: Score(variable: Variable, criteria: Criteria, dtype=Format.INT32.value, compute_fn: Optional[CustomScoreRoutine] = None) This class scores a Variable based on the given criteria (threshold & condition). The score is a np.MaskedArray with the same shape as the given variable. The score contains integer values indicating whether the variable meets the criteria (1) or (0). If the variable is masked, the score is also masked. Binary notation was selected to allow mathematical operations. .. py:attribute:: _variable :value: None .. py:property:: variable :type: Variable Get the variable. :return: The variable as a Variable object. .. py:attribute:: _criteria :value: None .. py:property:: criteria :type: Criteria Get the criteria. :return: The criteria as a Criteria object. .. py:attribute:: _score :type: numpy.ma.MaskedArray :value: None .. py:attribute:: _dtype :value: None .. py:attribute:: _compute_fn :value: None .. py:property:: compute_fn :type: Optional[CustomScoreRoutine] Get the custom compute function. :return: Callable used to compute score, or None. .. py:property:: dtype :type: type Get the data type of the score. :return: The data type of the score. .. py:property:: score :type: numpy.ma.MaskedArray Get the score. :return: The score as a numpy masked array. .. py:method:: _compute_score() Compute the score based on the variable and criteria. :return: The score as a numpy masked array. .. py:class:: Scores(scores: dict[str, Score]) This class is used to store multiple scores from different criteria as dictionary. It contains a dictionary of scores, where the keys are the score names and the values are the Score objects. .. py:attribute:: _scores :type: dict[str, Score] :value: None .. py:property:: scores :type: dict[str, Score] Get the scores. :return: The scores as a dictionary of Score objects. .. py:property:: number :type: int Get the number of scores. :return: The number of scores in the dictionary. .. py:method:: add_score(name: str, score: Score) -> None Add a score to the scores dictionary. :param name: The name of the score. :param score: The Score object to add. .. py:method:: get_score(name: str) -> Score Get a score by its name. :param name: The name of the score to get. :return: The Score object with the given name. .. py:method:: remove_score(name: str) -> None Remove a score by its name. :param name: The name of the score to remove. .. py:class:: Operations(scores: Scores, int_type: str = Format.INT32.value, float_type: str = Format.FLOAT32.value, weight: dict = None) This class is used to perform mathematical operations on scores. N.B.: if needed operations from other libraries can be added here. for instance **pymcdm, scikit-mcda, etc.** .. py:attribute:: _scores :value: None .. py:attribute:: _int_type :value: None .. py:attribute:: _float_type :value: None .. py:attribute:: _weight :value: None .. py:property:: scores :type: Scores Get the Scores object. :return: The Scores object. .. py:property:: int_type :type: str Get the integer data type used in the operations. :return: The integer data type as a string. .. py:property:: float_type :type: str Get the float data type used in the operations. :return: The float data type as a string. .. py:property:: weight :type: dict Get the weight dictionary. :return: The weight dictionary. .. py:attribute:: _available_operations .. py:method:: sum() -> numpy.ma.MaskedArray Sum all scores in the Scores object. :return: The sum of all scores as a numpy masked array. .. py:method:: product() -> numpy.ma.MaskedArray Calculate the product of all scores in the Scores object. :return: The product of all scores as a numpy masked array. .. py:method:: weighted_sum() -> numpy.ma.MaskedArray Calculate the weighted sum of all scores in the Scores object. :return: The weighted sum of all scores as a numpy masked array. .. py:method:: average() -> numpy.ma.MaskedArray Calculate the average of all scores in the Scores object. :return: The average of all scores as a numpy masked array. .. py:method:: percentage() -> numpy.ma.MaskedArray Calculate the percentage of each score in the Scores object. :return: The percentage of each score as a numpy masked array. .. py:method:: apply_operation(operation: Literal[Operator, Operator, Operator, Operator, Operator]) -> numpy.ma.MaskedArray Select an operation to perform on the scores. :param operation: The operation to perform. :return: The result of the operation as a numpy masked array. .. py:class:: Results(operations: Operations, mold: wolfhece.wolf_array.WolfArray = None, method: Literal[Operator, Operator, Operator, Operator, Operator] = Operator.SUM) This class is used to collect results of the Operations module. It allows: - to define the mold (a WolfArray) which serve as the geo-spatial extent computed results, - to define the method used to compute scores, - to get and write the results. .. py:attribute:: _operations :value: None .. py:attribute:: _mold :value: None .. py:attribute:: _method :value: None .. py:property:: operations :type: Operations Get the Operations object. :return: The Operations object. .. py:property:: mold :type: wolfhece.wolf_array.WolfArray Get the mold used for the results. :return: The mold as a WolfArray. .. py:property:: method :type: str Get the method used for the results. :return: The method as a string. .. py:property:: header :type: wolfhece.wolf_array.header_wolf Get the header of the mold. :return: The header of the mold as a header_wolf object. .. py:property:: as_numpy_array :type: numpy.ma.MaskedArray .. py:property:: as_WolfArray :type: wolfhece.wolf_array.WolfArray Get the results as a WolfArray. :return: The results as a WolfArray. .. py:method:: create_header_wolf(origx: float = None, origy: float = None, origz: float = None, dx: float = None, dy: float = None, dz: float = None, nbx: int = None, nby: int = None, nbz: int = None) Create a header_wolf object. The header_wolf object is used to describe the spatial characteristics of the array. :param origx: The x-coordinate of the origin (in 2D - lower left corner), defaults to None. :type origx: float, optional :param origy: The y-coordinate of the origin (in 2D - lower left corner), defaults to None. :type origy: float, optional :param origz: The z-coordinate of the origin, defaults to None. :type origz: float, optional :param dx: The x-spacing (discretization in the x direction), defaults to None. :type dx: float, optional :param dy: The y-spacing (discretization in the x direction), defaults to None. :type dy: float, optional :param dz: The z-spacing, defaults to None. :type dz: float, optional :param nbx: The number of columns, defaults to None. :type nbx: int, optional :param nby: The number of rows, defaults to None. :type nby: int, optional :param nbz: The number of layers, defaults to None. :type nbz: int, optional :return: A header_wolf object with the given parameters. :rtype: header_wolf .. py:method:: create_WolfArray(dtype=None) -> wolfhece.wolf_array.WolfArray Create an empty WolfArray with the given name, and header. :param dtype: The data type of the WolfArray, defaults to np.float32. :type dtype: Union[type, str] :return: An empty WolfArray with the given name and header. :rtype: WolfArray .. py:method:: as_results(results: numpy.ma.MaskedArray, EPSG: int = 31370, dtype: Union[type, str] = None, write_to: Union[pathlib.Path, str] = None) -> wolfhece.wolf_array.WolfArray Write the results to a WolfArray file. :param output_path: The path to write the results to. :param name: The name of the results file. :param header: The header for the WolfArray. :param dtype: The data type of the WolfArray. .. py:class:: Input(name: str, array: numpy.ma.MaskedArray | numpy.ndarray | wolfhece.wolf_array.WolfArray, condition: Literal[Operator, Operator, Operator, Operator, Operator] = Operator.SUPERIOR_OR_EQUAL, threshold: Union[float, int] = 0.0, score_routine: Optional[CustomScoreRoutine] = None) This class stores the inputs of the MultiCriteriaAnalysis. Also, it ensures that the inputs are valid and consistent to feed the MulticriteriAnalysis tool. Optionally, a custom scoring routine can be provided to compute a continuous score instead of the default binary score. .. py:attribute:: _name :value: None .. py:attribute:: _array :value: None .. py:attribute:: _condition :value: None .. py:attribute:: _threshold :value: None .. py:attribute:: _score_routine :value: None .. py:attribute:: _score :value: None .. py:property:: name :type: str Get the name of the input. :return: The name of the input. .. py:property:: array :type: Union[numpy.ma.MaskedArray, numpy.ndarray, wolfhece.wolf_array.WolfArray] Get the array of the input. :return: The array as a numpy masked array. .. py:property:: condition :type: Literal[Operator, Operator, Operator, Operator, Operator] Get the condition of the input. :return: The condition as a string. .. py:property:: threshold :type: Union[float, int] Get the threshold of the input. :return: The threshold as a float or an int. .. py:property:: score_routine :type: Optional[CustomScoreRoutine] Get the custom score routine. :return: Callable used for custom score computation, or None. .. py:property:: score :type: Score Get the score of the input. :return: The score as a Score object. .. py:class:: MulticriteriAnalysis(inputs: Union[list[Input], tuple[Input], Input], method: Literal[Operator, Operator, Operator, Operator, Operator] = Operator.PERCENTAGE, dtype: Union[type, str] = Format.FLOAT32.value, mold: wolfhece.wolf_array.WolfArray = None, weight: dict[Input, Union[int, float]] = None, write_to: Union[pathlib.Path, str] = None, EPSG: int = None) This class performs a multi-criteria analysis based on a set of inputs (variables and criteria). The inputs are: - name: The name of the variable (observations). - array: The array (matrix) containing the variable (observations). - condition: The condition (criteria) used to distinguish between good and bad variables. Basically, the condition is used to obtain a binary score (0 or 1) for each value in the array. - Threshold: The value(s) used as limits for the condition. .. py:attribute:: _inputs :type: list[Input] :value: None .. py:attribute:: _method :type: str :value: None .. py:attribute:: _dtype :type: Union[type, str] :value: None .. py:attribute:: _mold :type: wolfhece.wolf_array.WolfArray :value: None .. py:attribute:: _weight :type: dict[Input, Union[int, float]] :value: None .. py:attribute:: _path :type: Union[pathlib.Path, str] :value: None .. py:attribute:: _EPSG :type: int :value: None .. py:property:: inputs :type: list[Input] Get the inputs of the MultiCriteriaAnalysis. :return: The inputs as a list of Input objects. .. py:property:: method :type: Literal[Operator, Operator, Operator, Operator, Operator] Get the method used for the MultiCriteriaAnalysis. :return: The method as a string. .. py:property:: dtype :type: Union[type, str] Get the data type used for the MultiCriteriaAnalysis. :return: The data type as a string or a numpy dtype. .. py:property:: mold :type: wolfhece.wolf_array.WolfArray Get the mold used for the MultiCriteriaAnalysis. :return: The mold as a WolfArray. .. py:property:: weight :type: dict[Input, Union[int, float]] Get the weight dictionary used by the weighted sum operation. :return: The weight dictionary or None. .. py:property:: path :type: Union[pathlib.Path, str] Get the path where the results will be written. :return: The path as a string or a Path object. .. py:property:: EPSG :type: int Get the EPSG code for the results. :return: The EPSG code as an integer. .. py:property:: number_of_inputs :type: int Get the number of inputs. :return: The number of inputs. .. py:property:: _weight_by_name :type: dict[str, Union[int, float]] Convert Input-keyed weights to score-name keyed weights. :return: Name-keyed weight dictionary for Operations. .. py:property:: scores :type: Scores Get the scores for each input. :return: The scores as a Scores object. .. py:property:: operations :type: Operations Get the operations to be performed on the scores. :return: The Operations object. .. py:property:: results :type: wolfhece.wolf_array.WolfArray Perform the MultiCriteria Analysis on the inputs. :return: The results of the analysis as a WolfArray object. .. py:method:: write_result() -> wolfhece.wolf_array.WolfArray Write the results to a WolfArray file. :return: The results as a WolfArray.