UTAR Manual

8/3/2019 UTAR Manual

1/33

Package UTAR

June 3, 2011

Version 1.3.0

Date 2011-06-03

Title UTAR library for MCDA

Author Boris Leistedt

Maintainer Boris Leistedt

Description UTAR is a R library specifically designed for the

construction and the learning of UTA models in MultiCriteria

Decision Aid (MCDA). The main features are: data extraction,model initialization, selec-

tion strategies and supervized

learning, model assessment in terms of functions and relations,data layout and output.

Depends R(>= 2.1.0), RXMCDA, XML, lpSolve, LowRankQP

Suggests MASS, linprog

Encoding latin1

License CeCILL 2 (GNU GPL 2 compatible)

URL http://github.com/ixkael/RMCDA

R topics documented:

alreadyDone . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

a n a l y t i c C e n t e r . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

analyticCenterInitialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

buildUmatrix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4checkEasyPair . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

comparerankings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

computeAlternativesIndicator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

computebound . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

computeEmptyUTASTARmatrices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

computeequation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

c o mp u te N e c e s s a ry R e la tio n . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

computeNormalizedPerformanceTable . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

computePostOptimalityAnalysis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

c o m p u t e r a n k i n g . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

computeUTASTAR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

1
http://github.com/ixkael/RMCDAhttp://github.com/ixkael/RMCDA


2/33

2 R topics documented:

computeUTASTARmatrices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

c o mp u te U til i t ie s In d ic a to r . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

computeUtilitiesIndicator_weights . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

constructGmatrix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12countNbDiffAlternatives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

exportLog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

exportSituation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

extractContent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

e x t r a c t S u b s e t s . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

fast.svd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

fi n d A n d C h e c k . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

findcprofile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

g e n e ra te E a s y L e a rn in g Se t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

g e n e ra te R a n d o mA lte rn a tiv e s . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

generateStandardAlternatives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

g e n e r a t e U t i l i t i e s . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

g e n e r a t e Y p r o fi l e F r o m X . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

getPreferencesDirections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

getRanking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

getValueFunctions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

initializeModel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

i n v e r t p r o fi l e . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

meanValue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

nextpair_random . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

nextpair_relationoriented . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23nextpair_visionary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

nextpair_volumeoriented . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

nullspace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

performanceTableToXML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

positive.svd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

p ro d u c e O rie n te d Se g me n t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

pseudoinverse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

psmall.svd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

restrictAllFilesToCorrectAlternatives . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

restrictAllFilesToCorrectCriteria . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

restrictPerformanceTable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29saveUtilityFunctionUnderXML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

scanInputsFolder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

solveUTASTAR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

updateLearningSet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

updateModel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

utamp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

Index 33


3/33

alreadyDone 3

alreadyDone alreadyDone

Description

Checks if a doublet has already been added to a two-column matrix.

Usage

out


4/33

4 buildUmatrix

analyticCenterInitialization

Initializes the analytic center

Description

Initializes the analytic center. This method is included into the analyticCenter() function.

Usage

xout


5/33

checkEasyPair 5

checkEasyPair Checks easy pair

Description

Checks an easy pair (x,y) by performing various tests on its structure. y is assumed to be generated

from x.

Usage

out


6/33

6 computebound

Arguments

ranking1 A first ranking, i.e. a two-column matrix containing alternatives and their rank

ranking1 Another ranking, i.e. a two-column matrix containing alternatives and their rank

Value

An integer

computeAlternativesIndicator

Computes alternatives indicator

Description

Computes the necessary relation induced by the model

Usage

value


7/33

computeEmptyUTASTARmatrices 7

computeEmptyUTASTARmatrices

Computes empty UTASTAR matrices

Description

Computes the linear programming system corresponding the an empty UTA model

Usage

out


8/33

8 computeNormalizedPerformanceTable

computeNecessaryRelation

Computes the necessary relation

Description

Computes the necessary relation of a model on A.

Usage

out


9/33

computePostOptimalityAnalysis 9

computePostOptimalityAnalysis

Computes post-optimality analysis

Description

Computes the post-optimality analysis from a given solution (interior point of the constraints poly-

hedron) for UTA models. The three available methods are Analytic center, UTASTAR, and UTAMP.

Usage

xout


10/33

