wolfhece.MulticriteriAnalysis

This module contains the objects needed to perform a multi-criteria analysis for fish passage on spatially distributed hydrodynamic data.

The module tests are located in the folder: tests/test_MulticriteriAnalysis.py file, in HECEPython repository.

Authors: Utashi Ciraane, HECE, University of Liège, Belgium.

Module Contents

class wolfhece.MulticriteriAnalysis.Operator(*args, **kwds)

Bases: enum.Enum

Mathematical operators used in the module.

AVERAGE = 'average'

BETWEEN = 'between'

BETWEEN_STRICT = 'strictly between'

EQUAL = 'equal'

INFERIOR = 'inferior'

INFERIOR_OR_EQUAL = 'inferior or equal'

OUTSIDE = 'outside'

OUTSIDE_STRICT = 'strictly outside'

PERCENTAGE = 'percentage'

PRODUCT = 'product'

SUM = 'sum'

SUPERIOR = 'superior'

SUPERIOR_OR_EQUAL = 'superior or equal'

THRESHOLD = 'threshold'

WEIGHTED_SUM = 'weighted sum'

class wolfhece.MulticriteriAnalysis.Format(*args, **kwds)

Bases: enum.Enum

Types of data formats used in the module.

FLOAT32

FLOAT64

INT32

INT64

class wolfhece.MulticriteriAnalysis.Status(*args, **kwds)

Bases: enum.Enum

Status of objects in the module

PROGRESS_BAR_DISABLE = False

class wolfhece.MulticriteriAnalysis.Constant(*args, **kwds)

Bases: enum.Enum

This class contains the constants used throughout the module.

EPSG = 31370

ONE = 1

ZERO = 0

CONDITION = 'condition'

class wolfhece.MulticriteriAnalysis.Variable(variable: numpy.ma.MaskedArray | numpy.ndarray | wolfhece.wolf_array.WolfArray, dtype: 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.

_variable: numpy.ma.MaskedArray = None

_dtype

property variable: numpy.ma.MaskedArray

Return the variable.

Returns:

The variable as a numpy masked array.

property dtype: type

Return the data type of the variable.

Returns:

The data type of the variable.

class wolfhece.MulticriteriAnalysis.Criteria(threshold: float | int | tuple, condition: Literal[Operator, Operator, Operator, Operator, Operator, Operator, Operator, Operator] = Operator.SUPERIOR_OR_EQUAL.value)

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).

_available_conditions

_needs_tuple

_criteria: dict

property threshold: float

Get the threshold of the criteria.

Returns:

The threshold as a float.

property condition: str

Get the condition.

Returns:

The condition as a string.

property criteria: dict

Return the criteria.

Returns:

The criteria as a dictionary.

_number_to_tuple(value: float | int) → tuple

Convert a number to a tuple of two elements.

Parameters:

value – The number to convert.

Returns:

A tuple with the number as both elements.

_tuple_to_number(value: tuple) → float

Convert a tuple of two elements to a number.

Parameters:

value – The tuple to convert.

Returns:

The first element of the tuple as a float.

class wolfhece.MulticriteriAnalysis.Score(variable: Variable, criteria: Criteria, dtype=Format.INT32.value)

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 boolean 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.

_variable = None

property variable: Variable

Get the variable.

Returns:

The variable as a Variable object.

_criteria = None

property criteria: Criteria

Get the criteria.

Returns:

The criteria as a Criteria object.

_score: numpy.ma.MaskedArray = None

_dtype = None

property dtype: type

Get the data type of the score.

Returns:

The data type of the score.

property score: numpy.ma.MaskedArray

Get the score.

Returns:

The score as a numpy masked array.

_compute_score()

Compute the score based on the variable and criteria.

Returns:

The score as a numpy masked array.

class wolfhece.MulticriteriAnalysis.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.

_scores: dict[str, Score] = None

property scores: dict[str, Score]

Get the scores.

Returns:

The scores as a dictionary of Score objects.

property number: int

Get the number of scores.

Returns:

The number of scores in the dictionary.

add_score(name: str, score: Score) → None

Add a score to the scores dictionary.

Parameters:

• name – The name of the score.

• score – The Score object to add.

get_score(name: str) → Score

Get a score by its name.

Parameters:

name – The name of the score to get.

Returns:

The Score object with the given name.

remove_score(name: str) → None

Remove a score by its name.

Parameters:

name – The name of the score to remove.

class wolfhece.MulticriteriAnalysis.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.

_scores = None

_int_type = None

_float_type = None

_weight = None

property scores: Scores

Get the Scores object.

Returns:

The Scores object.

property int_type: str

Get the integer data type used in the operations.

Returns:

The integer data type as a string.

property float_type: str

Get the float data type used in the operations.

Returns:

The float data type as a string.

property weight: dict

Get the weight dictionary.

Returns:

The weight dictionary.

_available_operations

sum() → numpy.ma.MaskedArray

Sum all scores in the Scores object.

Returns:

The sum of all scores as a numpy masked array.

product() → numpy.ma.MaskedArray

Calculate the product of all scores in the Scores object.

Returns:

The product of all scores as a numpy masked array.

weighted_sum() → numpy.ma.MaskedArray

