R/splitMap.R

In msxakk89/dat: Data Analyst Toolkit (dat): a library of tools for data analysts and scientists

#' Split a 2D map given 5 reference points
#' 
#' This function is an application of analytical geometry in order to split the map into "half" given 5 reference points. 
#' Given the line passing through points 1 and 2 and traingle vertices 3, 4 and 5 it computes the coefficients of line passing through circumcentre (3-4-5) and parallel to line (1-2).
#' 
#' @param ref_coord_mx A matrix or data frame of reference point coordinates on 2D plan. Ensure that ref_coord_mx[,1] represents coordinates on X-axis while ref_coord_mx[,2] represents coordinates on Y-axis. If applyAveraging is FALSE ensure that ref_coord_mx[1:2,] represent reference points 1 and 2 thus points that are passed by reference line, while ref_coord_mx[3:5,] represents the vertices of traingle for which circumcentre will be computed. Note that other rows may be supplied and will be ignored.
#' @param applyAveraging A boolean indicating whether to average the X-axis and Y-axis coordinates for the reference points if multiples of individual reference points are supplied. If set as TRUE pleasue set whichRowsAreRefPoints accordingly. Defults to FALSE.
#' @param whichRowsAreRefPoints A list of lenght 2 where first elements is named as 'line' and is a numeric vector of reference points 1 and 2 in the order in which they appear at the top of ref_coord_mx, while second element is named 'triangle' and is a numeric vector of reference vertices 3, 4 and 5 in the order in which they appear right after the place holders of 'line'. Ensure 'line' coordinates are right at the top of ref_coord_mx followed strictly by 'triangle' coordinates. If non-reference data is intermixed with reference data at the top than 0 can be supplied for them and the application will be functional. Example usage: list(line=c(1,1,2,2,0,1),triangle=c(3,3,4,4,5)). Defults to list(line=c(1,2),triangle=c(3, 4, 5)).
#' @param refRowNames An optional character vector of reference points names in their ascending order (1 -> 5). Defults to NULL.
#' @param returnRich A boolean. Do you want the coordinates of split line only or other info such as cicumcentre coordinates and parallel line coordinates.
#' @export
splitMap <- function(ref_coord_mx, applyAveraging = FALSE, whichRowsAreRefPoints=list(line=c(1,2),triangle=c(3, 4, 5)), refRowNames=NULL, returnRich = FALSE){
  # Step 1: computing the average of coordinates of repeated measures if given
  # Reference points must be on the top of mx and adjacent
  if(applyAveraging==TRUE){
    ref_coord_mx_2 <- matrix(ncol=2,nrow=1) 
    
    # averaging the coordinates of the lines
    for(i in 1:2){
      rows_i <- grep(pattern = i,x=whichRowsAreRefPoints[["line"]])
      ref_coord_mx_2 <- rbind(ref_coord_mx_2, colMeans(ref_coord_mx[rows_i,]))
    }
    # averaging the coordinates of the traingle
    # must add the lenght of 'line' vector in order to get the right row indexes
    for(i in 3:5){
      rows_i <- grep(pattern = i,x=whichRowsAreRefPoints[["triangle"]]) + length(whichRowsAreRefPoints[["line"]])
      ref_coord_mx_2 <- rbind(ref_coord_mx_2, colMeans(ref_coord_mx[rows_i,]))
    }
    ref_coord_mx_2 <- ref_coord_mx_2[-1,]
    row.names(ref_coord_mx_2) <- refRowNames
    ref_coord_mx <- ref_coord_mx_2
    # now the rows of ref_coord_mx are ordered by the relevant points
  }
  # Step 2 : computing the slope of line passing through points 1-2
  lineCoef <- compute_SlopeAndIntercept_givenTwoPoints(point1_coord = ref_coord_mx[1,],
                                                       point2_coord = ref_coord_mx[2,])
  slope <- lineCoef[1]
  # Step 3: computing the coordinates of circumcentre given the vertices 3-4-5
  point3_coord <- ref_coord_mx[3,]
  point4_coord <- ref_coord_mx[4,]
  point5_coord <- ref_coord_mx[5,]
  
  circumcentre <- compute_circumcentre_givenThreePoints(point1_coord = point3_coord,
                                                        point2_coord = point4_coord,
                                                        point3_coord = point5_coord)
  
  # Step 4: computing the coefficients of line splitting the line
  o <- computeParallelLineCoef(slope=slope,
                               point_coord = circumcentre)
  names(o) <- c("slope","intercept")
  if(returnRich==TRUE){
    return(list(coefOfSplit=o, avgMx=ref_coord_mx, circumcentre=circumcentre,radius=euc.dist(circumcentre,point3_coord),coefOf_1_2_Line=lineCoef))
  }
  else{
    return(o)
  }
}