10 computeUTASTARmatrices

Value

A ranking, under the form of a two-column matrix

computeUTASTAR Computes UTASTAR disaggregation method

Description

Meta-method to compute and solve the UTA linear programming problem.

Usage

out


11/33

computeUtilitiesIndicator 11

Arguments

performanceTable

Classical performanceTable according to MCDA standard

ranking Total order of a subset of alternatives

delta Utility gap between two alternatives for which one was declared to be preferred

to the other

prefPairs Pairs of alternatives, involved in preference statements

indiffPairs Pairs of alternatives, involved in indifference statements

prefDirections

Vector : number of segments in each value function

Value

A list structured as follows:

c Vector : objective constraints function

A Matrix : inequality constraints matrix

b Vector : inequality constraints right-member

Aeq Matrix : equality constraints matrix

beq Vector : inequality constraints right-member

computeUtilitiesIndicator

computeUtilitiesIndicator

Description

Computes and aggregates (product) the bounds of all variables of the model.

Usage

value


12/33

12 constructGmatrix

computeUtilitiesIndicator_weights

computeUtilitiesIndicator_weights

Description

Computes and aggregates (product) the bounds of trade-off weights variables of the model.

Usage

value


13/33

countNbDiffAlternatives 13

countNbDiffAlternatives

Counts the number of different alternatives

Description

Counts the number of different alternatives in a doublet preference relation / indifference relation.

Usage

n


14/33

14 extractContent

exportSituation Exports value functions to XMCDA file

Description

Exports the constructed value functions (created by function saveUtilityFunctionUnderXML)

into XML file according to XMCDA standard.

Usage

exportSituation( solution, outputsLocation )

Arguments

solution List containing at least two matrices named "umatrix" and "gmatrix" that are the

standard outputs for utility and value functions.

outputsLocation

Where you want the XML file to be saved

Value

No output (except the XML file)

extractContent Extracts Content

Description

Extracts and checks content from an XML tree (generic function).

Usage

out


15/33

extractSubsets 15

extractSubsets Constructs combinatory subsets

Description

Constructs combinatory subsets (n-wise permutations).

Usage

out nA

n 1


16/33

16 findcprofile

findAndCheck Finds and checks XML inputs and content

Description

Finds and checks XML inputs and content in the inputsDirectory.

Usage

out


17/33

generateEasyLearningSet 17

generateEasyLearningSet

Generates a set of easy pairs

Description

Generates a set of easy pairs from a model M an its internal data.

Usage

L


18/33

18 generateUtilities

generateStandardAlternatives

Generates a regular grid of alternatives

Description

Generates a regular grid of alternatives in [0,1].

Usage

out


19/33

generateYprofileFromX 19

generateYprofileFromX

Generates Y profile from X and U

Description

Generates a profile cy for alternative Y from the profile of X.

Usage

out


20/33

20 getValueFunctions

Value


status Validation tag ("OK" execution was successful)

Vector or matrix containing the directions and the criteria names

getRanking Computes analytic center ranking

Description

Computes the ranking corresponding to the analytic center of the manipulated polyhedron.

Usage

out


21/33

initializeModel 21

Value

The function returns a list structured as follows:

gmatrix Matrix containing the abscissa for the breakpoints of the constructed value func-tions

umatrix Matrix containing the ordinates for the breakpoints of the constructed value

functions

status Either OK or error status

initializeModel Initializes an empty UTA model

Description

Initializes an empty UTA model

Usage

out


22/33

22 meanValue

necess The necessary relation induced on A by the empty model

A Matrix : inequality constraints matrix

b Vector : inequality constraints right-member

A Matrix : equality constraints matrix

b Vector : equality constraints right-member

invertprofile Inverts c profile

Description

Inverts the c profile (in the utilities space) and gets the equivalent alternative. Dual method of

findcprofile.

Usage

alt


23/33

nextpair_random 23

Value


x The solution (vectorized value function)validation Success or failure tag

LOG Log information

nextpair_random Random selection method

Description

Randomly selects the next pair in the set of possible questions

Usage

out


24/33

24 nextpair_volumeoriented

Value


pos Row number of the selected pair in L

pair Selected pair, i.e. concatenation of the evaluation profiles

nextpair_visionary Visionary learning strategy

Description

