From 0b8d8b4a004103b07d0f255938dfc38ceff143fc Mon Sep 17 00:00:00 2001 From: evaaepelde Date: Mon, 23 Sep 2024 12:35:24 +0200 Subject: [PATCH] improve tutorials --- R/main.R | 26 ++++-- docs/articles/Tutorials.html | 60 +++++++------ docs/pkgdown.yml | 2 +- docs/reference/calc_ep.html | 2 +- docs/reference/calc_tp.html | 2 +- docs/reference/check_year.html | 160 +++++++++++++++++++++++++++++++++ docs/reference/index.html | 4 + docs/sitemap.xml | 1 + paper/paper.md | 4 +- vignettes/Tutorials.Rmd | 60 +++++++------ 10 files changed, 252 insertions(+), 69 deletions(-) create mode 100644 docs/reference/check_year.html diff --git a/R/main.R b/R/main.R index cc3762f..502c75f 100644 --- a/R/main.R +++ b/R/main.R @@ -193,9 +193,16 @@ calc_ep <- function(year, index = "all"){ year <- as.numeric(year) } - if (!year %in% seq(2006,2021,1)) { - stop(sprintf('You introduced year %s which is not available. Possible options are %s.', - year, paste(seq(2006,2021,1), collapse = ", "))) + wrong_years <- year[!year %in% seq(2006,2021,1)] + + if (length(wrong_years) != 0) { + if(length(wrong_years) == 1){ + stop(sprintf('You introduced year %s which is not available. Possible options are %s.', + paste0(wrong_years, collapse = ", "), paste(seq(2006,2021,1), collapse = ", "))) + }else{ + stop(sprintf('You introduced years %s which are not available. Possible options are %s.', + paste0(wrong_years, collapse = ", "), paste(seq(2006,2021,1), collapse = ", "))) + } } accepted <- c("all", @@ -283,9 +290,16 @@ calc_tp <- function(year, index = "all"){ year <- as.numeric(year) } - if (!year %in% seq(2006,2021,1)) { - stop(sprintf('You introduced year %s which is not available. Possible options are %s.', - year, paste(seq(2006,2021,1), collapse = ", "))) + wrong_years <- year[!year %in% seq(2006,2021,1)] + + if (length(wrong_years) != 0) { + if(length(wrong_years) == 1){ + stop(sprintf('You introduced year %s which is not available. Possible options are %s.', + paste0(wrong_years, collapse = ", "), paste(seq(2006,2021,1), collapse = ", "))) + }else{ + stop(sprintf('You introduced years %s which are not available. Possible options are %s.', + paste0(wrong_years, collapse = ", "), paste(seq(2006,2021,1), collapse = ", "))) + } } accepted <- c("all", diff --git a/docs/articles/Tutorials.html b/docs/articles/Tutorials.html index 42ce899..1237ae2 100644 --- a/docs/articles/Tutorials.html +++ b/docs/articles/Tutorials.html @@ -154,12 +154,12 @@

Example 1. How to enter

  1. Download the example file into your directory by running the -following function in the terminal:
    2. +following function in the R terminal: 
 ex_shocks()
    -

  1. Go to the defined folder in your directory and open the csv +

  2. Go to your working directory and open the csv “Example_shocks”.

  3. Define the scenarios: Each column Scenario__ is a scenario. To run calc_di for a single scenario delete column Scenario2. @@ -178,20 +178,20 @@

    Example 1. How to enter the terminal:

-file_name <- read.csv(file,        # File name or full file path
-             header = TRUE,        # Read the header (TRUE)
-             sep = ",",            # Value separator
-             dec = ".",            # Decimal point
-             ...)                  # Additional arguments
+exampledf <- read.csv(file_name, # File name or full file path + header = TRUE, # Header indicator (set to TRUE) + sep = ",", # Value separator used in the file + dec = ".", # Decimal point format used + ...) # Additional arguments to be passed
  1. Indicate to calc_di that this is the file from which to take the price shocks to be applied.
-calc_di( year,                 
-         elevate = F,
-         shocks = file_name,   # Indicate here your file name
-         ...)
+calc_di( year, # Base year for the simulation (available 2006-2021) + elevate = F, # Elevation of raw data (set to FALSE) + shocks = exampledf, # Indicate here the name of the uploaded file with shocks + ...) # Additional arguments to be passed

[1] The COICOP variables of the file correspond to the aggregate variables of the package, if you are not going to aggregate the COICOP variables you have to replace the column @@ -221,11 +221,11 @@

Introduce individual variable variables click here.

-calc_di( year,                 
-        elevate = F,
-        shocks ,   
-        var_impact = "ZONA",       # Indicate here the selected variable
-        ...)
+calc_di(year, # Base year for the simulation + elevate = F, # Elevation of raw data (set to FALSE) + shocks = exampledf, # Name of the uploaded file with shocks + var_impact = "DECILE", # Indicate here the socioeconomic variable to be used + ...) # Additional arguments to be passed
  1. In case you want to calculate distributional impacts for several variables, e.g. for “ZONE” and “TAMAMU”, create a vector with these @@ -237,11 +237,11 @@

    Introduce individual variable vars <- c("ZONA", "TAMAMU") #Introduce the vector in var_impact argument -calc_di( year, - elevate = F, - shocks , - var_impact = vars, # Indicate here the name of the vector with the selected variables - ...) +calc_di(year, # Base year for the simulation + elevate = F, # Elevation of raw data (set to FALSE) + shocks = exampledf, # Name of the uploaded file with shocks + var_impact = vars, # Indicate here the name of the vector with the selected variables + ...) # Additional arguments to be passed

    Introduce a set of variables (var_intersec) @@ -270,9 +270,11 @@

    Introduce a set of variables terminal:

-file_name <- read.csv(file,        # File name or full file path
-             header = TRUE,
-             ...)                  # Additional arguments
+example_vars <- read.csv(file_name, # File name or full file path + header = TRUE, # Header indicator (set to TRUE) + sep = ",", # Value separator used in the file + dec = ".", # Decimal point format used + ...) # Additional arguments to be passed
  1. Enter the file in the var_intersec argument in calc_di. By default, var_intersec = NULL , @@ -281,11 +283,11 @@

    Introduce a set of variables for individual variables. For more information on variables click here.

-calc_di( year,                 
-        elevate = F,
-        shocks ,   
-        var_intersec = file_name,       # Indicate here the file name of the selected set of variables
-        ...)
+calc_di(year, # Base year for the simulation + elevate = F, # Elevation of raw data (set to FALSE) + shocks = exampledf, # Name of the uploaded file with shocks + var_intersec = example_vars, # Indicate here the file name of the selected set of variables + ...) # Additional arguments diff --git a/docs/pkgdown.yml b/docs/pkgdown.yml index 3a88aeb..48ad130 100644 --- a/docs/pkgdown.yml +++ b/docs/pkgdown.yml @@ -10,4 +10,4 @@ articles: Tutorials: Tutorials.html TutorialsEnergyPoverty: TutorialsEnergyPoverty.html TutorialsTransportPoverty: TutorialsTransportPoverty.html -last_built: 2024-09-18T14:47Z +last_built: 2024-09-23T10:05Z diff --git a/docs/reference/calc_ep.html b/docs/reference/calc_ep.html index 3e4b25a..23002d7 100644 --- a/docs/reference/calc_ep.html +++ b/docs/reference/calc_ep.html @@ -130,7 +130,7 @@

Arguments

index
-

energy poverty index or indices you want to calculate. Possible +

energy poverty index or indices to be calculated. Possible options: 10 all the indices for the selected year/s.

diff --git a/docs/reference/calc_tp.html b/docs/reference/calc_tp.html index 5880cfc..ef11690 100644 --- a/docs/reference/calc_tp.html +++ b/docs/reference/calc_tp.html @@ -130,7 +130,7 @@

Arguments

index
-

transport poverty index or indices you want to calculate. Possible +

transport poverty index or indices to be calculated. Possible options: 10 for the selected year/s.

diff --git a/docs/reference/check_year.html b/docs/reference/check_year.html new file mode 100644 index 0000000..fac8e44 --- /dev/null +++ b/docs/reference/check_year.html @@ -0,0 +1,160 @@ + +check_year — check_year • medusa + + +
+
+ + + +
+
+
+

check_year

+ Source: R/utils.R + +
+ +
+

Check if the parameter year is valid

+
+ +
+ 
check_year(year)
+
+ +
+

Arguments

+ + +
year
+

year introduce by the user

+ +
+
+

Value

+

stop if year is wrongly introduced

+
+ +
+ +
+ + +
+

Developed by Eva Alonso-Epelde, Clàudia Rodés-Bachs, María Moyano-Reina, Jon Sampedro, Xaquín García-Muros.

+
+ +
+

Site built with pkgdown 2.1.0.

+
+ +
+ + + + + + + + diff --git a/docs/reference/index.html b/docs/reference/index.html index bb3dcc4..bffd1fc 100644 --- a/docs/reference/index.html +++ b/docs/reference/index.html @@ -155,6 +155,10 @@

All functions categories

List containing the socioeconomic and demographic categories for the calculation of distributional impacts

+ +

check_year()

+ +

check_year

coicop_2006

diff --git a/docs/sitemap.xml b/docs/sitemap.xml index e9a424e..162fcba 100644 --- a/docs/sitemap.xml +++ b/docs/sitemap.xml @@ -26,6 +26,7 @@ /reference/calc_ep.html /reference/calc_tp.html /reference/categories.html +/reference/check_year.html /reference/coicop_2006.html /reference/coicop_2007.html /reference/coicop_2008.html diff --git a/paper/paper.md b/paper/paper.md index b4b2381..f31595f 100644 --- a/paper/paper.md +++ b/paper/paper.md @@ -40,7 +40,7 @@ library(medusa) ex_shocks() # After introducing the price shocks in the csv file, upload the edited file -file_name <- read.csv(file, # File name or full file path +exampledf <- read.csv(file_name, # File name or full file path header = TRUE, # Header indicator (set to TRUE) sep = ",", # Value separator used in the file dec = ".", # Decimal point format used @@ -49,7 +49,7 @@ file_name <- read.csv(file, # File name or full file path # Calculate distributional impacts calc_di( year, # Base year for the simulation elevate = F, # Elevation of raw data (set to FALSE) - shocks = file_name, # Name of the uploaded file with shocks + shocks = exampledf, # Name of the uploaded file with shocks var_impact = "DECILE", # Socioeconomic variable to be used ...) # Additional arguments to be passed ``` diff --git a/vignettes/Tutorials.Rmd b/vignettes/Tutorials.Rmd index 7c001a0..24520d0 100644 --- a/vignettes/Tutorials.Rmd +++ b/vignettes/Tutorials.Rmd @@ -11,13 +11,13 @@ vignette: > ## Example 1. How to enter price shocks in `calc_di` -1. Download the example file into your directory by running the following function in the terminal: +1. Download the example file into your directory by running the following function in the R terminal: ``` r ex_shocks() ``` -2. Go to the defined folder in your directory and open the csv "Example_shocks". +2. Go to your working directory and open the csv "Example_shocks". 3. Define the scenarios: Each column Scenario__ is a scenario. To run `calc_di` for a single scenario delete column Scenario2. To add another scenario, copy column Scenario2 to the right and change the heading to Scenario3. You can also rename the scenarios by changing the heading of each column (e.g. renaming "Scenario1" to "Shock1"). It is recommended to keep the names short, as additional variables with this name will be created later and inserted into the graphs. @@ -27,19 +27,19 @@ ex_shocks() 6. Upload the edited file to R by running the following function in the terminal: ``` r -file_name <- read.csv(file, # File name or full file path - header = TRUE, # Read the header (TRUE) - sep = ",", # Value separator - dec = ".", # Decimal point - ...) # Additional arguments +exampledf <- read.csv(file_name, # File name or full file path + header = TRUE, # Header indicator (set to TRUE) + sep = ",", # Value separator used in the file + dec = ".", # Decimal point format used + ...) # Additional arguments to be passed ``` 7. Indicate to `calc_di` that this is the file from which to take the price shocks to be applied. ``` r -calc_di( year, - elevate = F, - shocks = file_name, # Indicate here your file name - ...) +calc_di( year, # Base year for the simulation (available 2006-2021) + elevate = F, # Elevation of raw data (set to FALSE) + shocks = exampledf, # Indicate here the name of the uploaded file with shocks + ...) # Additional arguments to be passed ``` [1] The COICOP variables of the file correspond to the aggregate variables of the package, if you are not going to aggregate the COICOP variables you have to replace the column labels by the COICOP variables that appear in your dataset. @@ -56,11 +56,11 @@ available_var_impact() 3. Enter that variable in the `var_impact` argument of `calc_di`. By default, `var_impact = "all"` , i.e. it calculates the distributional impacts for all variables returned by `available_var_impact()`. For more information on variables click [here](https://bc3lc.github.io/medusa/articles/AvailableVariables.html). ``` r -calc_di( year, - elevate = F, - shocks , - var_impact = "ZONA", # Indicate here the selected variable - ...) +calc_di(year, # Base year for the simulation + elevate = F, # Elevation of raw data (set to FALSE) + shocks = exampledf, # Name of the uploaded file with shocks + var_impact = "DECILE", # Indicate here the socioeconomic variable to be used + ...) # Additional arguments to be passed ``` 4. In case you want to calculate distributional impacts for several variables, e.g. for "ZONE" and "TAMAMU", create a vector with these variables and enter it in the `var_impact` argument of `calc_di`. @@ -69,11 +69,11 @@ calc_di( year, vars <- c("ZONA", "TAMAMU") #Introduce the vector in var_impact argument -calc_di( year, - elevate = F, - shocks , - var_impact = vars, # Indicate here the name of the vector with the selected variables - ...) +calc_di(year, # Base year for the simulation + elevate = F, # Elevation of raw data (set to FALSE) + shocks = exampledf, # Name of the uploaded file with shocks + var_impact = vars, # Indicate here the name of the vector with the selected variables + ...) # Additional arguments to be passed ``` ### Introduce a set of variables (var_intersec) @@ -88,15 +88,17 @@ ex_var_intersec() ``` 3. Upload the edited file to R by running the following function in the terminal: ``` r -file_name <- read.csv(file, # File name or full file path - header = TRUE, - ...) # Additional arguments +example_vars <- read.csv(file_name, # File name or full file path + header = TRUE, # Header indicator (set to TRUE) + sep = ",", # Value separator used in the file + dec = ".", # Decimal point format used + ...) # Additional arguments to be passed ``` 4. Enter the file in the `var_intersec` argument in `calc_di`. By default, `var_intersec = NULL` , i.e. iif no data is entered in this argument it will not calculate any intersectional impacts, it will only calculate distributional impacts for individual variables. For more information on variables click [here](https://bc3lc.github.io/medusa/articles/AvailableVariables.html). ``` r -calc_di( year, - elevate = F, - shocks , - var_intersec = file_name, # Indicate here the file name of the selected set of variables - ...) +calc_di(year, # Base year for the simulation + elevate = F, # Elevation of raw data (set to FALSE) + shocks = exampledf, # Name of the uploaded file with shocks + var_intersec = example_vars, # Indicate here the file name of the selected set of variables + ...) # Additional arguments ```