rra {iRRA} | R Documentation |
This is the main function of the iRRA package. It builds the Region of Interest (RoI) given the
coordinates of the ROC curve, the number of actual positives (AP
) and actual negatives (AN
) and
the reference values of the performance metrics, and then it computes the Ratio of Relevant Areas (RRA). It returns a "rra_result" object,
a named list of "rra_result" class. This object can be printed and plotted. Additionally, two "rra_result" object can be compared
(rra.test
) and a list of "rra_result" objects can be averaged out by rra.average
rra(roc_x, roc_y, AP, AN, precision = FALSE, c_precision = "pop", p_precision = -1, recall = FALSE, c_recall = "pop", p_recall = -1, fm = FALSE, c_fm = "pop", p_fm = -1, npv = FALSE, c_npv = "pop", p_npv= -1, specificity = FALSE, c_specificity = "pop", p_specificity = -1, fallout = FALSE, c_fallout = "pop", p_fallout = -1, nm = FALSE, c_nm = "pop", p_nm = -1, j = FALSE, c_j = -1, markedness = FALSE, c_markedness = -1, phi = FALSE, c_phi = 0.4, ncost = FALSE, c_ncost = "uses_mu", lambda = c(-1), mu = 1, print = TRUE, plot = TRUE, ...)
roc_x |
The |
roc_y |
The |
AP |
The number of actual positives. This value represents the number of positive responses (the "1" values) used to build the ROC curve. It must be greater than |
AN |
The number of actual negatives. This value represents the number of negative responses (the "0" values) used to build the ROC curve. It must be greater or equal to |
precision |
If the user wants to use a precision reference value to build the Region of Interest |
c_precision |
The reference value. It must be between |
p_precision |
The unified probability used by the |
recall |
If the user wants to use a recall reference value to build the Region of Interest |
c_recall |
The reference value. It must be between |
p_recall |
The unified probability used by the |
fm |
If the user wants to use a F-Measure (FM) reference value to build the Region of Interest |
c_fm |
The reference value. It must be between |
p_fm |
The unified probability used by the |
npv |
If the user wants to use a Negative Predictive Value (NPV) reference value to build the Region of Interest |
c_npv |
The reference value. It must be between |
p_npv |
The unified probability used by the |
specificity |
If the user wants to use a F_Measure (FM) reference value to build the Region of Interest |
c_specificity |
The reference value. It must be between |
p_specificity |
The unified probability used by the |
fallout |
If the user wants to use a Fall-out (or False Positive Rate) reference value to build the Region of Interest |
c_fallout |
The reference value. It must be between |
p_fallout |
The unified probability used by the |
nm |
If the user wants to use a Negative-F-Measure (NM) reference value to build the Region of Interest |
c_nm |
The reference value. It must be between |
p_nm |
The unified probability used by the |
j |
If the user wants to use a Youden's J reference value to build the Region of Interest |
c_j |
The reference value. It must be between |
markedness |
If the user wants to use a Markedness reference value to build the Region of Interest |
c_markedness |
The reference value. It must be between |
phi |
If the user wants to use a Matthews Correlation Coefficient (phi) reference value to build the Region of Interest |
c_phi |
The reference value. It must be between |
ncost |
If the user wants to use a Normalized Cost (NC) reference value to build the Region of Interest |
c_ncost |
The reference value. It must be between |
lambda |
The value of False Negative and False Positive cost ratio as |
mu |
The reduction cost index value. It's used only if |
print |
If the user wants to print the result. For more information, check |
plot |
If the user wants to plot the ROC curve and the RoI. For more information, check |
... |
Other arguments for |
The Region of Interest (RoI) represents the points in the ROC space that have a better performance value than the reference values.
Every performance metrics corresponds to a specific border of the RoI. It is possible to use multiple metrics and different methods, but it is important to keep in mind that some border could be always greater than others within the ROC space. In this case some borders will obscure the others.
Additionally, some special values will be not very significant. For instance, a recall reference value of 1
will result in a non-existent RoI. Its RRA will be 0
unless the ROC curve is perfect (AUC = 1
). On the other hand, if recall is equal to 0
the RoI will correspond to the ROC space, therefore the RRA will be equal to the AUC of the ROC curve.
The default value for phi
, 0.4
, represents a medium-strong association between a model and actual positiveness.
A "rra_result" object contains the points of the ROC curve, the coordinates of the RoI and the RoI under the curve, the RRA value and the list of the performance metrics considered
The function will stop if roc_x
and roc_y
have different length or have values greater than 1
or lesser than 0
. It will also stop if the other parameters have invalid values
Note that the precision("uni") border will be y=x
for every p(m). For this reason, using c_precision = "uni", p_precision = (0<p<1)
will generate the same border as using c_precision = "pop"
. This is also true for the NPV border
rra.plot
, rra.print
, rra.test
, rra.average
## Not run: # They can be run if one has the ROC curve's coordinates and the AP and AN values. rra(roc_x, roc_y, AP, AN, recall = TRUE, fallout = TRUE) # The RoI represents all the points that have a better recall and fall-out value than the #"pop" values rra(roc_x, roc_y, AP, AN, ncost = TRUE, lambda = c(0.4,0.6), mu = 0.9, plot = FALSE) # The RoI represents all the points that have a better NC than the NC("pop")*0.9 value with lambda between 0.4 and 0.6. Its borders are two lines. This RoI won't be plotted rra(roc_x, roc_y, AP, AN) # This will warn the user that no performance metric has been selected. It will return the # AUC value. > Warning message: > In rra(roc$x, roc$y, app, ann) : > No performance metrics have been selected. The AUC value of the ROC curve has been returned rra(roc_x, roc_y, AP, AN, phi = TRUE, precision = TRUE) # In this case phi = 0.4 will generate a curve that is always greater than y=x # (precision("pop") border). # Precision will not contribute to the generation of the RoI rra(roc_x, roc_y, AP, AN, recall = TRUE, fallout = TRUE, colUnder = "red") # A parameter for the rra.plot function is used. The RoI under the ROC curve will # be red instead of light blue ## End(Not run)