R/Path_Strength-Yang_Knoke.R

In davidbuch/sconduct: A Suite of Functions for Generalized Path Analysis

#' Calculates the Binary Distance of a network path.
#' 
#' Calculates the binary distance of a user-specified network path,
#' or the minimum over all possible paths if only a source and 
#' target node are specified.
#' 
#' If a path is specified, \code{binary_distance} will merely return the 
#' length of the path, so long as the specified edges are present 
#' in the sociomatrix. If an edge is not present, \code{binary_distance}
#' will return \code{Inf}, signifying that the path is not traversable.
#' 
#' If no path is specified, \code{binary_distance} uses Dijkstra's algorithm 
#' to identify the shortest path from \code{source} to \code{target} on 
#' a binary graph generated from the nonzero entries of the user-provided sociomatrix.
#'
#' @param sociomatrix a nonnegative, real valued sociomatrix
#' @param path optional, a vector of integer indices corresponding to nodes of the sociomatrix. 
#' @param source optional, user must also specify a target node.
#' @param target optional, user must also specify a source node.
#' @return The binary distance along \code{path} or minimum binary distance between \code{source} and \code{target}
#' 
#' @examples
#' ## Calculate binary distance between nodes of a sociomatrix
#' binary_distance(sociomatrix = YangKnoke, source = 1, target = 3)
#' 
#' ## Calculate binary distance along a path in a sociomatrix
#' binary_distance(sociomatrix = YangKnoke, path = c(1,2))
binary_distance <- function(sociomatrix, path = NULL, source = NULL, target = NULL){
  check_input(sociomatrix, path, source, target, p_norm = 1)
  if(is.null(path)){
    # If no path is provided, provide the binary path of least resistance
    binary_sociomatrix <- as_binary(sociomatrix)
    path <- shortest_path(1/binary_sociomatrix, source, target, p_norm = 1)
  }
  return(length(path) - 1)## FIX THIS!!!!!!! Doesn't work if path doesn't exist!!!!!
}

#'
#'
#'
#'@family historic path strengths
#' 
peay_path_value <- function(sociomatrix, path = NULL, source = NULL, target = NULL){
  check_input(sociomatrix, path, source, target, p_norm = Inf)
  if(is.null(path)){
    # No path specified. Defaulting to path of greatest Peay Path Value.
    path <- shortest_path(1/sociomatrix, source, target, p_norm = Inf)
  }
  tie_strength <- get_tie_strengths(sociomatrix, path)
  return(min(tie_strength))
}

flament_path_length <- function(sociomatrix, path = NULL, source = NULL, target = NULL){
  check_input(sociomatrix, path, source, target, p_norm = 1)
  message("This method is provided for historical context and comparison, but
          it is not clear from Flament (1963) how Flament Path Length (FPL) should be interpreted.
          On binary graphs, it is equivalent to binary distance.")
  if(is.null(path)){
    warning("No path specified. Defaulting to path of least resistance.")
    path <- shortest_path(1/sociomatrix, source, target, p_norm = 1)
  }
  tie_strength <- get_tie_strengths(sociomatrix, path)
  return(sum(tie_strength))
}

peay_average_path_value <- function(sociomatrix, path = NULL, source = NULL, target = NULL){
  check_input(sociomatrix, path, source, target, p_norm = Inf)
  if(is.null(path)){
    # "No path specified. Defaulting to path of greatest Peay Path Value
    path <- shortest_path(1/sociomatrix, source, target, p_norm = Inf)
  }
  # Number of Edges in a path = number of vertices - 1
  return(peay_path_value(sociomatrix, path, source, target)/(length(path) - 1))
}

flament_average_path_length <- function(sociomatrix, path = NULL, source = NULL, target = NULL){
  check_input(sociomatrix, path, source, target, p_norm = 1)
  if(is.null(path)){
    message("No path specified. Defaulting to path of least resistance.")
    path <- shortest_path(1/sociomatrix, source, target, p_norm = 1)
  }
  return(flament_path_length(sociomatrix, path, source, target)/(length(path) - 1))
}