distanceHartmann: 'Hartmann distance' (standardized Euclidean distances).
In OpenRepGrid: Tools to analyse repertory grid data

Description Usage Arguments Details Value Author(s) References See Also Examples

Hartmann (1992) showed in a Monte Carlo study that Slater distances (see distanceSlater) based on random grids, for which Slater coined the expression quasis, have a skewed distribution, a mean and a standard deviation depending on the number of constructs elicited. He suggested a linear transformation (z-transformation) which takes into account the estimated (or expected) mean and the standard deviation of the derived distribution to standardize Slater distance scores across different grid sizes. 'Hartmann distances' represent a more accurate version of 'Slater distances'. Note that Hartmann distances are multiplied by -1. Hence, negative Hartmann values represent dissimilarity, i.e. a big Slater distance.

The function distanceHartmann conducts a small Monte Carlo simulation for the supplied grid. I. e. a number of quasis of the same size and with the same scale range as the grid under investigation are generated. A distrubution of Slater distances derived from the quasis is calculated and used for Hartmann's standardization.

It is also possible to return the quantiles of the sample distribution and only the element distances consideres 'significant' according to the quantiles defined.

1
2
3

distanceHartmann(x, rep=100, meantype=2, quant=c(0.05, 0.5, 0.95),
    significant=FALSE, trim=10, indexcol=FALSE, prob,
    digits=2, output=1, progress=TRUE, upper=TRUE)

`x`	`repgrid` object.
`rep`	Number of random grids to generate to produce sample distribution for Slater distances (default is `100`). Note that a lot of samples may take a while to calculate. Set `progress = TRUE` to monitor progress for large samples.
`meantype`	The type of mean to use for standardization. `meantype=1` will use the empirical mean (which is 1 and the default) `meantype=2` will use the expected mean, i. e. 1.
`quant`	The propabities of the quantiles from the Slater distance distribution that will be returned. The default is `c(.05, .5, .95)`. This corresponds to the lower 5 %, the mean and the upper 5 % of the distribution.
`significant`	Whether to only show values that are outside the quantiles defined in `quant`, i.e. onsidered as 'significant' (default is `FALSE`.) The first and last value of `quant` is used to determine the indifference region. This options only applies when `output == 1` is used.
`trim`	The number of characters a element names are trimmed to (default is `10`). If `NA` no trimming is done. Trimming simply saves space when displaying the output.
`indexcol`	Logical. Whether to add an extra index column so the column names are indexes instead of element names. This option renders a neater output as long element names will stretch the output (default is `FALSE`). Note that the index column is the first matrix column.
`prob`	The probability of each rating value to occur. If `NULL` (default) the distribution is uniform. The number of values must match the length of the rating scale.
`digits`	Numeric. Number of digits to round to (default is `2`).
`output`	The output type. The default (`output=1`) will print the Hartmann distances, `output=2` the Slater and `output=3` both distances to the console. `output=0` will suppress the printing to the console. In all cases a list containig the results of the calculations is returned invisibly. See value for details.
`progress`	Whether to show a progress bar (default is `TRUE`). May be useful when the distribution is estimated on the basis of many quasis.
`upper`	Logical. Whether to display only upper part of the distance matrix (default `TRUE`).

The 'Hartmann distance' is calculated as follows (Hartmann 1992, p. 49).

D = -1 (D_slater - M_c / sd_c)

Where D_slater denotes the Slater distances of the grid, M_c the sample distribution's mean value and sd_c the sample distributions's standard deviation.

A matrix containing Hartmann distances (output=1 and output=2) or a list (output=3) containing:

`hartmann`	matrix of Hartmann distances
`h.quantiles`	quantiles for Hartmann distances
`h.vals`	random values of Hartmann
`h.sd`	standard deviation of distribution of Hartmann values
`slater`	matrix of Slater distances
`sl.quantiles`	quantiles for Slater distances
`sl.vals`	vector of all Slater distances
`ls.sd`	standard deviation of random Slater distances

Mark Heckmann

Hartmann, A. (1992). Element comparisons in repertory grid technique: Results and consequences of a Monte Carlo study. International Journal of Personal Construct Psychology, 5(1), 41-56.

distanceSlater

## Not run: 

distanceHartmann(bell2010)
distanceHartmann(bell2010, trim=40, index=T, sig=T)

### histogram of Slater distances and indifference region
d <- distanceHartmann(bell2010, out=0)
hist(d$sl.vals, breaks=100)
abline(v=d$sl.quant, col="red")

### histogram of Hartmann distances and indifference region
hist(d$h.vals, breaks=100)
abline(v=d$h.quant, col="red")


## End(Not run)