##########################################################################################################
# THREADNET:  Metrics

# This software may be used according to the terms provided in the
# GNU General Public License (GPL-3.0) https://opensource.org/licenses/GPL-3.0?
# Absolutely no warranty!
##########################################################################################################
# Functions for metrics:  entropy, complexity, routine-ness, etc.


# takes the output from the function that maps threads to networks
#' Estimates the number of paths in a directed graph
#'
#' This function takes a network descripts (nodes and edges, as generaged by the functino threads_to_network, and estimates the number of paths.
#' as described in Haerem, Pentland and Miller (2015). The estimate correlates with the McCabe's (1975) cyclometric complexity.
#'
#' @family ThreadNet_Metrics
#'
#' @param net
#'
#' @return number
#' @export
#'
#' @examples
estimate_network_complexity <- function(net){ return(estimate_task_complexity_index( nrow(net$nodeDF), nrow(net$edgeDF)) ) }

# this version takes vertices and edges
#' Estimates the number of paths in a directed graph
#'
#' Same as estimate_network_complexity, but takes different parameters
#'
#' @family ThreadNet_Metrics
#'
#' @param v number of vertices (or nodes)
#' @param e number of edges
#'
#' @return number
#' @export
estimate_task_complexity_index <- function(v,e){

  #INPUT ARGS:
  # in MatLab version, arguments were v (vertices) and e (edges)
  # v = number of vertices
  # tested for range of 10 < v < 100
  # e = number of edges
  print("edges")
  print(e)
  print("vertices")
  print(v)
  #
  # OUTPUT ARG:
  # cidx correlates with Log10(simple paths) with r>= 0.8

  # from ORM paper analysis, constant is 0.12.
  # For boundary condition of 2 nodes and 1 edge, complexity index=0, constant = 0.08
  return(  0.08 + 0.08*e - 0.08*v )
}


#################################################################
#' Computes a metric of routineness based on frequency of ngrams
#'
#' Computes the fraction of observed behavior that conforms to an observed pattern.
#' Current version uses ngrams, but it would be good to use spmf pattern mining to avoid including duplicate patterns  (e.g., a-b-c and b-c-d)
#'
#' @family ThreadNet_Metrics
#'
#' @param o  data frame with occurresnces or events
#' @param TN  name of column with threadNumbers
#' @param CF name of column with contextual factor
#' @param n size of ngram
#' @param m how many of the most frequent ngrams to include. When m > 1, there is a risk of duplication.
#'
#' @return number, index of routineness.
#'
#' @export
routineness_metric <- function(o,TN,CF,n,m){

  # get the ngrams
  ng=count_ngrams(o,TN,CF,n)

# print(ng[1:m,])

  # return the ratio of occurrences in the top m most frequent ngrams to total occurrences
    return( sum(ng$freq[1:m])*n/nrow(o) )
}


#############################################################################
#' Computes the compressibility of the data in one column of a data frame
#'
#' Compressibility is an index of complexity -- more compressible means less complex.  This function computes the ratio of compressed data
#' to the original data.  Should be between zero and one.  Uses built-in functions for in=memory compression
#'
#' @family ThreadNet_Metrics
#'
#' @param df  a data frame containing occurrences or events
#' @param CF  a column or contextual factor in that data frame
#'
#' @return number containing compressibility index, 0 < i < 1
#' @export
compression_index <- function(df,CF){ return(
    length(memCompress(paste0(as.character(df[[CF]])),type="gzip")) /
    length(paste0(as.character(df[[CF]]))) ) }


#######################################################################
#compute entropy for a set of observations in a column from a data frame
# freq is typically going to the $freq column from ngram table, or
# the frequency of each level in the CFs, as counted by table()
#' Compute the entropy of a contextual factor
#'
#' Each column in the raw data represents a contextual factor.  This function computes the entropy of each factor that is selected for use in the
#' analysis.
#' @family ThreadNet_Metrics
#'
#' @param freq is the frequency distribution of the levels in the factor
#'
#' @return number
#' @export
compute_entropy <- function(freq){
  N = sum(freq)
  p = freq/N
  plnp = p*log(p)
  return(-sum(plnp))
}