Extensive updates to the package documentation. In particular, making…

… sure that all functions list what values they return.

NAMESPACE

@@ -5,6 +5,7 @@ S3method(get_data,ds_generalization)
 S3method(get_parameters,cl_max_correlation)
 S3method(get_parameters,cl_poisson_naive_bayes)
 S3method(get_parameters,cl_svm)
+S3method(get_parameters,cv_standard)
 S3method(get_parameters,ds_basic)
 S3method(get_parameters,ds_generalization)
 S3method(get_parameters,fp_select_k_features)
@@ -49,6 +50,7 @@ export(read_raster_data)
 export(rm_confusion_matrix)
 export(rm_main_results)
 export(run_decoding)
+export(test_valid_ndr_object)
 export(test_valid_raster_format)
 import(dplyr)
 import(foreach)

R/cl_max_correlation.R

@@ -3,15 +3,15 @@
 #' An implementation of a maximum correlation coefficient classifier.
 #' 
 #' @param ndr_container_or_object The purpose of this argument is to make the
-#'   constructor of the cl_maximum_correlation classifier work with the
-#'   magrittr pipe (%>%) operator. This argument should almost never be directly
-#'   set by the user to anything other than NULL. If this is set to the default
-#'   value of NULL, then the constructor will return a cl_max_correlation
-#'   object. If this is set to an ndr container, then a cl_max_correlation
-#'   object will be added to the container and the container will be returned.
-#'   If this argument is set to another ndr object, then both that ndr object as
-#'   well as a new cl_maximum_correlation object will be added to a new
-#'   container and the container will be returned.
+#'   constructor of the cl_maximum_correlation classifier work with the pipe
+#'   (|>) operator. This argument should almost never be directly set by the
+#'   user to anything other than NULL. If this is set to the default value of
+#'   NULL, then the constructor will return a cl_max_correlation object. If this
+#'   is set to an NDT container, then a cl_max_correlation object will be added
+#'   to the container and the container will be returned. If this argument is
+#'   set to another NDT object, then both that NDR object as well as a new
+#'   cl_maximum_correlation object will be added to a new container and the
+#'   container will be returned.
 #'   
 #' @param return_decision_values A Boolean specifying whether the prediction
 #'   function should return columns that have the decision values. Setting this
@@ -21,6 +21,12 @@
 #'   decision values; e.g., the rm_main_results object won't be able to
 #'   calculate normalized rank decision values.
 #'
+#' @return This constructor creates an NDR classifier object with the class
+#'   `cl_max_correlation`. Like all NDR classifier objects, this classifier will
+#'   be used by a cross-validator to learn the relationship between neural
+#'   activity and experimental conditions on a training set of data, and then it
+#'   will be used to make predictions on a test set of data.
+#'
 #' @details This CL object learns a mean population vector (template) for each
 #'   class from the training set (by averaging together the all training points
 #'   within each class). The classifier is tested by calculated Pearson’s
@@ -30,9 +36,9 @@
 #'   classifier are the correlation coefficients between all test points and all
 #'   templates.
 #'
-#' Like all classifiers (CL) objects, this classifier has a get_predictions()
-#' method which learns a model based on training data and then makes predictions
-#' on the test data.
+#' Like all classifiers (CL) objects, this classifier has a private
+#' get_predictions() method which learns a model based on training data and then
+#' makes predictions on the test data.
 #'
 #'
 #' @examples
