Add preferred pole to grid, plot in grid console

DESCRIPTION

@@ -16,8 +16,8 @@ Description: Analyze repertory grids, a qualitative-quantitative
     to quantitatively analyze and visualize repertory grid data (e.g. 'Fransella', 'Bell', & 'Bannister', 
     2004, ISBN: 978-0-470-09080-0). The package is part of the The package is part of the 
     <https://openrepgrid.org/> project.
-Version: 0.1.17
-Date: 2025-03-02
+Version: 0.1.18.9006
+Date: 2025-05-12
 Encoding: UTF-8
 URL: https://github.com/markheckmann/OpenRepGrid
 Imports:
@@ -56,6 +56,7 @@ Collate:
     'onair.r'
     'openrepgrid.r'
     'perturbate.R'
+    'preferred_poles.R'
     'repgrid.r'
     'repgrid-basicops.r'
     'repgrid-constructs.r'

NAMESPACE

@@ -35,6 +35,7 @@ S3method(rep,repgrid)
 export("constructs<-")
 export("elements<-")
 export("leftpoles<-")
+export("preferredPoles<-")
 export("ratings<-")
 export("rightpoles<-")
 export(addAvgElement)
@@ -44,6 +45,7 @@ export(addIndexColumnToMatrix)
 export(addVarianceExplainedToBiplot2d)
 export(alignByIdeal)
 export(alignByLoadings)
+export(alignByPreferredPole)
 export(apply_pb)
 export(as.gridlist)
 export(bertin)
@@ -68,7 +70,6 @@ export(center)
 export(clearRatings)
 export(cluster)
 export(clusterBoot)
-export(colorize_matrix_rows)
 export(constructCor)
 export(constructD)
 export(constructPca)
@@ -150,6 +151,8 @@ export(orderByString)
 export(permuteConstructs)
 export(permuteGrid)
 export(perturbate)
+export(preferredPoles)
+export(preferredPolesByIdeal)
 export(prepareBiplotData)
 export(print_square_matrix)
 export(quasiDistributionDistanceSlater)
@@ -182,14 +185,14 @@ export(settings)
 export(settingsLoad)
 export(settingsSave)
 export(shift)
-export(showMeta)
 export(showScale)
 export(slaterStandardization)
 export(ssq)
 export(statsConstructs)
 export(statsElements)
 export(stepChart)
 export(stop_if_not_0_1_ratings_only)
+export(stop_if_not_in_element_range)
 export(stop_if_not_is_repgrid)
 export(stop_if_scale_not_defined)
 export(strReverse)
@@ -227,3 +230,4 @@ importFrom(crayon,red)
 importFrom(crayon,silver)
 importFrom(crayon,white)
 importFrom(crayon,yellow)
+importFrom(dplyr,case_when)

NEWS.md

