R/RcppExports.R

In robiRagan/voteR: Spatial Voting Models in R

# Generated by using Rcpp::compileAttributes() -> do not edit by hand
# Generator token: 10BE3573-1514-4C36-9D1C-5A225CD40393

#' findICPoints
#' 
#' Takes an ideal point and and alternative and returns the requested number of
#' points that are on the indifference curve for the alternative. The function
#' can take into account different distance metrics, and the
#' salience voters have over the different issue dimensions.
#' 
#' Possible TODO: Could add a simplify from <boost/geometry/algorithms/simplify.hpp> to possibaly decrease the number of points in each IC.
#' 
#' @param idealPoint An ideal point for a voter.
#'   
#' @param altPointVector An alternative in the choice set.
#'   
#' @param orderScalar Order for the voter's distance metric. 1 is the Manhattan
#'   Distance, 2 is the Cartesian Distance and 100000 is the Chebechev
#'   Distance. You can choose any integer inbetween.
#'   
#' @param salienceVector The salience the voter has for each issue dimension. The element that
#'     coresponds to the least salient matrix is a 1 and all the other dimensions have their salience measured
#'     relative to that dimension. 
#' 
#' @param precision How precise you want the IC to be. The lower the precision the higher the number
#'     points on the IC that are found.
#'   
#' @return indifferencePoints A set of points that are on the indifference curve.
#' 
#' @export
#'
findICPoints <- function(voterID, idealPoint, altPointVector, orderScalar, salienceVector, precision = .01) {
    .Call('_voteR_findICPoints', PACKAGE = 'voteR', voterID, idealPoint, altPointVector, orderScalar, salienceVector, precision)
}

#' findParetoSet
#' 
#' Will find the pareto set in a two dimensional spatial voting model given a set of ideal points.
#' 
#' The pareto set of a set of ideal points is the convex hull of that set of
#' alternatives. This function will take a set of ideal points and returns
#' their convex hull as a matrix of points. The points are listed down the rows in clockwise
#' or counterclockwise order with the first and last element in the matrix being the same ideal point.
#' 
#' @param idealPoints A numberOfVoters x numberOfDimensions matrix of ideal points.
#' 
#' @return The set of points that constitutes the pareto set of the set of alternatives. The points are listed down the rows in clockwise
#' or counterclockwise order with the first and last element in the matrix being the same ideal point.
#' 
#' @export
findParetoSet <- function(idealPoints) {
    .Call('_voteR_findParetoSet', PACKAGE = 'voteR', idealPoints)
}

#' superElipseRadius
#' 
#' Returns the distance between the center of a super elipse and a point on the
#' elipse. The distance is mesured in the "order" of the superelipse. This
#' order is the same as the minkowski order for distance. 
#' 
#' @param idealPoint An ideal point for a voter.
#'   
#' @param altPoint An alternative in the choice set.
#'   
#' @param orderScalar Order for the voter's distance metric. 1 is the Manhattan
#'   Distance, 2 is the Cartesian Distance and 100000 is the Chebechev
#'   Distance. You can choose any integer inbetween.
#'   
#' @param salienceVector The salience the voter has for each issue dimension. The element that
#' coresponds to the least salient matrix is a 1 and all the other dimensions have their salience measured
#' relative to that dimension. 
#'   
#' @return indifferencePoints A set of points that are on the indifference curve.
#' @export
#' 
findSuperElipseRadius <- function(idealPoint, altPoint, orderScalar, salienceVector) {
    .Call('_voteR_findSuperElipseRadius', PACKAGE = 'voteR', idealPoint, altPoint, orderScalar, salienceVector)
}

