fechner {fechner} | R Documentation |
fechner
provides the Fechnerian scaling computations. It is
the main function of this package.
fechner(X, format = c("probability.different", "percent.same", "general"), compute.all = FALSE, check.computation = FALSE)
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 . |
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.
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) |
Thomas Kiefer thomas.kiefer@student.uni-augsburg.de, Ali Uenlue ali.uenlue@math.uni-augsburg.de. Based on original MATLAB source by Ehtibar N. Dzhafarov.
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/.
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.
## ## (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)