fechner {fechner}

Main Function For Fechnerian Scaling

Description

fechner provides the Fechnerian scaling computations. It is the main function of this package.

Usage

fechner(X, format = c("probability.different", "percent.same", "general"),
        compute.all = FALSE, check.computation = FALSE)

Arguments

X

a required square matrix or data frame of numeric data. No NA, NaN, Inf, or -Inf values are allowed.

format

an optional character string giving the data format that is used. This must be one of "probability.different", "percent.same", or "general", with default "probability.different", and may be abbreviated to a unique prefix.

compute.all

an optional logical. The default value FALSE corresponds to short computation, which yields the main Fechnerian scaling computations. The value TRUE corresponds to long computation, which additionally yields intermediate results and also allows for a check of computations if check.computation is set TRUE.

check.computation

an optional logical. If TRUE, the check for whether the overall Fechnerian distance of the first kind (in the first observation area) is equal to the overall Fechnerian distance of the second kind (in the second observation area) is performed. The check requires compute.all to be set TRUE.

Details

The format argument specifies the data format that is used. "probability.different" and "percent.same" are for datasets in the probability-different and percent-same formats, and in the latter case, the data are automatically transformed prior to the analysis using the transformation (100 - X) / 100. "general" is to be used for datasets that are properly in the general data format. Note that for "percent.same", the data must satisfy regular maximality, for "probability.different" and "general", regular minimality (otherwise function fechner produces respective messages). In particular, data in the general format may possibly need to be transformed manually prior to calling the function fechner.

If compute.all = TRUE and check.computation = TRUE, the performed check computes the difference ‘overall Fechnerian distance of the first kind minus overall Fechnerian distance of the second kind’. By theory, this difference is zero. The function fechner calculates that difference and checks for equality of these Fechnerian distances up to machine precision (see ‘Value’). fechner calls check.regular, which in turn calls check.data. In particular, the specified data format and regular minimality/maximality are checked, and the rows and columns of the canonical representation matrix (see check.regular) are canonically relabeled based on the labeling provided by check.data.

The function fechner returns an object of the class fechner (see ‘Value’), for which plot, print, and summary methods are provided; plot.fechner, print.fechner, and summary.fechner, respectively. Moreover, objects of the class fechner are set the specific named attribute computation, which is assumed to have the value short or long indicating whether short computation (compute.all = FALSE) or long computation (compute.all = TRUE) was performed, respectively.

Value

If the arguments X, format, compute.all, and check.computation are of required types, fechner returns a named list, of the class fechner and with the attribute computation, which consists of 6 or 18 components, depending on whether short computation (computation is then set short) or long computation (computation is then set long) was performed, respectively.

The short computation list contains the following first 6 components, the long computation list the subsequent ones:

points.of.subjective.equality

a data frame giving the permutation of the columns of X used to produce the canonical representation of X. The first and second variables of this data frame, observation.area.1 and observation.area.2, respectively, represent the pairs of points of subjective equality (PSEs). The third variable, common.label, lists the identical labels assigned to the pairs of PSEs. (first component of short computation list)

canonical.representation

a matrix giving the representation of X in which regular minimality/maximality is satisfied in the canonical form. That is, the single minimal/maximal entries of the rows and columns lie on the main diagonal (of the canonical representation). In addition, the rows and columns are canonically relabeled.

overall.Fechnerian.distances

a matrix of the overall Fechnerian distances (of the first kind); by theory, invariant from observation area.

geodesic.loops

a data frame of the geodesic loops of the first kind; must be read from left to right for the first kind, and from right to left for the second kind.

graph.lengths.of.geodesic.loops

a matrix of the graph-theoretic (edge/link based) lengths of the geodesic loops (of the first kind).

S.index

a matrix of the generalized ‘Shepardian’ dissimilarity (or S-index) values. An S-index value is defined as the psychometric length of the loop between a row stimulus and a column stimulus containing only these two stimuli. (last component of short computation list)

points.of.subjective.equality

the same as in case of short computation; see above. (first component of long computation list)

canonical.representation

the same as in case of short computation; see above.

psychometric.increments.1

a matrix of the psychometric increments of the first kind.

psychometric.increments.2

a matrix of the psychometric increments of the second kind.

oriented.Fechnerian.distances.1