#' findWinSet
#' 
#' Takes a set of indifference curves and returns the k-najority Rule WinSet. The IC's should be stored as a list
#' of DataFrames where each data framd in the list is the point set that constitutes the boundries of each voter's Indifference Curve. 
#' These ICs are usually generated by \code{\link{findICPoints}}
#' 
#' Possible TODO: 1) Could add a simplify at the begining from <boost/geometry/algorithms/simplify.hpp> to possibaly decrease the number of points in each IC.
#'                 2) Also could switch entire package to use Well Know Text as is used in the {sf} package. Then all polygons could be 
#'                 supplied as a single elements in a list (rather than as data frames in a list.)
#' 
#' @param indifferenceCurves A numberOffVoters list of data frames from R. Each data frame is the point set for a voters 
#'   
#' @param kToDefeatSQ A scalar indicating the number of indifference curves that must overlap to create the Win Set 
#'     (aka the k-majority rule).
#'  
#' @return winSetList A list of data frames where each data frame is a point set that defines one of the disjoint sets that are the 
#'     boundries of the win set. If there are less than two disjoint sets then the list will contain only one data frame. 
#' 
#' @export
#'
findWinSet <- function(indifferenceCurves) {
    .Call('_voteR_findWinSet', PACKAGE = 'voteR', indifferenceCurves)
}

#' isInICFromPointAndIC
#' 
#' This function takes an alternative and an indifference curve and checks to see if the
#' point is in the indifference curve. The more general function
#' \code{isInICFromPointAndIdeals()} will take an alternative and a set
#' of ideal points as its arguments.
#' 
#' @param aSexpPoint An R vector (SEXP) that contains the corrdinates of the
#'   alternative that you want to check.
#' @param aSexpMatrix An R matrix (SEXP) that contains all the points that
#'   define an indifference curve. The set of points should progress clockwise or
#'   counter clockwise as you go down the rows of the matrix and the first and
#'   last rows should of the matrix should be the same. The function
#'   \code{findICPoints()} generates a matrix that meets all of these
#'   requrements.
#' @return Logical that is TRUE if the alt is inside the agents indifference curve and FALSE if
#'   the alt is not inside the agents indifference curve. NOTE: Being inside the indifference curve 
#'   is equivalent to being in the agents preferred-to-set.
#' @export
isInICFromPointAndIC <- function(aSexpPoint, aSexpMatrix) {
    .Call('_voteR_isInICFromPointAndIC', PACKAGE = 'voteR', aSexpPoint, aSexpMatrix)
}

#' isInParetoSetFromPointAndIdeals
#' 
#' This function takes an alternative and a pareto set and checks to see if the
#' point is in the pareto set. The function \code{isInParetoSetFromPointAndPS()} 
#' will take an alternative and the set of points that define the pareto set and 
#' check if the alternative is in the pareto set.
#' 
#' @param aSexpPoint An R vector (SEXP) that contains the corrdinates of the
#'   alternative that you want to check.
#' @param aSexpMatrix An R matrix (SEXP) that contains the ideal points of the
#'   voters.
#' @return Logical that is TRUE if the alt is in the pareto set and FALSE of
#'   the alt is not in the pareto set.
#' @export
isInParetoSetFromPointAndIdeals <- function(aSexpPoint, aSexpMatrix) {
    .Call('_voteR_isInParetoSetFromPointAndIdeals', PACKAGE = 'voteR', aSexpPoint, aSexpMatrix)
}

#' isInParetoSetFromPointAndPS
#' 
#' This function takes an alternative and a pareto set and checks to see if the
#' point is in the pareto set. The more general function
#' \code{isInParetoSetFromPointAndIdeals()} will take an alternative and a set
#' of ideals as its arguments.
#' 
#' @param aSexpPoint An R vector (SEXP) that contains the corrdinates of the
#'   alternative that you want to check.
#' @param aSexpMatrix An R matrix (SEXP) that contains all the points that
#'   define a pareto set. The set of points should progress clockwise or
#'   counter clockwise as you go down the rows of the matrix and the first and
#'   last rows should of the matrix should be the same. The function
#'   \code{findParetoSet()} generates a matrix that meets all of these
#'   requrements.
#' @return Logical that is TRUE if the alt is in the pareto set and FALSE of
#'   the alt is not in the pareto set.
#' @export
isInParetoSetFromPointAndPS <- function(aSexpPoint, aSexpMatrix) {
    .Call('_voteR_isInParetoSetFromPointAndPS', PACKAGE = 'voteR', aSexpPoint, aSexpMatrix)
}