@@ -79,12 +85,12 @@ cl_max_correlation <- function(ndr_container_or_object = NULL,
 
 
 # the get_predictions method
+#' @inherit get_predictions
 #' @export
 get_predictions.cl_max_correlation <- function(cl_obj,
                                                training_set,
                                                test_set) {
 
-
   ### Train the classifier  ---------------------------------------------------
   prototypes <- training_set %>%
     dplyr::group_by(.data$train_labels) %>%
@@ -130,8 +136,12 @@ get_predictions.cl_max_correlation <- function(cl_obj,
 }
 
 
+
+
+
 # since there are no parameters for the cl_max_correlation, just return a data
 # frame with one variable with a value that there are not settable parameters
+#' @inherit get_parameters
 #' @export
 get_parameters.cl_max_correlation <- function(ndr_obj) {
   data.frame(cl_max_correlation.cl_max_correlation = "does not have settable parameters")

R/cl_poisson_naive_bayes.R

@@ -21,6 +21,12 @@
 #'   decision values; e.g., the rm_main_results object won't be able to
 #'   calculate normalized rank decision values.
 #'
+#' @return This constructor creates an NDR classifier object with the class
+#'   `cl_poisson_naive_bayes`. Like all NDR classifier objects, this classifier
+#'   will be used by a cross-validator to learn the relationship between neural
+#'   activity and experimental conditions on a training set of data, and then it
+#'   will be used to make predictions on a test set of data.
+#'
 #'
 #' @details
 #'
@@ -71,7 +77,6 @@
 
 
 
-
 # the constructor
 #' @export
 cl_poisson_naive_bayes <- function(ndr_container_or_object = NULL,
@@ -88,6 +93,9 @@ cl_poisson_naive_bayes <- function(ndr_container_or_object = NULL,
 
 
 
+
+# the get_predictions method
+#' @inherit get_predictions
 #' @export
 get_predictions.cl_poisson_naive_bayes <- function(cl_obj, training_set, test_set) {
 
@@ -167,8 +175,10 @@ get_predictions.cl_poisson_naive_bayes <- function(cl_obj, training_set, test_se
 
 
 
+
 # since there are no parameters for the cl_poisson_naive_bayes just return a data
 # frame with cl_poisson_naive_bayes.cl_poisson_naive_bayes saying no params...
+#' @inherit get_parameters
 #' @export
 get_parameters.cl_poisson_naive_bayes <- function(ndr_obj) {
   data.frame(cl_poisson_naive_bayes.cl_poisson_naive_bayes = "does not have settable parameters")

R/cl_svm.R

@@ -43,11 +43,16 @@
 #'   decision values; e.g., the rm_main_results object won't be able to
 #'   calculate normalized rank decision values.
 #'
-#'
 #' @param ... All parameters that are available in the e1071 package svm()
 #'   object should work with this CL object.
 #'
 #'
+#' @return This constructor creates an NDR classifier object with the class
+#'   `cl_svm`. Like all NDR classifier objects, this classifier will be used by
+#'   a cross-validator to learn the relationship between neural activity and
+#'   experimental conditions on a training set of data, and then it will be used
+#'   to make predictions on a test set of data.
+#'
 #'
 #' @examples
 #' # using the default e1071 parameters
@@ -85,6 +90,8 @@ cl_svm <- function(ndr_container_or_object = NULL,
 
 
 
+# the get_predictions method
+#' @inherit get_predictions
 #' @export
 get_predictions.cl_svm <- function(cl_obj, training_set, test_set) {
 
@@ -172,6 +179,7 @@ get_predictions.cl_svm <- function(cl_obj, training_set, test_set) {
 
 
 # Get the parameters that were used in the svm
+#' @inherit get_parameters
 #' @export
 get_parameters.cl_svm <- function(ndr_obj) {
 

R/create_binned_data.R

@@ -38,6 +38,10 @@
 #'   to use. The default (NULL) value is to use half of the cores detected on
 #'   the system. If this value is set to a value of less than 1, then the code
 #'   will be run serially.
+#'   
+#' @return Returns a string with the name of the file that was created which has
+#'   the data in binnned format.
+#'   
 #'
 #' @examples
 #' # create binned data with 150 ms bin sizes sampled at 10 ms intervals

R/cv_standard.R

@@ -61,6 +61,10 @@
 #'   string the output will be written to the screen, otherwise it will be
 #'   written to a file name specified. See parallel::makeCluster for more
 #'   details.
+#'   
+#' @return This constructor creates an NDR cross-validator object with the class
+#'   `cv_standard`. Like all NDR cross-validator objects, one should use
+#'   `run_decoding` method to run a decoding analysis.
 #'
 #' @examples
 #' data_file <- system.file("extdata/ZD_150bins_50sampled.Rda",
@@ -251,7 +255,7 @@ new_cv_standard <- function(datasource,
 
 
 
-
+#' @inherit run_decoding
 #' @export
 run_decoding.cv_standard <- function(cv_obj) {
 
@@ -469,6 +473,8 @@ run_decoding.cv_standard <- function(cv_obj) {
 
 # get parameters from all objects and save the in a data frame so that
 # which will be useful to tell if an analysis has already been run
+#' @inherit get_parameters
+#' @export
 get_parameters.cv_standard <- function(ndr_obj) {
 
 

R/ds_basic.R

@@ -60,6 +60,10 @@
 #'   get_data() function to return simultaneous populations rather than
 #'   pseudo-populations.
 #'
+#' @return This constructor creates an NDR datasource object with the class
+#'   `ds_basic`. Like all NDR datasource objects, this datasource will be used
+#'   by the cross-validator to generate training and test data sets.
+#'
 #'
 #' @examples
 #' # A typical example of creating a datasource to be passed cross-validation object
@@ -78,6 +82,12 @@
 #'   label_levels = c("car", "hand", "kiwi")
 #' )
 #'
+#' # One never explicitly calls the get_data() function, but rather this is
+#' # called by the cross-validator. However, to illustrate what this function
+#' # does, we can call it explicitly here to get training and test data:
+#' all_cv_data <- get_data(ds)
+#' names(all_cv_data)
+#'
 #' @family datasource
 #'
 
@@ -293,6 +303,7 @@ ds_basic <- function(binned_data,
 
 
 
+#' @inherit get_data
 #' @export
 get_data.ds_basic <- function(ds_obj) {
 
@@ -432,6 +443,7 @@ get_data.ds_basic <- function(ds_obj) {
 
 
 
+#' @inherit get_parameters
 #' @export
 get_parameters.ds_basic <- function(ndr_obj) {
 

R/ds_generalization.R

@@ -60,6 +60,9 @@
 #'   get_data() function to return simultaneous populations rather than
 #'   pseudo-populations.
 #'
+#' @return This constructor creates an NDR datasource object with the class
+#'   `ds_generalization`. Like all NDR datasource objects, this datasource will
+#'   be used by the cross-validator to generate training and test data sets.
 #'
 #' @examples
 #' # One can test if a neural population contains information that is position
@@ -179,6 +182,7 @@ ds_generalization <- function(binned_data,
 
 
 
+#' @inherit get_data
 #' @export
 get_data.ds_generalization <- function(ds_obj) {
 
@@ -262,6 +266,7 @@ get_data.ds_generalization <- function(ds_obj) {
 
 
 
+#' @inherit get_parameters
 #' @export
 get_parameters.ds_generalization <- function(ndr_obj) {
 

R/fp_select_k_features.R

@@ -24,6 +24,12 @@
 #'
 #' @param num_sites_to_exclude The number of features with the smallest p-values
 #'   that should be excluded.
+#'   
+#' @return This constructor creates an NDR feature preprocessor object with the
+#'   class `fp_select_k_features`. Like all NDR feature preprocessor objects,
+#'   this feature preprocessor will be used by the cross-validator to
+#'   pre-process the training and test data sets.
+#'   
 #'
 #' @examples
 #' # This will cause the cross-validator use only the 50 most selective sites
@@ -70,6 +76,7 @@ fp_select_k_features <- function(ndr_container_or_object = NULL,
 
 
 
+#' @inherit preprocess_data
 #' @export
 preprocess_data.fp_select_k_features <- function(fp, training_set, test_set) {
 
@@ -147,6 +154,7 @@ preprocess_data.fp_select_k_features <- function(fp, training_set, test_set) {
 
 
 
+#' @inherit get_parameters
 #' @export
 get_parameters.fp_select_k_features <- function(ndr_obj) {
   data.frame(

R/fp_zscore.R

@@ -14,6 +14,12 @@
 #'   container and the container will be returned. If this argument is set to
 #'   another ndr object, then both that ndr object as well as a new fp_zscore
 #'   object will be added to a new container and the container will be returned.
+#'   
+#' @return This constructor creates an NDR feature preprocessor object with the
+#'   class `fp_zscore`. Like all NDR feature preprocessor objects, this feature
+#'   preprocessor will be used by the cross-validator to pre-process the
+#'   training and test data sets.
+#'   
 #'
 #' @details This feature preprocessor object applies z-score normalization to
 #' each feature by calculating the mean and the standard deviation for each
@@ -47,6 +53,7 @@ fp_zscore <- function(ndr_container_or_object = NULL) {
 
 
 
+#' @inherit preprocess_data
 #' @export
 preprocess_data.fp_zscore <- function(fp, training_set, test_set) {
 
@@ -90,6 +97,7 @@ preprocess_data.fp_zscore <- function(fp, training_set, test_set) {
 
 # since there are no parameters for the fp_zscore just return a data frame with
 # fp_zscore.fp_zscore and a value of "No parameters"
+#' @inherit get_parameters
 #' @export
 get_parameters.fp_zscore <- function(ndr_obj) {
   data.frame(fp_zscore.fp_zscore = "does not have settable parameters")