Selects the next pair in the set of possible questions using the visionary method (oracle).

Usage

out


25/33

nullspace 25

Arguments

L Set of possible questions/pairs, where each row corresponds to a pair of alterna-

tives and is the concatenation of their evaluation profiles.

M A model properly initialized and enriched with the other functions of UTAR

Value


pos Row number of the selected pair in L

pair Selected pair, i.e. concatenation of the evaluation profiles

nullspace Computes the nullspace

Description

Computes the nullspace of a matrix

Usage

out


26/33

26 produceOrientedSegment

positive.svd Positive singular values decomposition

Description

Positive singular value decomposition

Usage

out


27/33

pseudoinverse 27

pseudoinverse Computes pseudoinverse

Description

Computes pseudoinverse of a matrix

Usage

out


28/33

28 restrictAllFilesToCorrectCriteria

restrictAllFilesToCorrectAlternatives

Restricts and combines content to correct alternatives

Description

From all the initial data, computes the correct content, restricted to the selected alternatives.

Usage

updatedcontent


29/33

restrictPerformanceTable 29

restrictPerformanceTable

Restricts and combines content to correct performance table

Description

From all the initial data, computes the correct performance table, restricted to the selected alterna-

tives and criteria.

Usage

updatedcontent


30/33

30 solveUTASTAR

scanInputsFolder Detects input files and analyses it

Description

Scans input directory, detects and analyse inputs of given name ("alternatives.xml" , "alternatives-

Ranking.xml" , "alternativesPreferences.xml" , "alternativesIndifferences.xml" , "criteria.xml" ,

"delta.xml" , "segments.xml" , "preferencesDirections.xml" , "performanceTable.xml" , "method.xml").

Usage

out


31/33

updateLearningSet 31

Value


x The solution (Vectorized value function)

validation Success or failure flage

LOG Log information

updateLearningSet Updates learning set

Description

Updates the set of possible questions by removing the previously asked question and the sure state-

ments arising from the updated necessary relation on A.

Usage

out


32/33

32 utamp

Arguments

M UTA model, correctly initialized

nextpair The nextpair, obtained from a selection procedure (concatenation of two evalu-

ation profiles)

U The decision makers value function, in order to obtain his judgement on the

next pair

Value

Updated model

utamp Computes "Utamp" post-optimality analysis

Description

Utamp is a post-optimality method taking a set of constraints and finding the compatible value

functions that maximize the gap between two alternatives (where one is declared to be preferred to

the other)

Usage

out


33/33

Index

alreadyDone, 3

analyticCenter, 3

analyticCenterInitialization , 4

buildUmatrix, 4

checkEasyPair, 5

comparerankings, 5computeAlternativesIndicator , 6

computebound, 6

computeEmptyUTASTARmatrices , 7

computeequation, 7

computeNecessaryRelation , 8

computeNormalizedPerformanceTable ,

8

computePostOptimalityAnalysis , 9

computeranking, 9

computeUTASTAR, 10

computeUTASTARmatrices, 10

computeUtilitiesIndicator , 11

computeUtilitiesIndicator_weights ,12

constructGmatrix, 12

countNbDiffAlternatives, 13

exportLog, 13

exportSituation, 14

extractContent, 14

extractSubsets, 15

fast.svd, 15

findAndCheck, 16

findcprofile, 16

generateEasyLearningSet, 17

generateRandomAlternatives , 17

generateStandardAlternatives , 18

generateUtilities, 18

generateYprofileFromX, 19

getPreferencesDirections , 19

getRanking, 20

getValueFunctions, 20

initializeModel, 21

invertprofile, 22

meanValue, 22

nextpair_random, 23

nextpair_relationoriented , 23

nextpair_visionary, 24

nextpair_volumeoriented, 24

nullspace, 25

performanceTableToXML, 25

positive.svd, 26

produceOrientedSegment, 26

pseudoinverse, 27

psmall.svd, 27

restrictAllFilesToCorrectAlternatives ,

28

restrictAllFilesToCorrectCriteria ,

28

restrictPerformanceTable , 29

saveUtilityFunctionUnderXML , 29scanInputsFolder, 30

solveUTASTAR, 30

updateLearningSet, 31

updateModel, 31

utamp, 32

33

UTAR Manual

Documents

Transcript of UTAR Manual