#' minkowskiDistancePairOfPoints
#' 
#' Calculates the sailence weighted Minkowski distance between a pair of points.
#' 
#' This function will find the salience weighted Minkowski Distance between a
#' pair of points. For example an ideal point and an alternative. 
#' 
#' @param idealsPoint A 1 x numberDimensions vector of numerics. Each column is a dimension in the policy space,
#'   <d1,d2,...dn>.
#'   
#' @param altPoint A 1 x numberDimensions vector of numerics. Each column is a dimension in the policy space,
#'   <d1,d2,...dn>. 
#'   
#' @param orderScalar The ``order" of the Minkowski Distance being used. In
#'   this packge it should be an element of [1,100]. Examples for cases where
#'   the salience on all dimensions is equal: 1 = Manhattan Distance.  diamond
#'   shaped indifference curves, perfect substitutes. 2 = Euclidian Distance.
#'   If salience on all dimensions is equal, circular indifference curves. 100
#'   = Aproximates Chebyshev Distance. If salience on all dimensions is equal
#'   square indifference curves, perfect compliments.
#'   
#' @param salienceVector A vector of doubles that is numberOfDimensions long: 
#'   <sd1, sd2, sd3, ... sdk>. Each element of the vector represents the 
#'   *relative* saliance of each dimension for the voter. The dimension with
#'   the lowest salience serves as the "numeraire" dimension and should recieve
#'   a salience of 1. All the other saliences are expressed in units of this 
#'   "numeraire". So if a dimension is twice as important to a voter as the 
#'   numeraire dimension it recieves a salience of 2. Example:  1 3 1. The
#'   salience of dimension 1 (or 3), is the numeraire, dimension 2 is three
#'   times as saient as dimension 1 and dimesnion 3 is equally as salient as
#'   dimension one.
#'   
#' @return distVector A 1 x numAlts matrix that contains the Minkowski
#'   Distance between the ideal point and alternative, weighted by a voter's salience
#'   and Minkowski order. The sailence and the Minkowski order together
#'   determine a voter's utility function.
#' @family minkowski
#' @family utility functions
#' @export
#' 
minkowskiDistancePairOfPoints <- function(idealVector, altVector, orderScalar, salienceVector) {
    .Call('_voteR_minkowskiDistancePairOfPoints', PACKAGE = 'voteR', idealVector, altVector, orderScalar, salienceVector)
}

