Merge pull request #77 from albersonmiranda/docs

docs: review documentation

R/addin.R

@@ -1,11 +1,4 @@
-#' Conveniently import data from an Excel file
-#'
-#' @description `fio_addin()` opens an [RStudio
-#'  gadget](https://shiny.rstudio.com/articles/gadgets.html) and
-#'  [addin](https://rstudio.github.io/rstudioaddins/) that allows you to say
-#'  where the data source is (either clipboard or Excel file) and import the
-#'  data into the global environment.
-#'  Appears as "Import input-output data" in the RStudio Addins menu.
+#' @noRd
 
 # nocov start
 input_options <- shiny::selectInput(
@@ -32,6 +25,15 @@ input_options <- shiny::selectInput(
   )
 )
 
+#' Conveniently import data from an Excel file
+#'
+#' @description `fio_addin()` opens an [RStudio
+#'  gadget](https://shiny.rstudio.com/articles/gadgets.html) and
+#'  [addin](https://rstudio.github.io/rstudioaddins/) that allows you to say
+#'  where the data source is (either clipboard or Excel file) and import the
+#'  data into the global environment.
+#'  Appears as "Import input-output data" in the RStudio Addins menu.
+
 fio_addin <- function() {
   rlang::check_installed(
     c("shiny", "miniUI"),

R/extendr-wrappers.R

@@ -49,7 +49,7 @@ set_max_threads <- function(max_threads) invisible(.Call(wrap__set_max_threads,
 #' A \eqn{1 x n} vector of total production.
 #' 
 #' @details
-#' It calculates the technical coefficients matrix, which is the columnwise ratio of
+#' It computes the technical coefficients matrix, which is the columnwise ratio of
 #' intermediate transactions to total production \insertCite{leontief_economia_1983}{fio}.
 #' 
 #' @return
@@ -78,7 +78,7 @@ compute_tech_coeff <- function(intermediate_transactions, total_production) .Cal
 #' A \eqn{n x n} matrix of technical coefficients.
 #' 
 #' @details
-#' It calculates the Leontief inverse matrix \insertCite{leontief_economia_1983}{fio}, which is the inverse of the
+#' It computes the Leontief inverse matrix \insertCite{leontief_economia_1983}{fio}, which is the inverse of the
 #' Leontief matrix. The formula is:
 #' 
 #' \deqn{L = I - A}
@@ -113,50 +113,50 @@ compute_tech_coeff <- function(intermediate_transactions, total_production) .Cal
 #' my_iom$leontief_inverse_matrix
 compute_leontief_inverse <- function(tech_coeff) .Call(wrap__compute_leontief_inverse, tech_coeff)
 
-#' Calculates type I output multiplier.
+#' Computes type I output multiplier.
 #' @param leontief_inverse_matrix The open model Leontief inverse matrix.
 #' @return A 1xn vector of type I output multipliers.
 compute_multiplier_output <- function(leontief_inverse_matrix) .Call(wrap__compute_multiplier_output, leontief_inverse_matrix)
 
-#' Calculates direct output multiplier.
+#' Computes direct output multiplier.
 #' @param technical_coefficients_matrix The open model technical coefficients matrix.
 #' @return A 1xn vector of direct output multipliers.
 compute_multiplier_output_direct <- function(technical_coefficients_matrix) .Call(wrap__compute_multiplier_output_direct, technical_coefficients_matrix)
 
-#' Calculates indirect output multiplier.
+#' Computes indirect output multiplier.
 #' @param technical_coefficients_matrix The open model technical coefficients matrix.
 #' @param leontief_inverse_matrix The open model Leontief inverse matrix.
 #' @return A 1xn vector of indirect output multipliers.
 compute_multiplier_output_indirect <- function(technical_coefficients_matrix, leontief_inverse_matrix) .Call(wrap__compute_multiplier_output_indirect, technical_coefficients_matrix, leontief_inverse_matrix)
 
-#' Calculates requirements for a given added value vector
+#' Computes requirements for a given added value vector
 #' @param added_value_element An added value vector.
 #' @param total_production The total production vector.
 #' @return A 1xn vector of a given added value coefficients.
 compute_requirements_added_value <- function(added_value_element, total_production) .Call(wrap__compute_requirements_added_value, added_value_element, total_production)
 
-#' Calculates generator matrix for a given added value vector.
+#' Computes generator matrix for a given added value vector.
 #' @param added_value_requirements The coefficients for a given added value vector.
 #' @param leontief_inverse_matrix The open model Leontief inverse matrix.
 #' @return A nxn matrix of an added value vector generator.
 compute_generator_added_value <- function(added_value_requirements, leontief_inverse_matrix) .Call(wrap__compute_generator_added_value, added_value_requirements, leontief_inverse_matrix)
 
-#' Calculates multiplier for a given added value vector.
+#' Computes multiplier for a given added value vector.
 #' @param added_value_requirements The coefficients for a given added value vector.
 #' @param leontief_inverse_matrix The open model Leontief inverse matrix.
 compute_multiplier_added_value <- function(added_value_requirements, leontief_inverse_matrix) .Call(wrap__compute_multiplier_added_value, added_value_requirements, leontief_inverse_matrix)
 
-#' Calculates indirect multiplier for a given added value vector.
+#' Computes indirect multiplier for a given added value vector.
 #' @param added_value_element An added value vector.
 #' @param total_production The total production vector.
 #' @param leontief_inverse_matrix The open model Leontief inverse matrix.
 #' @return A 1xn vector of indirect multipliers for a given added value vector.
 compute_multiplier_added_value_indirect <- function(added_value_element, total_production, leontief_inverse_matrix) .Call(wrap__compute_multiplier_added_value_indirect, added_value_element, total_production, leontief_inverse_matrix)
 
-#' Calculates field of influence given a technical change.
+#' Computes field of influence given a technical change.
 #' 
 #' @description
-#' Calculates total field of influence given a incremental change in the technical coefficients matrix \insertCite{vale_alise_2020}{fio}.
+#' Computes total field of influence given a incremental change in the technical coefficients matrix \insertCite{vale_alise_2020}{fio}.
 #' 
 #' @param tech_coeff_matrix A nxn matrix of technical coefficients.
 #' @param leontief_inverse_matrix The open model nxn Leontief inverse matrix.
@@ -228,12 +228,9 @@ compute_sensitivity_dispersion <- function(leontief_inverse_matrix) .Call(wrap__
 #' A 1xn vector of total production.
 #' 
 #' @details
-#' It calculates the allocation coefficients matrix, which is the rowwise ratio of
+#' Allocation coefficients matrix is the rowwise ratio of
 #' intermediate transactions to total production \insertCite{miller_input-output_2009}{fio}.
 #' 
-#' Underlined Rust code runs in parallel by default, so there is no need to
-#' use future or async/await to parallelize.
-#' 
 #' @references
 #' \insertAllCited{}
 #' 
@@ -256,7 +253,7 @@ compute_allocation_coeff <- function(intermediate_transactions, total_production
 #' A \eqn{n x n} matrix of allocation coefficients.
 #' 
 #' @details
-#' It calculates the Ghosh inverse matrix, which is the inverse of the
+#' The Ghosh inverse matrix is the inverse of the
 #' difference \eqn{(I - F)} where I is the identity matrix and F is the
 #' allocation coefficients matrix \insertCite{miller_input-output_2009}{fio}.
 #' 
@@ -279,7 +276,7 @@ compute_allocation_coeff <- function(intermediate_transactions, total_production
 #' my_iom$ghosh_inverse_matrix
 compute_ghosh_inverse <- function(allocation_coeff) .Call(wrap__compute_ghosh_inverse, allocation_coeff)
 
-#' Calculates backward linkage extraction.
+#' Computes backward linkage extraction.
 #' 
 #' @description
 #' Computes impact on demand structure after extracting a given sector \insertCite{miller_input-output_2009}{fio}.
@@ -295,7 +292,7 @@ compute_ghosh_inverse <- function(allocation_coeff) .Call(wrap__compute_ghosh_in
 #' \insertAllCited{}
 compute_extraction_backward <- function(technical_coefficients_matrix, final_demand_matrix, total_production) .Call(wrap__compute_extraction_backward, technical_coefficients_matrix, final_demand_matrix, total_production)
 
-#' Calculates forward linkage extraction.
+#' Computes forward linkage extraction.
 #' 
 #' @description
 #' Computes impact on supply structure after extracting a given sector \insertCite{miller_input-output_2009}{fio}.
@@ -308,7 +305,7 @@ compute_extraction_backward <- function(technical_coefficients_matrix, final_dem
 #' \insertAllCited{}
 compute_extraction_forward <- function(allocation_coefficients_matrix, added_value_matrix, total_production) .Call(wrap__compute_extraction_forward, allocation_coefficients_matrix, added_value_matrix, total_production)
 
-#' Calculates total extraction
+#' Computes total extraction
 #' @param backward_linkage_matrix A nx2 matrix of backward linkage.
 #' @param forward_linkage_matrix A nx2 matrix of forward linkage.
 #' 

R/r6.R

@@ -114,108 +114,107 @@ iom <- R6::R6Class(
     id = NULL,
 
     #' @field intermediate_transactions
-    #' Intermediate transactions matrix.
+    #' Intermediate transactions matrix
     intermediate_transactions = NULL,
 
     #' @field total_production
-    #' Total production vector.
+    #' Total production vector
     total_production = NULL,
 
     #' @field household_consumption
-    #' Household consumption vector.
+    #' Household consumption vector
     household_consumption = NULL,
 
     #' @field government_consumption
-    #' Government consumption vector.
+    #' Government consumption vector
     government_consumption = NULL,
 
     #' @field exports
-    #' Exports vector.
+    #' Exports vector
     exports = NULL,
 
     #' @field final_demand_others
-    #' Other vectors of final demand that doesn't have dedicated slots.
+    #' Other vectors of final demand that doesn't have dedicated slots
     final_demand_others = NULL,
 
     #' @field final_demand_matrix
-    #' Aggregates final demand vectors into a matrix.
+    #' Aggregates final demand vectors into a matrix
     final_demand_matrix = NULL,
 
     #' @field imports
-    #' Imports vector.
+    #' Imports vector
     imports = NULL,
 
     #' @field taxes
-    #' Taxes vector.
+    #' Taxes vector
     taxes = NULL,
 
     #' @field wages
     #' Wages vector.
     wages = NULL,
 
     #' @field operating_income
-    #' Operating income vector.
+    #' Operating income vector
     operating_income = NULL,
 
     #' @field added_value_others
-    #' Other vectors of added value that doesn't have dedicated slots.
+    #' Other vectors of added value that doesn't have dedicated slots
     added_value_others = NULL,
 
     #' @field added_value_matrix
-    #' Aggregates added value vectors into a matrix.
+    #' Aggregates added value vectors into a matrix
     added_value_matrix = NULL,
 
     #' @field occupation
     #' Occupation vector
     occupation = NULL,
 
     #' @field technical_coefficients_matrix
-    #' Technical coefficients matrix.
+    #' Technical coefficients matrix
     technical_coefficients_matrix = NULL,
 
     #' @field leontief_inverse_matrix
-    #' Leontief inverse matrix.
+    #' Leontief inverse matrix
     leontief_inverse_matrix = NULL,
 
     #' @field multiplier_output
-    #' Output multiplier dataframe.
+    #' Output multiplier dataframe
     multiplier_output = NULL,
 
     #' @field multiplier_employment
-    #' Employment multiplier dataframe.
+    #' Employment multiplier dataframe
     multiplier_employment = NULL,
 
     #' @field multiplier_taxes
-    #' Taxes multiplier dataframe.
+    #' Taxes multiplier dataframe
     multiplier_taxes = NULL,
 
     #' @field multiplier_wages
-    #' Wages multiplier dataframe.
+    #' Wages multiplier dataframe
     multiplier_wages = NULL,
 
     #' @field field_influence
-    #' Influence field matrix.
+    #' Influence field matrix
     field_influence = NULL,
 
     #' @field key_sectors
-    #' Key sectors dataframe.
+    #' Key sectors dataframe
     key_sectors = NULL,
 
     #' @field allocation_coefficients_matrix
-    #' Allocation coefficients matrix.
+    #' Allocation coefficients matrix
     allocation_coefficients_matrix = NULL,
 
     #' @field ghosh_inverse_matrix
-    #' Ghosh inverse matrix.
+    #' Ghosh inverse matrix
     ghosh_inverse_matrix = NULL,
 
     #' @field hypothetical_extraction
-    #' Absolute and relative backward and forward differences in total output after a hypothetical extraction.
+    #' Absolute and relative backward and forward differences in total output after a hypothetical extraction
     hypothetical_extraction = NULL,
 
     #' @field threads
-    #' Number of threads available for Rust to run in parallel.
-    #' Defaults to 0, meaning running in parallel with all available threads.
+    #' Number of threads available for Rust to run in parallel
     threads = 0,
 
     #' @description
@@ -356,8 +355,6 @@ iom <- R6::R6Class(
     #' @param matrix_name
     #' One of household_consumption, government_consumption, exports, final_demand_others,
     #' imports, taxes, wages, operating income, added_value_others or occupation matrix to be removed.
-    #' @param matrix
-    #' Matrix object to be removed.
     remove = function(matrix_name) {
       # check arg
       choices <- private$iom_elements()
@@ -374,7 +371,7 @@ iom <- R6::R6Class(
     },
 
     #' @description
-    #' Updates final demand matrix.
+    #' Aggregates final demand vectors into a matrix.
     update_final_demand_matrix = function() {
       # bind final demand vectors
       self$final_demand_matrix <- as.matrix(cbind(
@@ -386,7 +383,7 @@ iom <- R6::R6Class(
     },
 
     #' @description
-    #' Updates added value matrix.
+    #' Aggregates added value vectors into a matrix.
     update_added_value_matrix = function() {
       # bind added value vectors
       self$added_value_matrix <- as.matrix(rbind(
@@ -428,8 +425,6 @@ iom <- R6::R6Class(
 
     #' @description
     #' Computes the Leontief inverse matrix.
-    #' @param technical_coefficients_matrix
-    #' Technical coefficients matrix.
     compute_leontief_inverse = function() {
       # check if technical coefficients matrix is available
       if (is.null(self$technical_coefficients_matrix)) {
@@ -454,8 +449,6 @@ iom <- R6::R6Class(
 
     #' @description
     #' Computes the output multiplier dataframe.
-    #' @param leontief_inverse_matrix
-    #' Leontief inverse matrix.
     compute_multiplier_output = function() {
       # check if leontief inverse matrix is available
       if (is.null(self$leontief_inverse_matrix)) {
@@ -492,8 +485,6 @@ iom <- R6::R6Class(
 
     #' @description
     #' Computes the employment multiplier dataframe.
-    #' @param leontief_inverse_matrix
-    #' Leontief inverse matrix.
     compute_multiplier_employment = function() {
       # check if leontief inverse matrix is available
       if (is.null(self$leontief_inverse_matrix)) {
@@ -533,8 +524,6 @@ iom <- R6::R6Class(
 
     #' @description
     #' Computes the wages multiplier dataframe.
-    #' @param leontief_inverse_matrix
-    #' Leontief inverse matrix.
     compute_multiplier_wages = function() {
       # check if leontief inverse matrix is available
       if (is.null(self$leontief_inverse_matrix)) {
@@ -574,8 +563,6 @@ iom <- R6::R6Class(
 
     #' @description
     #' Computes the taxes multiplier dataframe.
-    #' @param leontief_inverse_matrix
-    #' Leontief inverse matrix.
     compute_multiplier_taxes = function() {
       # check if leontief inverse matrix is available
       if (is.null(self$leontief_inverse_matrix)) {
@@ -616,7 +603,8 @@ iom <- R6::R6Class(
     #' @description
     #' Computes the influence field matrix.
     #' @param epsilon
-    #' Epsilon value. A technical change in the input-output matrix.
+    #' Epsilon value. A technical change in the input-output matrix, caused by a variation of size `epsilon` into each
+    #' element of technical coefficients matrix.
     compute_field_influence = function(epsilon) {
       # check if epsilon was set
       if (missing(epsilon)) {
@@ -647,7 +635,7 @@ iom <- R6::R6Class(
     },
 
     #' @description
-    #' Computes the key sectors dataframe.
+    #' Computes the key sectors dataframe, based on it's backward and forward linkages.
     compute_key_sectors = function() {
       # check if leontief inverse matrix is available
       if (is.null(self$leontief_inverse_matrix)) {