@@ -1,3 +1,14 @@
+# OpenRepGrid 0.1.18 (dev version)
+
+* `importTxt` reads preferred poles from section `PREFERRED`, `importExcel` reads rightmost column `preferred_poles` (#57)
+* `preferredPoles` sets the preferred construct poles, `preferredPolesByIdeal` sets the preferred pole bases on the 
+  ideal elements ratings, `alignByPreferredPole` aligns constructs by pole preference (#57)
+* `biplot3d`: New args `e.sphere.show`, `e.labels.show`, `c.axis.show`. `c.sphere.show`. Construct spheres now hidden 
+  by default. Construct axes start at origin (#9, #25)
+* `print.distance`: fix docs for `cutoffs` arg (#18)
+* `distanceHartmann`: change default for `method` arg to `simulate` (#19)
+* fix bug in `align` which caused constructs to disappear and subsequent bugs in `bertinCluster` and `cluster` (#22, #31)
+
 # OpenRepGrid 0.1.17
 
 * `clusterBoot` gains `trim` arg. Construct labels in dendrogram are no longer trimmed by default (#58).
@@ -51,34 +62,34 @@
 
 # OpenRepGrid 0.1.13 
 
-  * indexDilemma was improved and fixed (thanks to Diego Vitali aka @artoo-git)
-  * biplot2d does now hide construct points as default setting (cex=0)
-  * setting a rating value outside the defined scale range now throws an error
-  * 'ratings' to access and replace grid ratings added
-  * 'elements' added to get and set element names replaces 'getElementNames' and 'eNames' which have become deprecated.
-  * 'constructs', 'leftpoles', and 'rightpoles' added to get and set construct poles replace 'getConstructNames' and 'cNames' which have become  deprecated.
+* indexDilemma was improved and fixed (thanks to Diego Vitali aka @artoo-git)
+* biplot2d does now hide construct points as default setting (cex=0)
+* setting a rating value outside the defined scale range now throws an error
+* 'ratings' to access and replace grid ratings added
+* 'elements' added to get and set element names replaces 'getElementNames' and 'eNames' which have become deprecated.
+* 'constructs', 'leftpoles', and 'rightpoles' added to get and set construct poles replace 'getConstructNames' and 'cNames' which have become  deprecated.
 
 # OpenRepGrid 0.1.11
 
-  * saveAsExcel to save grids as Microsoft Excel files
-  * replace xlsx by openxlsx to import Excel files to get rid of JRE dependency
+* saveAsExcel to save grids as Microsoft Excel files
+* replace xlsx by openxlsx to import Excel files to get rid of JRE dependency
 
 # OpenRepGrid 0.1.10
 
-  * indexDilemma: improved implicative dilemmas (thanks to Alejandro García, (#24, @j4n7)
-  * changelog file as place for documenting changes removed. All changes now in NEWS
+* indexDilemma: improved implicative dilemmas (thanks to Alejandro García, (#24, @j4n7)
+* changelog file as place for documenting changes removed. All changes now in NEWS
 
 # OpenRepGrid 0.1.9
 
-  * align parameter added to cluster
-  * importTxt will now erase empty lines
-  * changed default settings for implicative dilemmas
-  * dependency on xlsx removed (issue #15)
+* align parameter added to cluster
+* importTxt will now erase empty lines
+* changed default settings for implicative dilemmas
+* dependency on xlsx removed (issue #15)
 
 # OpenRepGrid 0.1.8
 
-  * importGridstat can now import multigrid files
-  * bug fix in importTxt: negative values are read in again
+* importGridstat can now import multigrid files
+* bug fix in importTxt: negative values are read in again
 
 # OpenRepGrid 0.1.7
 

R/calc.r

@@ -934,7 +934,7 @@ print.constructPca <- function(x, digits = 2, cutoff = 0, ...) {
 #' *International Journal of Personal Construct Psychology, 5*(1), 57-75.
 #'
 #' @export
-#' @seealso [alignByIdeal()]
+#' @family align_constructs
 #' @examples
 #'
 #' # reproduction of the example in the Bell (2010)
@@ -1049,7 +1049,7 @@ print.alignByLoadings <- function(x, digits = 2, col.index = TRUE, ...) {
 #'   middle way? *Journal of Constructivist Psychology, 23*(4), 337-356.
 #'
 #' @export
-#' @seealso [alignByLoadings()]
+#' @family align_constructs
 #' @examples
 #'
 #' feixas2004 # original grid
@@ -1204,16 +1204,23 @@ cluster <- function(x, along = 0, dmethod = "euclidean", cmethod = "ward.D", p =
 
 
 # function calculates cluster dendrogram from doublebind grid matrix
-# and reverses the constructs accoring to the upper big cluster
+# by seleting the frist occurence of the reordered grid after clustering
+# we (probably) get a decent alignment. NB: Seriation would probably be better.
 align <- function(x, along = 0, dmethod = "euclidean",
                   cmethod = "ward.D", p = 2, ...) {
   x2 <- doubleEntry(x)
   xr <- cluster(x2,
     dmethod = dmethod, cmethod = cmethod, p = p,
     align = FALSE, print = FALSE
   )
-  nc <- getNoOfConstructs(xr) / 2
-  xr[1:nc, ]
+  # step 1: cluster by distance
+  # step 2: take the first occurence of each constructs (see #22)
+  # => should yield a reasonable alignment. Unclear if it has edge cases.
+  df_con <- constructs(xr)
+  l <- as.list(as.data.frame(t(df_con))) # df rows as list
+  con <- vapply(l, function(x) paste(sort(x), collapse = " "), character(1))
+  ii <- which(!duplicated(con))
+  xr[ii, ]
 }
 
 

R/distance.R

@@ -125,9 +125,8 @@ dist_minmax <- function(x, along = 1, dmethod = "euclidean", p = 2, max.only = F
 #'                    the output (default is `TRUE`).
 #' @param upper       Whether to display upper triangle of correlation matrix only
 #'                    (default is `TRUE`).
-#' @param cutoffs     Cutoff values. Values below or above this interval are not
-#'                    printed. For Slater distances `c(.8, 1.2)` are common
-#'                    values.
+#' @param cutoffs     Cutoff values. Only values outside the interval are printed.
+#'                    For Slater distances `c(.8, 1.2)` are common values.
 #' @param diag        Whether to show the matrix diagonal.
 #' @param ...         Not evaluated.
 #' @export
@@ -449,7 +448,7 @@ getDistributionParameters <- function(x, probs = c(.01, .025, .05, .1, .9, .95,
 #'                    parameters as given in Hartmann (1992) for calculation.
 #'                    `"simulate"` (default) simulates a Slater distribution
 #'                    for the calculation. In a future version the time consuming
-#'                    simulation will be replaced by more accurate parameters for
+#'                    simulation may be replaced by more accurate parameters for
 #'                    Hartmann distances than used in Hartmann (1992).
 #' @param reps        Number of random grids to generate sample distribution for
 #'                    Slater distances (default is `10000`). Note that
@@ -501,7 +500,7 @@ getDistributionParameters <- function(x, probs = c(.01, .025, .05, .1, .9, .95,
 #' hist(l$hartmann, breaks = 100)
 #' }
 #'
-distanceHartmann <- function(x, method = "paper", reps = 10000,
+distanceHartmann <- function(x, method = "simulate", reps = 10000,
                              prob = NULL, progress = TRUE, distributions = FALSE) {
   if (distributions == TRUE & method != "simulate") {
     method <- "simulate"