#' minkowskiDistanceSets
#' 
#' Calculates the sailence weighted Minkowski distance between all combinations
#' of a set of voters and a set of alternatives in an n-dimensional space.
#' 
#' This function will find the salience weighted Minkowski Distance for a set
#' of voters whose ideal points are stacked in a numberVoters x
#' numberDimensions matrix and a set of alternatives that are stacked into a
#' numberAlternatives x numberDimensions matrix. Each voter can have a
#' different 'order' for their Minkowski Distance and a set of `sailence`
#' weights for each policy dimension.
#' 
#' @param idealsMatrix A numberVoters x numberDimensions matrix of numerics.
#'   Each row is a voter and each column is a dimension in the policy space,
#'   <d1,d2,...dn>. The values in a given row give the location of one voters
#'   ideal point, the point that is the argMax of their utility
#'   function.Example: In a two dimensional space the if entry in the matrix at
#'   location (v=2,d1=2,d=2) is <.5,.5> then the peak of voter 2's utility
#'   function in the two dimensional issue space is at .5,.5.
#'   
#' @param altsMatrix A numberAlts x numberDimensions matrix of numerics. Each
#'   row is an alternative and each column is a dimension in the policy space,
#'   <d1,d2,...dn>. The values in a given row give the location of that
#'   alternative in the policy space. Example: In a two dimensional space the
#'   if entry in the matrix at location (d=2,d1=2,d=2) is <.25,.75> then the
#'   location of that alternative in the two dimensional issue space is at
#'   .25,.75.
#'   
#' @param minkoOrderVector A numVoters length vector of doubles. It is the ``order" 
#'   of the Minkowski Distance being used. In this packge it should be an 
#'   element of [1,100]. Examples for cases where the salience on all 
#'   dimensions is equal: 1 = Manhattan Distance.  diamond shaped indifference
#'   curves, perfect substitutes. 2 = Euclidian Distance. If salience on all
#'   dimensions is equal, circular indifference curves. 100 = Aproximates
#'   Chebyshev Distance. If salience on all dimensions is equal square
#'   indifference curves, perfect compliments.
#'   
#' @param salienceMatrix A matrix of doubles that is numberOfDimensions long: 
#'   <sd1, sd2, sd3, ... sdk>. Each element of the vector represents the 
#'   *relative* saliance of each dimension for a voter. The dimension with the 
#'   lowest salience serves as the "numeraire" dimension and should recieve a 
#'   salience of 1. All the other saliences are expressed in units of this 
#'   "numeraire". So if a dimension is twice as important to a voter as the 
#'   numeraire dimension it recieves a salience of 2. Example: The second row
#'   is 1 2 3. This means that for voter two (second row) the salience of dimension 1 is the
#'   numeraire, dimension 2 is twice as saient as dimension 1 and
#'   dimension 3 is three times as salient as dimension one.
#'   
#' @return distMatrix A numVoters x numAlts matrix that contains the Minkowski
#'   Distance between each voter and each alternative, given a voter's salience
#'   and Minkowski order. The sailence and the Minkowski order together
#'   determine a voter's utility function.
#' @family minkowski
#' @family utility functions
#' @export
#' 
minkowskiDistanceSets <- function(idealsMatrix, altsMatrix, minkoOrderVector, salienceMatrix) {
    .Call('_voteR_minkowskiDistanceSets', PACKAGE = 'voteR', idealsMatrix, altsMatrix, minkoOrderVector, salienceMatrix)
}