Calculate the weighted sum of all scores in the Scores object.

Returns:

The weighted sum of all scores as a numpy masked array.

average() → numpy.ma.MaskedArray

Calculate the average of all scores in the Scores object.

Returns:

The average of all scores as a numpy masked array.

percentage() → numpy.ma.MaskedArray

Calculate the percentage of each score in the Scores object.

Returns:

The percentage of each score as a numpy masked array.

apply_operation(operation: Literal[Operator, Operator, Operator, Operator, Operator]) → numpy.ma.MaskedArray

Select an operation to perform on the scores.

Parameters:

operation – The operation to perform.

Returns:

The result of the operation as a numpy masked array.

class wolfhece.MulticriteriAnalysis.Results(operations: Operations, mold: wolfhece.wolf_array.WolfArray = None, method: Literal[Operator, Operator, Operator, Operator, Operator] = Operator.SUM.value)

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.

_operations = None

_mold = None

_method = None

property operations: Operations

Get the Operations object.

Returns:

The Operations object.

property mold: wolfhece.wolf_array.WolfArray

Get the mold used for the results.

Returns:

The mold as a WolfArray.

property method: str

Get the method used for the results.

Returns:

The method as a string.

property header: wolfhece.wolf_array.header_wolf

Get the header of the mold.

Returns:

The header of the mold as a header_wolf object.

property as_numpy_array: numpy.ma.MaskedArray

property as_WolfArray: wolfhece.wolf_array.WolfArray

Get the results as a WolfArray.

Returns:

The results as a WolfArray.

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.

Parameters:

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

create_WolfArray(dtype=None) → wolfhece.wolf_array.WolfArray

Create an empty WolfArray with the given name, and header.

Parameters:

dtype (Union[type, str]) – The data type of the WolfArray, defaults to np.float32.

Returns:

An empty WolfArray with the given name and header.

Return type:

WolfArray

as_results(results: numpy.ma.MaskedArray, EPSG: int = 31370, dtype: type | str = None, write_to: pathlib.Path | str = None) → wolfhece.wolf_array.WolfArray

Write the results to a WolfArray file.

Parameters:

• output_path – The path to write the results to.

• name – The name of the results file.

• header – The header for the WolfArray.

• dtype – The data type of the WolfArray.

class wolfhece.MulticriteriAnalysis.Input(name: str, array: numpy.ma.MaskedArray | numpy.ndarray | wolfhece.wolf_array.WolfArray, condition: Literal[Operator, Operator, Operator, Operator, Operator] = Operator.SUPERIOR_OR_EQUAL.value, threshold: float | int = 0.0)

This class stores the inputs of the MultiCriteriaAnalysis.

Also, it ensures that the inputs are valid and consistent to feed the MulticriteriAnalysis tool.

_name = None

_array = None

_condition = None

_threshold = None

_score = None

property name: str

Get the name of the input.

Returns:

The name of the input.

property array: numpy.ma.MaskedArray | numpy.ndarray | wolfhece.wolf_array.WolfArray

Get the array of the input.

Returns:

The array as a numpy masked array.

property condition: Literal[Operator, Operator, Operator, Operator, Operator]

Get the condition of the input.

Returns:

The condition as a string.

property threshold: float | int

Get the threshold of the input.

Returns:

The threshold as a float or an int.

property score: Score

Get the score of the input.

Returns:

The score as a Score object.

class wolfhece.MulticriteriAnalysis.MulticriteriAnalysis(inputs: list[Input] | tuple[Input] | Input, method: Literal[Operator, Operator, Operator] = Operator.PERCENTAGE.value, dtype: type | str = Format.FLOAT32.value, mold: wolfhece.wolf_array.WolfArray = None, write_to: 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.

_inputs: list[Input] = None

_method: str = None

_dtype: type | str = None

_mold: wolfhece.wolf_array.WolfArray = None

_path: pathlib.Path | str = None

_EPSG: int = None

property inputs: list[Input]

Get the inputs of the MultiCriteriaAnalysis.

Returns:

The inputs as a list of Input objects.

property method: Literal[Operator, Operator, Operator]

Get the method used for the MultiCriteriaAnalysis.

Returns:

The method as a string.

property dtype: type | str

Get the data type used for the MultiCriteriaAnalysis.

Returns:

The data type as a string or a numpy dtype.

property mold: wolfhece.wolf_array.WolfArray

Get the mold used for the MultiCriteriaAnalysis.

Returns:

The mold as a WolfArray.

property path: pathlib.Path | str

Get the path where the results will be written.

Returns:

The path as a string or a Path object.

property EPSG: int

Get the EPSG code for the results.

Returns:

The EPSG code as an integer.

property number_of_inputs: int

Get the number of inputs.

Returns:

The number of inputs.

property scores: Scores

Get the scores for each input.

Returns:

The scores as a Scores object.

property operations: Operations

Get the operations to be performed on the scores.

Returns:

The Operations object.

property results: wolfhece.wolf_array.WolfArray

Perform the MultiCriteria Analysis on the inputs.

Returns:

The results of the analysis as a Results object.

write_result() → wolfhece.wolf_array.WolfArray

Write the results to a WolfArray file.

Returns:

The results as a WolfArray.