From eafd138e91665b2d2d1bcecf6a2975fd07999a98 Mon Sep 17 00:00:00 2001
From: James J Balamuta <james.balamuta@gmail.com>
Date: Thu, 11 Jan 2024 02:59:53 -0800
Subject: [PATCH] Add a highlight matrix

---
 NAMESPACE               |  1 +
 R/highlight.R           | 59 +++++++++++++++++++++++++++++++++++++++++
 man/highlight_matrix.Rd | 43 ++++++++++++++++++++++++++++++
 3 files changed, 103 insertions(+)
 create mode 100644 R/highlight.R
 create mode 100644 man/highlight_matrix.Rd

diff --git a/NAMESPACE b/NAMESPACE
index faa14bc..83b891f 100644
--- a/NAMESPACE
+++ b/NAMESPACE
@@ -2,6 +2,7 @@
 
 export(draw_matrix)
 export(gdraw_matrix)
+export(highlight_matrix)
 importFrom(graphics,mtext)
 importFrom(graphics,par)
 importFrom(graphics,plot.new)
diff --git a/R/highlight.R b/R/highlight.R
new file mode 100644
index 0000000..6ff7e13
--- /dev/null
+++ b/R/highlight.R
@@ -0,0 +1,59 @@
+#' Highlight a matrix
+#' 
+#' Generate a matrix with active areas.
+#' 
+#' @param x       A matrix.
+#' @param rows    An interger vector with valid row index locations.
+#' @param columns An integer vector containing valid column indexlocations.
+#' @param points  An m by 2 matrix with points listed in x, y format.
+#'
+#' @return 
+#' A logical matrix with the required rows and/or columns or points set to
+#' `TRUE`. All other values are given as `FALSE`.
+#'
+#' @export
+#' @examples
+#' 
+#' x = matrix(1:12, nrow = 4)
+#' 
+#' # Highlight entries only in the 1st and 3rd rows.
+#' highlight_matrix(x, rows = c(1, 3))
+#' 
+#' # Highlight entries only in the first two rows:
+#' highlight_matrix(x, rows = 1:2)
+#' 
+#' # Highlight entries in the last row
+#' highlight_matrix(x, rows = nrow(x))
+#' 
+#' # Highlight entries in the first column
+#' highlight_matrix(x, columns = 1)
+#' 
+#' # Highlight entries in the first column or first row.
+#' highlight_matrix(x, rows = 1, columns = 1)
+highlight_matrix <- function(x, rows = NULL, columns = NULL, points = NULL) {
+  
+  # Create a logical matrix with the same dimensions as 'x'
+  logical_matrix <- matrix(FALSE, nrow = nrow(x), ncol = ncol(x))
+  
+  # Nothing to mark.
+  if (is.null(rows) && is.null(columns) && is.null(points)) {
+    return(logical_matrix)
+  }
+  
+  if(!is.null(points)){
+    stopifnot("points must contain only two columns." = ncol(points) == 2)
+    logical_matrix[points] <- TRUE
+  }
+  
+  # Enable rows
+  if(!is.null(rows)){
+    logical_matrix[rows, ] <- TRUE
+  }
+  
+  # Enable columns
+  if(!is.null(columns)){
+    logical_matrix[, columns] <- TRUE
+  }
+  
+  logical_matrix
+}
diff --git a/man/highlight_matrix.Rd b/man/highlight_matrix.Rd
new file mode 100644
index 0000000..0e61c8c
--- /dev/null
+++ b/man/highlight_matrix.Rd
@@ -0,0 +1,43 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/highlight.R
+\name{highlight_matrix}
+\alias{highlight_matrix}
+\title{Highlight a matrix}
+\usage{
+highlight_matrix(x, rows = NULL, columns = NULL, points = NULL)
+}
+\arguments{
+\item{x}{A matrix.}
+
+\item{rows}{An interger vector with valid row index locations.}
+
+\item{columns}{An integer vector containing valid column indexlocations.}
+
+\item{points}{An m by 2 matrix with points listed in x, y format.}
+}
+\value{
+A logical matrix with the required rows and/or columns or points set to
+\code{TRUE}. All other values are given as \code{FALSE}.
+}
+\description{
+Generate a matrix with active areas.
+}
+\examples{
+
+x = matrix(1:12, nrow = 4)
+
+# Highlight entries only in the 1st and 3rd rows.
+highlight_matrix(x, rows = c(1, 3))
+
+# Highlight entries only in the first two rows:
+highlight_matrix(x, rows = 1:2)
+
+# Highlight entries in the last row
+highlight_matrix(x, rows = nrow(x))
+
+# Highlight entries in the first column
+highlight_matrix(x, columns = 1)
+
+# Highlight entries in the first column or first row.
+highlight_matrix(x, rows = 1, columns = 1)
+}