#' minkowskiUtilitySets
#' 
#' Calculates the sailence weighted Minkowski utility for a set of voters and 
#' a set of alternatives in an 2-dimensional space.
#' 
#' This function will find the salience weighted Minkowski Utility for a set
#' of voters whose ideal points are stacked in a numberVoters x
#' numberDimensions matrix and a set of alternatives that are stacked into a
#' numberAlternatives x numberDimensions matrix. Each voter can have a
#' different 'order' for their Minkowski Distance, a set of `sailence`
#' weights for each policy dimension and a loss order. Each voter can have a
#' different loss order for their loss function. 
#' 
#' @param idealsMatrix A numberVoters x numberDimensions matrix of numerics.
#'   Each row is a voter and each column is a dimension in the policy space,
#'   <d1,d2,...dn>. The values in a given row give the location of one voters
#'   ideal point, the point that is the argMax of their utility
#'   function.Example: In a two dimensional space the if entry in the matrix at
#'   location (v=2,d1=2,d=2) is <.5,.5> then the peak of voter 2's utility
#'   function in the two dimensional issue space is at .5,.5.
#'   
#' @param altsMatrix A numberAlts x numberDimensions matrix of numerics. Each
#'   row is an alternative and each column is a dimension in the policy space,
#'   <d1,d2,...dn>. The values in a given row give the location of that
#'   alternative in the policy space. Example: In a two dimensional space the
#'   if entry in the matrix at location (d=2,d1=2,d=2) is <.25,.75> then the
#'   location of that alternative in the two dimensional issue space is at
#'   .25,.75.
#'   
#' @param minkoOrderVector A numVoters lengh vector of doubles. It is the ``order" 
#'   of the Minkowski Distance being used. In this packge it should be an 
#'   element of [1,100]. Examples for cases where the salience on all 
#'   dimensions is equal: 1 = Manhattan Distance.  diamond shaped indifference
#'   curves, perfect substitutes. 2 = Euclidian Distance. If salience on all
#'   dimensions is equal, circular indifference curves. 100 = Aproximates
#'   Chebyshev Distance. If salience on all dimensions is equal square
#'   indifference curves, perfect compliments.
#'   
#' @param salienceMatrix A matrix of doubles that is numberOfDimensions long: 
#'   <sd1, sd2, sd3, ... sdk>. Each element of the vector represents the 
#'   *relative* saliance of each dimension for a voter. The dimension with the 
#'   lowest salience serves as the "numeraire" dimension and should recieve a 
#'   salience of 1. All the other saliences are expressed in units of this 
#'   "numeraire". So if a dimension is twice as important to a voter as the 
#'   numeraire dimension it recieves a salience of 2. Example: The second row
#'   is 1 2 3. This means that for voter two (second row) the salience of dimension 1 is the
#'   numeraire, dimension 2 is twice as saient as dimension 1 and
#'   dimension 3 is three times as salient as dimension one.
#'
#' @param lossOrderVector A numVoters lengh vector of doubles. It is the ``order" 
#'   of the loss function being used. In short the Minkowski Distance is the way that
#'   a voter percieves the distance between their ideal point and another alternative. 
#'   The loss function tells us how that distance is converted into utility for the voter. 
#'   If lossOrderVector=1, then the voter has linear loss and their disutility for an
#'   alternative is equal to the minkowski distance. If lossOrderVector=2 then the voter has
#'   a quadratic loss function and their disutility is the square of the minkowski distance.
#'   This has the effect of causing utility to fall slowly at first as they evaluate alternatives
#'   closer to their ideal, but then once an alternative is sufficently far away utility falls much
#'   faster than in the linear case. 
#'   
#' @return utilMatrix A numVoters x numAlts matrix that contains the Minkowski
#'   Utility between each voter and each alternative, given a voter's salience, 
#'   Minkowski order and loss function. The sailence, Minkowski order and loss function
#'   together determine a voter's utility function.
#' @family minkowski
#' @family utility functions
#' @export
#' 
minkowskiUtilitySets <- function(idealsMatrix, altsMatrix, minkoOrderVector, lossOrderVector, salienceMatrix) {
    .Call('_voteR_minkowskiUtilitySets', PACKAGE = 'voteR', idealsMatrix, altsMatrix, minkoOrderVector, lossOrderVector, salienceMatrix)
}

