v0.1.18 Better import / export, preferred poles added, fixed bug in align and bertinCluster

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.18.9006
-Date: 2025-05-12
+Version: 0.1.18
+Date: 2025-07-08
 Encoding: UTF-8
 URL: https://github.com/markheckmann/OpenRepGrid
 Imports:

NAMESPACE

@@ -99,13 +99,15 @@ export(getNoOfElements)
 export(getRatingLayer)
 export(getScale)
 export(getScaleMidpoint)
+export(grid_to_df_long)
+export(grid_to_df_wide)
 export(gridlist)
 export(grids_bootstrap)
 export(grids_leave_n_out)
 export(grids_perturbate)
 export(home)
+export(importDataframe)
 export(importExcel)
-export(importExcelInternal)
 export(importGridcor)
 export(importGridcorInternal)
 export(importGridstat)
@@ -115,7 +117,6 @@ export(importGridsuiteInternal)
 export(importScivesco)
 export(importScivescoInternal)
 export(importTxt)
-export(importTxtInternal)
 export(indexBias)
 export(indexBieri)
 export(indexConflict1)
@@ -177,6 +178,7 @@ export(ring)
 export(sapply_pb)
 export(saveAsExcel)
 export(saveAsTxt)
+export(saveAsWorksheet)
 export(setConstructAttr)
 export(setElementAttr)
 export(setMeta)

NEWS.md