a matrix of the oriented Fechnerian distances of the first kind.

overall.Fechnerian.distances.1

a matrix of the overall Fechnerian distances of the first kind.

oriented.Fechnerian.distances.2

a matrix of the oriented Fechnerian distances of the second kind.

overall.Fechnerian.distances.2

a matrix of the overall Fechnerian distances of the second kind.

check

if check.computation = TRUE, a list of two components: difference and are.nearly.equal. The component difference is a matrix of the differences of the overall Fechnerian distances of the first and second kind; ought to be a zero matrix. The component are.nearly.equal is a logical indicating whether this matrix of differences is equal to the zero matrix up to machine precision. If check.computation = FALSE, a character string saying “computation check was not requested”.

geodesic.chains.1

a data frame of the geodesic chains of the first kind.

geodesic.loops.1

a data frame of the geodesic loops of the first kind.

graph.lengths.of.geodesic.chains.1

a matrix of the graph-theoretic (edge/link based) lengths of the geodesic chains of the first kind.

graph.lengths.of.geodesic.loops.1

a matrix of the graph-theoretic (edge/link based) lengths of the geodesic loops of the first kind.

geodesic.chains.2

a data frame of the geodesic chains of the second kind.

geodesic.loops.2

a data frame of the geodesic loops of the second kind.

graph.lengths.of.geodesic.chains.2

a matrix of the graph-theoretic (edge/link based) lengths of the geodesic chains of the second kind.

graph.lengths.of.geodesic.loops.2

a matrix of the graph-theoretic (edge/link based) lengths of the geodesic loops of the second kind.

S.index

the same as in case of short computation; see above. (last component of long computation list)

Author(s)

Thomas Kiefer, Ali Uenlue. Based on original MATLAB source by Ehtibar N. Dzhafarov.

References

Dzhafarov, E. N. and Colonius, H. (2006) Reconstructing distances among objects from their discriminability. Psychometrika, 71, 365–386.

Dzhafarov, E. N. and Colonius, H. (2007) Dissimilarity cumulation theory and subjective metrics. Journal of Mathematical Psychology, 51, 290–304.

Uenlue, A. and Kiefer, T. and Dzhafarov, E. N. (2009) Fechnerian scaling in R: The package fechner. Journal of Statistical Software, 31(6), 1–24. URL http://www.jstatsoft.org/v31/i06/.

See Also

check.data for checking data format; check.regular for checking regular minimality/maximality; plot.fechner, the S3 method for plotting objects of the class fechner; print.fechner, the S3 method for printing objects of the class fechner; summary.fechner, the S3 method for summarizing objects of the class fechner, which creates objects of the class summary.fechner; print.summary.fechner, the S3 method for printing objects of the class summary.fechner. See also fechner-package for general information about this package.

Examples

##
## (1) examples based on dataset \link{morse}
##

## dataset \link{morse} satisfies regular maximality in canonical form
morse
check.regular(morse, type = "percent.same")

## a self-contained 10-code subspace consisting of the codes for the
## letter B and the digits 0, 1, 2, 4, \ldots, 9
indices <- which(is.element(names(morse), c("B", c(0, 1, 2, 4:9))))
f.scal.morse <- fechner(morse, format = "percent.same")
f.scal.morse$geodesic.loops[indices, indices]
morse.subspace <- morse[indices, indices]
check.regular(morse.subspace, type = "percent.same")

## since the subspace is self-contained, results must be the same
f.scal.subspace.mo <- fechner(morse.subspace, format = "percent.same")
identical(f.scal.morse$geodesic.loops[indices, indices],
          f.scal.subspace.mo$geodesic.loops)
identical(f.scal.morse$overall.Fechnerian.distances[indices, indices],
          f.scal.subspace.mo$overall.Fechnerian.distances)

## Fechnerian scaling analysis using short computation
f.scal.subspace.mo
str(f.scal.subspace.mo)
attributes(f.scal.subspace.mo)
## for instance, the S-index
f.scal.subspace.mo$S.index

## Fechnerian scaling analysis using long computation
f.scal.subspace.long.mo <- fechner(morse.subspace,
                                   format = "percent.same",
                                   compute.all = TRUE,
                                   check.computation = TRUE)