#' Preferece Ording Using Minkowski Distance
#' @param idealsMatrix A numberVoters x numberDimensions matrix of numerics.
#'   Each row is a voter and each column is a dimension in the policy space,
#'   <d1,d2,...dn>. The values in a given row give the location of one voters
#'   ideal point, the point that is the argMax of their utility
#'   function.Example: In a two dimensional space the if entry in the matrix at
#'   location (v=2,d1=2,d=2) is <.5,.5> then the peak of voter 2's utility
#'   function in the two dimensional issue space is at .5,.5.
#'   
#' @param altsMatrix A numberAlts x numberDimensions matrix of numerics. Each
#'   row is an alternative and each column is a dimension in the policy space,
#'   <d1,d2,...dn>. The values in a given row give the location of that
#'   alternative in the policy space. Example: In a two dimensional space the
#'   if entry in the matrix at location (d=2,d1=2,d=2) is <.25,.75> then the
#'   location of that alternative in the two dimensional issue space is at
#'   .25,.75.
#'   
#' @param minkoOrderVector A numVoters lengh vector of doubles. It is the ``order" 
#'   of the Minkowski Distance being used. In this packge it should be an 
#'   element of [1,100]. Examples for cases where the salience on all 
#'   dimensions is equal: 1 = Manhattan Distance.  diamond shaped indifference
#'   curves, perfect substitutes. 2 = Euclidian Distance. If salience on all
#'   dimensions is equal, circular indifference curves. 100 = Aproximates
#'   Chebyshev Distance. If salience on all dimensions is equal square
#'   indifference curves, perfect compliments.
#'   
#' @param salienceMatrix A matrix of doubles that is numberOfDimensions long: 
#'   <sd1, sd2, sd3, ... sdk>. Each element of the vector represents the 
#'   *relative* saliance of each dimension for a voter. The dimension with the 
#'   lowest salience serves as the "numeraire" dimension and should recieve a 
#'   salience of 1. All the other saliences are expressed in units of this 
#'   "numeraire". So if a dimension is twice as important to a voter as the 
#'   numeraire dimension it recieves a salience of 2. Example: The second row
#'   is 1 2 3. This means that for voter two (second row) the salience of dimension 1 is the
#'   numeraire, dimension 2 is twice as saient as dimension 1 and
#'   dimension 3 is three times as salient as dimension one.
#'
#' @param lossOrderVector A numVoters lengh vector of doubles. It is the ``order" 
#'   of the loss function being used. In short the Minkowski Distance is the way that
#'   a voter percieves the distance between their ideal point and another alternative. 
#'   The loss function tells us how that distance is converted into utility for the voter. 
#'   If lossOrderVector=1, then the voter has linear loss and their disutility for an
#'   alternative is equal to the minkowski distance. If lossOrderVector=2 then the voter has
#'   a quadratic loss function and their disutility is the square of the minkowski distance.
#'   This has the effect of causing utility to fall slowly at first as they evaluate alternatives
#'   closer to their ideal, but then once an alternative is sufficently far away utility falls much
#'   faster than in teh quadratic case. 
#'   
#' @return prefMatrix A numVoters x numAlts matrix that contains the Minkowski
#'   Utility between each voter and each alternative, given a voter's salience, 
#'   Minkowski order and loss function. The sailence, Minkowski order and loss function
#'   together determine a voter's utility function.
#' @family minkowski
#' @family utility functions
prefOrderMinko <- function(idealsMatrix, altsMatrix, minkoOrderVector, salienceMatrix, lossOrderVector) {
    .Call('_voteR_prefOrderMinko', PACKAGE = 'voteR', idealsMatrix, altsMatrix, minkoOrderVector, salienceMatrix, lossOrderVector)
}

#' sgn
#' 
#' Returns the signum of the supplied arguement
#' 
#' @param aScalar
#'   
#' @return Sign of supplied scalar.
#' @export
#' 
sgn <- function(aScalar) {
    .Call('_voteR_sgn', PACKAGE = 'voteR', aScalar)
}

#' superElipseRadius
#' 
#' Returns the distance between the center of a super elipse and a point on the
#' elipse. The distance is mesured in the "order" of the superelipse. This
#' order is the same as the minkowski order for distance. 
#' 
#' @param idealPoint An ideal point for a voter.
#'   
#' @param altPoint An alternative in the choice set.
#'   
#' @param orderScalar Order for the voter's distance metric. 1 is the Manhattan
#'   Distance, 2 is the Cartesian Distance and 100000 is the Chebechev
#'   Distance. You can choose any integer inbetween.
#'   
#' @param salienceVector The salience the voter has for each issue dimension. The element that
#' coresponds to the least salient matrix is a 1 and all the other dimensions have their salience measured
#' relative to that dimension. 
#' 
#' @param granularity The number of points on the indifference curve the function should report back. 
#'   
#' @return indifferencePoints A set of points that are on the indifference curve.
#' @export
#' 
superElipseRadius <- function(idealPoint, altPoint, orderScalar, salienceVector) {
    .Call('_voteR_superElipseRadius', PACKAGE = 'voteR', idealPoint, altPoint, orderScalar, salienceVector)
}

# Register entry points for exported C++ functions
methods::setLoadAction(function(ns) {
    .Call('_voteR_RcppExport_registerCCallable', PACKAGE = 'voteR')
})