@@ -1,5 +1,13 @@
-# OpenRepGrid 0.1.18 (dev version)
-
+# OpenRepGrid 0.1.18
+
+* `saveAsExcel` can export a list of grids now (#67)
+* `saveAsWorksheet` adds a grid as a new sheet to a `openxlsx` `Workbook` object.
+* `makeGrid` and `randomGrid` can add construct pole preference.
+* `importExcel` now also understands the long format (#65) and can import from several sheets at once (#68)
+* `importDataframe` converts a dataframe into a repgrid. Three different formats can be read in. See the sample 
+   dataframes `df_element_columns`, `df_construct_columns`, and `df_long` (#61)
+* `saveAsExcel` now supports output in wide and long format. The output is also formatted now (#64)
+* `bertinCluster`: now restores the original `par()` settings after changing the plot layout (#63)
 * `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)

R/bertin.r

@@ -335,7 +335,7 @@ bertinBase <- function(nrow, ncol, labels = "", labels.elements = "",
   }
 
   colorRow <- function(cr) {
-    par(new = TRUE) # next plot will overplot not earse the old one, necessary for setting the same regions
+    old_par <- par(new = TRUE) # next plot will overplot not erase the old one, necessary for setting the same regions
     plot.new()
     # plot.window(xlim=0:1, ylim=0:1) #, xaxs="i", yaxs="i")#, asp =nrow/ncol)
     if (cr >= 1 & cr <= nrow) { # color current row cr
@@ -348,10 +348,11 @@ bertinBase <- function(nrow, ncol, labels = "", labels.elements = "",
         labels = labels.rows, col = col.mark.text, cex = cex.text
       )
     }
+    par(old_par)
   }
 
   colorColumn <- function(cc) {
-    par(new = TRUE) # next plot will overplot not earse the old one, necessary for setting the same regions
+    old_par <- par(new = TRUE) # next plot will overplot not earse the old one, necessary for setting the same regions
     plot.new()
     # plot.window(xlim=0:1, ylim=0:1) #, xaxs="i", yaxs="i")#, asp =nrow/ncol)
     if (cc >= 1 & cc <= ncol) { # color current column cc
@@ -373,6 +374,7 @@ bertinBase <- function(nrow, ncol, labels = "", labels.elements = "",
       segments(x.lines[cc], y1.lines, x.lines[cc], y2.lines[cc], lwd = 3, col = "white") # overplot old stroke in white
       segments(x.lines[cc], y1.lines, x.lines[cc], y2.lines[cc], col = col.mark.fill)
     }
+    par(old_par)
   }
 
   renewColumn <- function(cc) {
@@ -440,7 +442,7 @@ bertinBase <- function(nrow, ncol, labels = "", labels.elements = "",
   # set plotting parameters
   # old.par <- par(no.readonly = TRUE)    # save parameters
   # on.exit(par(old.par))                 # reset old par when done
-  op <- par(oma = rep(0, 4), mar = rep(0, 4), xaxs = "i", yaxs = "i")
+  old_par <- par(oma = rep(0, 4), mar = rep(0, 4), xaxs = "i", yaxs = "i")
   if (print) { # in case no new printing should occur
     par(new = FALSE)
   } else {
@@ -466,7 +468,7 @@ bertinBase <- function(nrow, ncol, labels = "", labels.elements = "",
     colorRow(cr)
     colorColumn(cc)
   }
-  # par(op)
+  par(old_par)
   invisible(NULL)
 }
 
@@ -786,16 +788,14 @@ bertinCluster <- function(x, dmethod = c("euclidean", "euclidean"),
 
   x <- x[con.ord, el.ord] # reorder repgrid object
 
+  old_par <- par(fig = c(xsegs[c(1, 4)], ysegs[c(2, 4)]))
   plot.new()
-  par(fig = c(xsegs[c(1, 4)], ysegs[c(2, 4)]), new = TRUE)
-  # par(fig = c(0, .8, .2, 1), new=T)
-
-  bertin(x, xlim = xlim.bertin, ylim = ylim.bertin, add = TRUE, ...) # print reordered bertin
+  bertin(x, xlim = xlim.bertin, ylim = ylim.bertin, add = FALSE, ...) # print reordered bertin
 
   # x dendrogram (horizontal) elements
   if (!is.na(cmethod[2])) {
     dend.x.fig <- c(xsegs[2:3], ysegs[1:2]) + c(0, 0, y.off, -y.off) # adjust for offsets
-    par(fig = dend.x.fig, new = T, mar = c(0, 0, 0, 0))
+    par(fig = dend.x.fig, new = TRUE, mar = c(0, 0, 0, 0)) # trick: new = TRUE avoids opening a new plot window in next plot
     ymax.el <- attr(dend.el, "height")
     plot(dend.el,
       horiz = F, xlab = "", xaxs = "i", yaxs = "i", yaxt = "n",
@@ -819,17 +819,7 @@ bertinCluster <- function(x, dmethod = c("euclidean", "euclidean"),
       axis(1, las = 1, cex.axis = cex.axis, col = col.axis, col.axis = col.axis)
     }
   }
+  par(old_par)
   # return hclust objects for elements and constructs
   invisible(list(constructs = fit.constructs, elements = fit.elements))
 }
-
-# TODO: use of layout does not work with bertinCluster
-# a future version could use layout
-# layout (matrix(1:4), 2)
-# bertinCluster(bell2010)
-
-# bertinCluster(bell2010, type="t", bor=grey(.5))
-# dev.new()
-# bertinCluster(bell2010, type="t", dm="manhattan", cm="single")
-# dev.new()
-# bertinCluster(bell2010, type="t", dm="manhattan", cm="centroid")

R/data-openrepgrid.r

@@ -4,8 +4,10 @@
 #
 # //////////////////////////////////////////////////////////////////////////////
 
+# _____________ ----
+# REPGRID ----
 
-# Bell (2010) ----
+## Bell (2010) ----
 
 #' Grid data from Bell (2010).
 #'
@@ -54,7 +56,7 @@ NULL
 # save("bell2010", file="../data/bell2010.RData")
 
 
-# Bell and McGorry (1992) ----
+## Bell and McGorry (1992) ----
 
 #' Grid data from Bell and McGorry (1992).
 #'
@@ -112,7 +114,7 @@ NULL
 # save("bellmcgorry1992", file="../data/bellmcgorry1992.RData")
 
 
-# Boeker (1996) ----
+## Boeker (1996) ----
 
 #' Grid data from Boeker (1996).
 #'
@@ -171,7 +173,7 @@ NULL
 # saveAsExcel(boeker, "inst/extdata/boeker.xlsx")
 
 
-# Fransella, Bell & Bannister (2003) ----
+## Fransella, Bell & Bannister (2003) ----
 
 #' Grid data from Fransella, Bell and Bannister (2003).
 #'
@@ -211,7 +213,7 @@ NULL
 # save("fbb2003", file="../data/fbb2003.RData")
 
 
-# Feixas and Saul (2004) ----
+## Feixas and Saul (2004) ----
 
 #' Grid data from Feixas and Saul (2004).
 #'
@@ -277,7 +279,7 @@ NULL
 
 
 
-# Leach et al. (2001) ----
+## Leach et al. (2001) ----
 
 #' Pre- and post therapy dataset from Leach et al. (2001).
 #'
@@ -368,7 +370,7 @@ NULL
 
 
 
-# Mackay (1992) ----
+## Mackay (1992) ----
 
 #' Grid data from Mackay (1992).
 #'
@@ -405,7 +407,7 @@ NULL
 # save("mackay1992", file="../data/mackay1992.RData")
 
 
-# Raeithel (1998) ----
+## Raeithel (1998) ----
 
 #' Grid data from Raeithel (1998).
 #'
@@ -457,7 +459,7 @@ NULL
 
 
 
-# Slater (1977a) ----
+## Slater (1977a) ----
 
 #' Drug addict's grid data set from Slater (1977, p. 32).
 #'
@@ -509,7 +511,7 @@ NULL
 # save("slater1977a", file="../data/slater1977a.RData")
 
 
-# Slater (1977b) ----
+## Slater (1977b) ----
 
 #' Grid data from Slater (1977).
 #'
@@ -555,3 +557,118 @@ NULL
 # slater1977b <- makeRepgrid(args)
 # slater1977b <- setScale(slater1977b, 1, 10)
 # save("slater1977b", file="../data/slater1977b.RData")
+
+
+# _____________ ----
+# DATAFRAME ----
+
+##  df_element_columns ----
+
+#' Sample dataframe with grid data (elements are columns)
+#'
+#' This dataframe can be converted into a `repgrid` object via [importDataframe()]. The dataframe column names are the
+#' minimum of the rating scale (`1`), the element names (`element_1` to `element_4`), the maximum of the rating scale
+#' (`5`), and optionally a column indicating the `preferred` pole. Each row contains the constructs' entries (left
+#' pole, ratings, right pole, preferred pole). The preferred pole must be one of `left`, `right`, `none`, `NA` (see
+#' [preferredPoles()]). See sample data [df_element_columns].
+#'
+#' \tabular{lccccrr}{
+#' `1`           \tab `element_1` \tab `element_2` \tab `element_3` \tab `element_4` \tab `5`            \tab `preferred` \cr
+#' `left_pole_1` \tab `1`         \tab `5`         \tab `3`         \tab `4`         \tab `right_pole_1` \tab `left`      \cr
+#' `left_pole_2` \tab `3`         \tab `1`         \tab `1`         \tab `3`         \tab `right_pole_2` \tab `right`     \cr
+#' `left_pole_3` \tab `4`         \tab `2`         \tab `5`         \tab `1`         \tab `right_pole_3` \tab `none`        \cr
+#' }
+#' @name df_element_columns
+#' @family grid_dataframe
+#' @docType data
+#' @seealso [importDataframe()]
+#' @keywords data
+#' @examples
+#' df_element_columns
+#' importDataframe(df_element_columns)
+NULL
+
+# # dataframe with columns as elements
+# file <- system.file("extdata", "grid_01.xlsx", package = "OpenRepGrid")
+# x <- importExcel(file)
+# x <- x[1:3, 1:4]  # smaller version
+# df_element_columns <- grid_to_wide_format(x)
+# save("df_element_columns", file="data/df_element_columns.RData")
+# rg2 <- importDataframe(df_element_columns)
+
+
+## df_construct_columns ----
+
+#' Sample dataframe with grid data (constructs are columns)
+#'
+#' This dataframe can be converted into a `repgrid` object via [importDataframe()]. The columns names are `elements`
+#' followed by the constructs (`left_pole_1:right_pole_1` to `left_pole_3:right_pole_3`). The poles are separated by a
+#' colon by default (change via arg `pole_sep`). The rows contain the elements' entries (element name and ratings). The
+#' min and max of the rating scale should be passed explicitly via the args `rmin` and `rmax`. See sample data
+#' [df_construct_columns].
+#'
+#' \tabular{lrrrr}{
+#' `elements`  \tab `left_pole_1:right_pole_1` \tab `left_pole_2:right_pole_2` \tab `left_pole_3:right_pole_3` \cr
+#' `element_1` \tab `5`                        \tab `3`                        \tab `2`                        \cr
+#' `element_2` \tab `3`                        \tab `3`                        \tab `4`                        \cr
+#' `element_3` \tab `1`                        \tab `5`                        \tab `2`                        \cr
+#' `element_4` \tab `4`                        \tab `3`                        \tab `3`                        \cr
+#' }
+#' @name df_construct_columns
+#' @family grid_dataframe
+#' @seealso [importDataframe()]
+#' @docType data
+#' @keywords data
+#' @examples
+#' df_construct_columns
+#' importDataframe(df_construct_columns, format = "construct_columns", rmin = 1, rmax = 5)
+NULL
+
+# # dataframe with columns as constructs
+# file <- system.file("extdata", "grid_01.xlsx", package = "OpenRepGrid")
+# x <- importExcel(file)
+# x <- x[1:3, 1:4]  # smaller version
+# df_construct_columns <- grid_to_long_format(x) %>%
+#   mutate(construct = paste0(left_pole, ":", right_pole)) %>%
+#   pivot_wider(id_cols = "element", names_from = "construct", values_from = "rating")
+# save("df_construct_columns", file="data/df_construct_columns.RData")
+# rg2 <- importDataframe(df_construct_columns, format = "c", rmin = 1, rmax = 5)
+
+
+## df_long ----
+
+#' Sample dataframe with grid data (long)
+#'
+#' This dataframe can be converted into a `repgrid` object via [importDataframe()].
+#' The `long` format has this name because it has few columns and many rows. It is a common format
+#' in data analytics. Here, each row contains a different element-construct combination and the corresponding rating
+#' value. The format looks like this:
+#'
+#' \tabular{lllrlrr}{
+#' `element`   \tab `left_pole`   \tab `right_pole`   \tab `rating` \tab `preferred_pole` \tab `rmin` \tab `rmax` \cr
+#' `element 1` \tab `left pole 1` \tab `right pole 1` \tab `5`      \tab `left`           \tab `1`    \tab `5`   \cr
+#' `element_2` \tab `left pole 1` \tab `right pole 1` \tab `3`      \tab `left`           \tab `1`    \tab `5`   \cr
+#' `element_3` \tab `left pole 1` \tab `right pole 1` \tab `1`      \tab `left`           \tab `1`    \tab `5`   \cr
+#' }
+#'
+#' The columns `element`, `left_pole`, `right_pole`, and `rating` are mandatory, the columns `preferred_pole`, `rmin`,
+#' and `rmax` are optional. `rmin` and `rmax` contain the min and max of the rating scale. Alternatively, you may
+#' pass `rmin` and `rmax` as arguments in the function call.
+#'
+#' @name df_long
+#' @family grid_dataframe
+#' @seealso [importDataframe()]
+#' @docType data
+#' @keywords data
+#' @examples
+#' df_long
+#' importDataframe(df_long, format = "long")
+NULL
+
+# # # dataframe with columns as constructs
+# file <- system.file("extdata", "grid_01.xlsx", package = "OpenRepGrid")
+# x <- importExcel(file)
+# x <- x[1:3, 1:4]  # smaller version
+# df_long <- grid_to_long_format(x)
+# save("df_long", file="data/df_long.RData")
+# rg2 <- importDataframe(df_long, format = "long")