scoring-matrix()
This function is deprecated.
Returns a scoring decision based on a CSV matrix.
The goal might be to find the cheapest out of a list of service providers, depending on specific parameter values. As a practical example, you could search for the best forwarding agent for a specific shipping item, depending on the specific properties of this item (necessary refrigeration, weight, express shipping, …).
The overall decision can be a combination of several individual decisions, whereby every single decision is assigned to a function parameter (starting with c). Every single decision returns a non-negative value for each service provider. These values are multiplied and deliver an overall scoring value for each service provider.
The service provider with the highest scoring wins. Its name or key value, which is the first column of the matrix, is the result of the function call.
If none of the service providers achieves a score > 0, the result will be empty.
Brief scoring example
Four forwarding agents ("Fa1", "Fa2", "Fa3", "Fa4") provide transport services. There are various features.
|
R |
Refrigerated transport possible. |
|
E |
Delivery to other European countries. |
|
D |
Guaranteed delivery in 8, 24, 48 hours or without guarantee. Coded as "D08", "D24", "D48", "DSTD". |
To find the most favourable price for a delivery (cheapest forwarding agent), we have to define the requirements for a piece of cargo, i.e. as function parameters c, d, and e.
|
c |
Cooling necessary, boolean ("false"/"true"). |
|
d |
Recipient is abroad, boolean ("false"/"true"). |
|
e |
Speed requirements, string with possible values "D08", "D24", "D48", "DSTD". |
There are 3 single decisions to be made with the help of parameters c, d, and e.
The two Boolean parameters c and d each have two possible values, true or false. Parameter e has 4 possible values. For each of these values, we have to give every forwarding agent a rating. We portray that information in a matrix.
|
Forwarding agent |
R.false |
R.true |
E.false |
E.true |
D08 |
D24 |
D48 |
DSTD |
|
Fa1 |
1 |
1 |
1 |
1 |
0 |
2 |
1 |
1 |
|
Fa2 |
1 |
0 |
1 |
2 |
0 |
0 |
1 |
1 |
|
Fa3 |
1 |
0 |
1 |
0 |
1 |
1 |
0 |
1 |
|
Fa4 |
0 |
2 |
1 |
0 |
1 |
1 |
0 |
1 |
"Fa1" provides cooled and uncooled transports. "Fa4" only provides cooled transports, at a better price than "Fa1". "Fa2" and "Fa3" cannot provide cooled transports at all.
All forwarding agents deliver domestically, "Fa1" and "Fa2" also deliver abroad, whereby "Fa2" has a better price for deliveries abroad.
Analogously for the delivery speed: All forwarding agents provide "DSTD", etc…
Decision c (cooling) is portrayed in column group 2, 3. Decision d (delivery abroad) in 4 + 5 and e (delivery speed) in column group 6, 7, 8, 9.
If we are looking for a forwarding agent that delivers cooled cargo abroad within 24 hours, we have to consider columns 3, 5, 7. The corresponding values are multiplied and thereby deliver an overall score. At the first occurrence of a "0", the scoring for this forwarding agent is aborted. Only "Fa1" fulfils all requirements.
|
Forwarding agent |
R.false |
R.true |
E.false |
E.true |
D08 |
D24 |
D48 |
DSTD |
Score |
|
|
Fa1 |
1 |
1 |
1 |
1 |
0 |
2 |
1 |
1 |
2 |
|
|
Fa2 |
1 |
0 |
1 |
2 |
0 |
0 |
1 |
1 |
0 |
|
|
Fa3 |
1 |
0 |
1 |
0 |
1 |
1 |
0 |
1 |
0 |
|
|
Fa4 |
0 |
2 |
1 |
0 |
1 |
1 |
0 |
1 |
0 |
|
Now, we want to domestically deliver uncooled cargo within 24 hours.
|
Forwarding agent |
R.false |
R.true |
E.false |
E.true |
D08 |
D24 |
D48 |
DSTD |
Score |
|
Fa1 |
1 |
1 |
1 |
1 |
0 |
2 |
1 |
1 |
2 |
|
Fa2 |
1 |
0 |
1 |
2 |
0 |
0 |
1 |
1 |
0 |
|
Fa3 |
1 |
0 |
1 |
0 |
1 |
1 |
0 |
1 |
1 |
|
Fa4 |
0 |
2 |
1 |
0 |
1 |
1 |
0 |
1 |
0 |
"Fa2" and "Fa4" cannot provide one of the requirements. That leaves us with "Fa1" and "Fa3". "Fa3" wins because it provides better conditions for "D24".
Methods (parameter "b")
Parameter b determines the function of the function. Currently, values "max" and "col" are supported. Default: "max".
Method "max" corresponds to the normal function: The result is the service provider (forwarding agent) with the highest scoring or an empty value if none of the service providers fits.
Method "col" was developed for debugging and error messages. The result is a listing of those matrix columns that are used for the scoring. In the example above, the result is [3,5,7].
Structure of the function configuration file
The configuration file (file path in parameter a) can be a CSV file or an Excel file (xls or xslx).
In the case of an Excel file with several tabs, the tab can specifically be set. The first tab is default (index=0):
|
Syntax |
directory/excel_file.xlsx?0 |
This file needs to contain the decision matrix and the group definitions. Both segments are initiated with a command line, beginning with "!/cmd/".
|
Command |
Description |
|
!/cmd/matrix |
The following lines are the lines of the decision matrix. |
|
!/cmd/conf |
The following lines are the lines of the group definitions. |
Lines that begin with "#" are comments and can be ignored.
The decision matrix
The matrix consists of CSV lines. Each line represents a forwarding agent (service provider). The fields are separated by commas. The first field contains the distinct label/key of the forwarding agent. Fields starting at position 2 correspond to the services of the forwarding agent. The numeric value in the field corresponds to the weight of the service, i.e. its value in the scoring multiplication. Negative values are not allowed. Positive integers and floating point numbers are allowed.
Value 0 means: The forwarding agent does not provide the service.
Value > 0 means: The forwarding agent provides the service.
The higher the value in a column, relative to the values of the other forwarding agents in the same matrix column, the more the corresponding forwarding agent is preferred.
Which matrix columns are used in a specific scoring of a forwarding agent depends on the configuration of the groups and the assigned parameters c to z. The scoring is calculated on the basis of one or several single decisions (partial scorings). Every single decision refers to one function parameter (starting with c). Every single decision is expressed as group of interrelated matrix columns. The correlation of groups and function parameters is set in the second part of the configuration file in the group definition.
The single decision (partial scoring) consists of the selection of the correct column within a group, dependent on the value of the function parameter that is assigned to this group. The numeric values of all forwarding agents of this column are used for the scoring. The other columns of the group are not considered.
The group definition
A group refers to several columns of a decision matrix and is assigned to a function parameter. Depending on the parameter value, exactly one of the column is selected.
Structure of a group definition line
|
group |
offset |
type |
parameter |
defEnum |
defFactor |
values… |
"offset": The second field contains the integer offset of the group. The offset is the index of the first column belonging to the group.
"type": The third field contains the type of the group.
"parameter": The fourth field contains the function parameter as the lowercase letter that is assigned to the group.
"values", "defEnum" and "defFactor": Only for type "enum": See description below.
The following types are allowed (the first letter is sufficient):
|
Type of group |
Description |
|
boolean |
Defines a logical decision. The function parameter has to be of type Boolean ("false"/"true"). This kind of group always has exactly two columns. The first corresponding (decision matrix) column is used for function parameter value "false" and the second for value "true". |
|
enum |
Defines an enumeration of possible values. The values are defined in parameter values. If the value of the assigned function parameter matches one of these values, the corresponding (decision matrix) column of the group is used. If none of the enum values is matched, "defEnum" is used as parameter value. If "defEnum" does not match any of the values, "defFactor" is used as the result. If even "defFactor" does not exist, the function execution is aborted with an exception. |
It is possible, but probably not useful, to assign several groups to a parameter.
Important note: Groups are not allowed to overlap, which means that a column of the decision matrix is not allowed to belong to two groups. This is achieved by a proper definition of all the offsets. If two groups overlap, the function call is aborted with an exception.
Configuration file for the example above
!/cmd/matrixFa1,1,1,1,1,0,2,1,1Fa2,1,0,1,2,0,0,1,1Fa3,1,0,1,0,1,1,0,1Fa4,0,2,1,0,1,1,0,1!/cmd/confgroup,2,boolean,cgroup,4,boolean,dgroup,6,enum,e,DSTD,,D08,D24,D48,DSTDPriority rule for equal scorings
It might happen that two or more forwarding agents get the same scoring. In this case, one of those has to be selected. Two main strategies are possible:
A random selection of one of the forwarding agents.
A reproducible selection.
The function uses a reproducible selection. The forwarding agent (of the highest scoring forwarding agents) that is listed first in the decision matrix is selected. If you manually want to favour one of the forwarding agents, you could modify the relevant columns from "1" to "1.0001" to achieve a slightly higher scoring.
Error cases and their avoidance
Groups are not allowed to overlap. The following group definition would be an error:
# Error: for c=true and d=false the same matrix column (index 3) is referencedgroup,2,boolean,cgroup,3,boolean,dIn this case, the function execution will be aborted with the IllegalArgumentException "conflicting groups:".
This error could be the result of an added value to an "enum" group without adding an additional column to the matrix. A "boolean" group always has two columns. The number of columns is only variable for type "enum". We recommend to define the "boolean" groups first and then the "enum" groups. If you expect an enlargement of an "enum", it makes sense to place this "enum" in the last line to avoid index shifts for the other groups. It is also possible to initially leave some columns in the group definition unused. The corresponding decision matrix columns of the unused columns can be left empty. Example:
Fa1,1,1,1,1,0,2,1,1,,,9,4Fa2,1,0,1,2,0,0,1,1,,,5,7!/cmd/confgroup,2,boolean,cgroup,4,boolean,dgroup,6,enum,e,DSTD,,DS08,DS24,DS48,DSTDgroup,12,enum,f,,,C,NThe "enum" with offset "6" only has 4 values and therefore, ends with index "9". The following "enum" begins with offset "12" and therefore, leaves out 2 columns that do not have to be filled with values in the corresponding decision matrix.
Groups are not allowed to reference a column index that is not defined in the matrix.
# Error: enum references columns that are not defined in the matrixFa1,1,1,1,1,0,2,1,1Fa2,1,0,1,2,0,0,1,1!/cmd/confgroup,2,boolean,cgroup,4,boolean,dgroup,6,enum,e,DSTD,,DS08,DS24,DS48,DSTD,DS12,N04The "enum" group defines 6 values ("DS08" to "N04") and begins with index "6". So the highest index is "11", but the matrix only has 9 columns. In this case, the function execution will be aborted with an IllegalArgumentException "illegal column index: 11".
All the values in the key column have to be unique.
The key column is used to distinctly identify the forwarding agent. The result of the function call (with method b=max) is the key of the forwarding agent with the highest score. If there are duplicate keys, the function execution will be aborted with an IllegalArgumentException "duplicate key in matrix line …".