New Excel output (close #6), update README, tweak UI (e.g. mouse-overs)

* Excel output: added table with raw matching score, i.e. without constructs
  reversal, to better resemble step 3 from method description
* Update README with parts from the JOSS paper as suggested by reviewers
* UI Tweaks to improve usability: info box informs that the output is an
  Excel file, mouser-over for most analysis settings
* Added MIT License

Author: markheckmann

DESCRIPTION

@@ -21,7 +21,7 @@ Authors@R: c(person(
 Description: Shiny UI to identify cliques of related constructs in repertory grid data. 
     See Burr, King, & Heckmann (2020) <doi:10.1080/14780887.2020.1794088> for a description 
     of the interpretive clustering (IC) method.
-Version: 0.5.2
+Version: 0.6.0
 Date: 2022-04-24
 Imports:
     graphics,
@@ -59,4 +59,4 @@ Suggests:
 Encoding: UTF-8
 URL: https://github.com/markheckmann/OpenRepGrid.ic
 BugReports: https://github.com/markheckmann/OpenRepGrid.ic/issues
-RoxygenNote: 7.1.1
+RoxygenNote: 7.1.2

LICENSE

@@ -0,0 +1,2 @@
+YEAR: 2022
+COPYRIGHT HOLDER: OpenRepGrid.ic authors

NAMESPACE

@@ -25,5 +25,6 @@ importFrom(dplyr,group_by)
 importFrom(dplyr,recode)
 importFrom(dplyr,select)
 importFrom(magrittr,"%>%")
+importFrom(shinyBS,tipify)
 importFrom(stats,na.omit)
 importFrom(withr,with_par)

NEWS.Rmd

@@ -4,8 +4,13 @@ output: html_document
 ---
 
 
-## v0.5.2
+## v0.6.0
 
+* Excel output: added table with raw matching score, i.e. without constructs reversal, to better 
+  resemble step 3 from method description
+* Update README with parts from the JOSS paper as suggested by reviewers
+* UI Tweaks to improve usability: info box informs that the output is an Excel file, 
+  mouser-over for most analysis settings
 * Added MIT License
 
 ## v0.5.1

R/02-calculate.R

@@ -1,8 +1,9 @@
-#////////////////////////////////////////////////////////////
+#//////////////////////////////////////////////////////////////////////////////////////
 #
-#                       IC Calculations
+#                                IC Calculations
 #
-#////////////////////////////////////////////////////////////
+#//////////////////////////////////////////////////////////////////////////////////////
+
 
 #' Count number of matches / non-matches for two constructs 
 #' 
@@ -92,10 +93,6 @@ calculate_similarity <- function(x, min_matches = 6, align_poles = TRUE) #, use_
     }
   }
 
-  # # for each construct geerate list of constructs constructs with >= 6 matches
-  # mm <- apply(ii, 1, which)   # like in Table 4a 
-  # # mx <- sapply(mm, length) %>% max
-  
   # keep bigger relatedness score
   M_vec <- as.vector(M)
   Mi_vec <- as.vector(Mi)
@@ -108,7 +105,7 @@ calculate_similarity <- function(x, min_matches = 6, align_poles = TRUE) #, use_
   # mark positive and negative relatedness
   ii_m <- M >= criterion_ 
   ii_mi <- Mi >= criterion_
-  ii <- ii_m | ii_mi   # min of 6 identical responses (match or mismatch)
+  ii <- ii_m | ii_mi   # min of n identical responses (match or mismatch)?
   D[ii_m] <- 1
   D[ii_mi] <- -1
 
@@ -134,7 +131,8 @@ calculate_similarity <- function(x, min_matches = 6, align_poles = TRUE) #, use_
   names(valence_left) <- labels
   names(valence_right) <- labels
 
-  list(R = R,    # no of matches 
+  list(R = R,    # no of matches (indlucing optional construct reversal, i.e. only high no. of matches relevant
+       M = M,    # matrix of matches without optional construct reversal, as described in paper, i.e. a very low and very high number of matches relevant
        MM = MM,  # relatedness 0/1
        D = D,    # direction of relation -1/1
        constructs = constructs,
@@ -357,7 +355,7 @@ network_graph_images <- function(x,
 
   img_all_constructs <- tempfile(fileext = ".png")
   png(img_all_constructs, width = 20, height = 20, units = "cm", res = 300)
-  #par(oma = c(0,0,0,0), mar = c(0,0,0,0))
+  #par(oma = c(0,0,0,0), mar = c(0,0,0,0))   # can be left out for now but kept as a reminder comment for an alternative approach
   with_par(img_par, {
     set.seed(seed)
     igraph::plot.igraph(g, 
@@ -400,7 +398,7 @@ network_graph_images <- function(x,
 
   img_all_constructs_full_labels <- tempfile(fileext = ".png")
   png(img_all_constructs_full_labels, width = 20, height = 20, units = "cm", res = 300)
-  # par(oma = c(0,0,0,0), mar = c(0,0,0,0))
+  # par(oma = c(0,0,0,0), mar = c(0,0,0,0))   # can be left out for now but kept as a reminder comment for an alternative approach
   with_par(img_par, {
     set.seed(seed)
     igraph::plot.igraph(g, 
@@ -439,7 +437,6 @@ network_graph_images <- function(x,
   ii_keep <- match(cns, names(cnames))
   vertex.labels <-
     cnames[cns] %>%
-    # str_sub(start = 1, end = label_max_length) %>%
     str_wrap(width = label_wrap_width)
   vertex.size <- 22
   vertex.label.cex <- .5
@@ -533,7 +530,7 @@ network_graph_images <- function(x,
                         vertex.size = vertex.size,
                         vertex.label = vertex.labels2,
                         vertex.size2 = vertex.size,
-                        vertex.label.color = colors_poles_right, #"black",
+                        vertex.label.color = colors_poles_right, 
                         vertex.label.cex = vertex.label.cex,
                         vertex.label.family = "mono",
                         vertex.label.font = vertex_font_pole_2,
@@ -691,8 +688,8 @@ network_graph_images <- function(x,
   })
 
   names(vertex_relations) <- cns
-  vertex_font_pole_1 <- 1 #recode(vertex_relations, "neg"= 2, .default = 1)
-  vertex_font_pole_2 <- 2 # recode(vertex_relations, "neg"= 1, .default = 2)
+  vertex_font_pole_1 <- 1 # recode(vertex_relations, "neg"= 2, .default = 1)  # can be left out for now but kept as a reminder comment for an alternative approach
+  vertex_font_pole_2 <- 2 # recode(vertex_relations, "neg"= 1, .default = 2)  # can be left out for now but kept as a reminder comment for an alternative approach
 
   vertex.labels1 <- replace_all(vertex.labels, first = TRUE)
   vertex.labels2 <- replace_all(vertex.labels, first = FALSE)

R/03-excel.R

@@ -1,8 +1,8 @@
-#////////////////////////////////////////////////////////////
+#/////////////////////////////////////////////////////////////////////////////////////
 #
-#                       Excel output
+#                                 Excel output
 #
-#////////////////////////////////////////////////////////////
+#/////////////////////////////////////////////////////////////////////////////////////
 
 
 #' Check if Excel input file contains valid data
@@ -149,7 +149,8 @@ create_excel_output <- function(file, data = list())
   nms <- names(wb)
   constructs_df <- data.frame("constructs" = data$constructs, stringsAsFactors = FALSE)
   R <- data$R
-  D <- data$D
+  D <- data$D  # matrix with matches (with optional construct reversal)
+  M <- data$M  # matrix with matches (no construct reversal)
   cliques_list <- data$cliques_list
   clique_lists_full_names <- data$clique_lists_full_names
 
@@ -202,10 +203,20 @@ create_excel_output <- function(file, data = list())
     c("* Positive construct poles (as indicated by column 'preferred') are aligned on the right",
     "** 1 = positive relatedness, -1 = negative relatedness"), stringsAsFactors = FALSE)
   writeData(wb, sheet, lgnd, startRow = row + 2, startCol = 1, colNames = FALSE, rowNames = FALSE)
-  
-  # matches
+
+  # matches (no construct reversal)
   row <- 6
-  writeData(wb, sheet, "Number of matches between constructs*", startRow = row, startCol = 1)
+  writeData(wb, sheet, "Number of matches between constructs (no construct reversal)*", startRow = row, startCol = 1)
+  addStyle(wb, sheet, style = style_bold, gridExpand = TRUE, rows = row, cols = 1) 
+  writeData(wb, sheet, constructs_df, startRow = row + 2, startCol = 1, colNames = TRUE, rowNames = FALSE)
+  addStyle(wb, sheet, style = style_right, rows = row + 2, cols = 1) 
+  addStyle(wb, sheet, style = style_italic, rows = row + 2, cols = 1, stack = TRUE) 
+  addStyle(wb, sheet, style = style_right, gridExpand = TRUE, rows = 1L:nrow(R) + row + 2, cols = 1) 
+  writeData(wb, sheet, M, startRow = row + 2, startCol = 2, colNames = TRUE, rowNames = TRUE)
+  
+  # matches (with optional construct reversal)
+  row <- row + nrow(M) + 4
+  writeData(wb, sheet, "Number of matches between constructs (after optional construct reversal)*", startRow = row, startCol = 1)
   addStyle(wb, sheet, style = style_bold, gridExpand = TRUE, rows = row, cols = 1) 
   writeData(wb, sheet, constructs_df, startRow = row + 2, startCol = 1, colNames = TRUE, rowNames = FALSE)
   addStyle(wb, sheet, style = style_right, rows = row + 2, cols = 1) 
@@ -215,7 +226,7 @@ create_excel_output <- function(file, data = list())
 
   # direction
   i <- row + nrow(R) + 4
-  txt <- paste0("Relatedness by criterion (matches >= ", min_matches, ")**")
+  txt <- paste0("Relatedness by criterion (matches >= ", min_matches, " after optional construct reversal)**")
   writeData(wb, sheet, txt, startRow = i, startCol = 1)
   addStyle(wb, sheet, style = style_bold, gridExpand = TRUE, rows = i, cols = 1) 
   writeData(wb, sheet, constructs_df, startRow = i + 2, startCol = 1, colNames = TRUE, rowNames = FALSE)
@@ -228,6 +239,7 @@ create_excel_output <- function(file, data = list())
   conditionalFormatting(wb, sheet, cols = 1L:nrow(R) + 2, rows = 1L:nrow(R) + i + 2, rule = "<0", style = neg_style)
   conditionalFormatting(wb, sheet, cols = 1L:nrow(R) + 2, rows = 1L:nrow(R) + i + 2, rule = ">0", style = pos_style)
 
+  
   # Clique enumeration ----------------------------------
 
   sheet <- "cliques"

R/OpenRepGrid.ic.R

@@ -33,6 +33,7 @@
 #' @rawNamespace import(graphics, except = box)
 #' @importFrom withr with_par
 #' @importFrom stats na.omit
+#' @importFrom shinyBS tipify
 #' @import
 #' utils
 #' grDevices

README.md

@@ -10,11 +10,31 @@ This package implements the [Interpretive Clustering (IC)](https://doi.org/10.10
 method as described in [Burr, King, and Heckmann (2020)](https://doi.org/10.1080/14780887.2020.1794088).
 An introduction to the software is available on [YouTube](https://youtu.be/f9oINYA22Rc).
 Interpretive Clustering is a variant of construct clustering for [repertory grid](https://en.wikipedia.org/wiki/Repertory_grid)
-data. While derived from theoretical considerations based on [Personal Construct Theory](https://en.wikipedia.org/wiki/Personal_construct_theory), the procedure itself is mathematically equivalent to a problem from graph theory called [maximal cliques enumeration](https://en.wikipedia.org/wiki/Clique_problem#Listing_all_maximal_cliques). Given a similarity measure, in our case the number of matching scores between two constructs, a network graph of relatedness between constructs is construed. A clique is a group of constructs which are all mutually related, given some cut-off criterion for relatedness (e.g. 6 matching scores in a grid with 7 elements). While an offline approach is also described to find the construct cliques, this software automates the process. Below you see the resulting cliques for Sylvia's sample grid. In the paper, the interpretation of the discovered cliques is discussed in detail.
+data. While derived from theoretical considerations based on [Personal Construct Theory](https://en.wikipedia.org/wiki/Personal_construct_theory), the procedure itself is mathematically equivalent to a problem from graph theory called [maximal cliques enumeration](https://en.wikipedia.org/wiki/Clique_problem#Listing_all_maximal_cliques). 
+Given a similarity measure, in our case the number of matching scores between
+two constructs, a network graph of relatedness between constructs is construed.
+A clique is a group of constructs which are all mutually related, given some
+cut-off criterion for relatedness (e.g. 6 matching scores in a grid with 7
+elements). While an offline approach is also described to find the construct
+cliques, this software automates the process. Below you see the resulting
+cliques for Sylvia's sample grid. In the paper, the interpretation of the
+discovered cliques is discussed in detail.
 
 ![example](inst/shiny/www/sylvia_cliques.png "Construct cliques for Sylvias's grid")
 
 
+# Statement of need 
+
+Currently, the IC method is not implemented in any other existing repertory grid
+software. While IC can also be conducted by hand, this is very time consuming,
+error-prone and only feasible for small-sized grids. Hence, a software solution
+to support the IC procedure is needed. Without proper software support which
+facilitates the process, the IC method is likely to become a methodological
+contribution which will rarely be used in research due to above mentioned
+reasons.
+
+
+
 ## Installation
 
 You can install the latest official release version from CRAN
@@ -44,3 +64,12 @@ You can find the datasets used in our publication on Zenodo.
 
 [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.3629868.svg)](https://doi.org/10.5281/zenodo.3629868)
 
+
+# Contributing
+
+In order to maximize the package's usefulness for the research community, we
+welcome participation in the package's development. Experienced R programmers
+are asked to make pull requests to the [`OpenRepGrid.ic` github repository](https://github.com/markheckmann/OpenRepGrid.ic), [report issues](https://github.com/markheckmann/OpenRepGrid.ic/issues), or commit code
+snippets. Non-technical oriented researchers are invited to send us feature
+requests or suggestions for improvement.
+

inst/examples/01-process-excel-file.R

@@ -15,9 +15,7 @@ l <- network_graph_images(x, min_clique_size = 3,
                           show_edges = TRUE, 
                           min_matches = 6)    # produce images
 file_tmp <- create_excel_output(file, l)      # create Excel file
-
-# copy Excel to working dir (commented out to avoid file generation during testing)
-#file.copy(file_tmp, file_out, overwrite = TRUE)  
+# file.show(file_tmp)  # not run during tests
 
 # open images saved as temp files (as shown in output Excel file)
 file.show(l$img_all_constructs)

inst/shiny/server.R

@@ -1,8 +1,8 @@
-#////////////////////////////////////////////////////
+#///////////////////////////////////////////////////////////////////////////////////////////
 #
-#                     server
+#                                   server
 #
-#////////////////////////////////////////////////////
+#//////////////////////////////////////////////////////////////////////////////////////////
 
 library(shiny)
 library(shinyjs)
@@ -100,7 +100,6 @@ server <- function(input, output, session)
   # the flag 'data_status' is needed so other processes can use the info
   observeEvent(rv$data, {
     x <- rv$data
-    cat("\ncheck data")
     if (is.null(x)) {
       rv$data_status <- "empty"
     } else {
@@ -196,7 +195,6 @@ server <- function(input, output, session)
     # all test were passed
     cat("\nall tests passed")
     hide("error_box")
-    show("success_box")
     show("down_btn")
     show("settings_box_1")
     show("settings_box_2")