f.scal.subspace.long.mo
str(f.scal.subspace.long.mo)
attributes(f.scal.subspace.long.mo)
## for instance, the geodesic chains of the first kind
f.scal.subspace.long.mo$geodesic.chains.1

## check whether the overall Fechnerian distance of the first kind is
## equal to the overall Fechnerian distance of the second kind
## the difference, by theory a zero matrix
f.scal.subspace.long.mo$check[1]
## or, up to machine precision
f.scal.subspace.long.mo$check[2]

## plot of the S-index versus the overall Fechnerian distance
## for all (off-diagonal) pairs of stimuli
plot(f.scal.subspace.long.mo)
## for all (off-diagonal) pairs of stimuli with geodesic loops
## containing at least 3 links
plot(f.scal.subspace.long.mo, level = 3)

## corresponding summaries, including Pearson correlation and C-index
summary(f.scal.subspace.long.mo)
## in particular, accessing detailed summary through assignment
detailed.summary.mo <- summary(f.scal.subspace.long.mo, level = 3)
str(detailed.summary.mo)

##
## (2) examples based on dataset \link{wish}
##

## dataset \link{wish} satisfies regular minimality in canonical form
wish
check.regular(wish, type = "probability.different")

## a self-contained 10-code subspace consisting of S, U, W, X,
## 0, 1, \ldots, 5
indices <- which(is.element(names(wish), c("S", "U", "W", "X", 0:5)))
f.scal.wish <- fechner(wish, format = "probability.different")
f.scal.wish$geodesic.loops[indices, indices]
wish.subspace <- wish[indices, indices]
check.regular(wish.subspace, type = "probability.different")

## since the subspace is self-contained, results must be the same
f.scal.subspace.wi <- fechner(wish.subspace,
                              format = "probability.different")
identical(f.scal.wish$geodesic.loops[indices, indices],
          f.scal.subspace.wi$geodesic.loops)
identical(f.scal.wish$overall.Fechnerian.distances[indices, indices],
          f.scal.subspace.wi$overall.Fechnerian.distances)

## dataset \link{wish} transformed to percent-same format
check.data(100 - (wish * 100), format = "percent.same")

## Fechnerian scaling analysis using short computation
f.scal.subspace.wi
str(f.scal.subspace.wi)
attributes(f.scal.subspace.wi)
## for instance, the graph-theoretic lengths of geodesic loops
f.scal.subspace.wi$graph.lengths.of.geodesic.loops

## Fechnerian scaling analysis using long computation
f.scal.subspace.long.wi <- fechner(wish.subspace,
                                   format = "probability.different",
                                   compute.all = TRUE,
                                   check.computation = TRUE)
f.scal.subspace.long.wi
str(f.scal.subspace.long.wi)
attributes(f.scal.subspace.long.wi)
## for instance, the oriented Fechnerian distances of the first kind
f.scal.subspace.long.wi$oriented.Fechnerian.distances.1
## or, graph-theoretic lengths of chains and loops
identical(f.scal.subspace.long.wi$graph.lengths.of.geodesic.chains.1 +
          t(f.scal.subspace.long.wi$graph.lengths.of.geodesic.chains.1),
          f.scal.subspace.long.wi$graph.lengths.of.geodesic.loops.1)

## overall Fechnerian distances are not monotonically related to
## discrimination probabilities; however, there is a strong positive
## correlation
cor(as.vector(f.scal.wish$overall.Fechnerian.distances),
    as.vector(as.matrix(wish)))

## check whether the overall Fechnerian distance of the first kind is
## equal to the overall Fechnerian distance of the second kind
## the difference, by theory a zero matrix
f.scal.subspace.long.wi$check[1]
## or, up to machine precision
f.scal.subspace.long.wi$check[2]

## plot of the S-index versus the overall Fechnerian distance
## for all (off-diagonal) pairs of stimuli
plot(f.scal.subspace.long.wi)
## for all (off-diagonal) pairs of stimuli with geodesic loops
## containing at least 5 links
plot(f.scal.subspace.long.wi, level = 5)

## corresponding summaries, including Pearson correlation and C-index
summary(f.scal.subspace.long.wi)
## in particular, accessing detailed summary through assignment
detailed.summary.wi <- summary(f.scal.subspace.long.wi, level = 5)
str(detailed.summary.wi)