-
Notifications
You must be signed in to change notification settings - Fork 0
Getting Started
CEDS is an open source framework that aims to be run on any major operating system. The following guide offers instructions for installing CEDS on your local machine.
It is recommended to use the latest version of R to run CEDS, however versions newer than R 3.2.0 should run without problems.
CEDS also requires several additional R packages to be installed. Packages only need to be installed once (while connected to the internet) with the install.packages() function, however they must be explicitly loaded every time a new R session is started with the require() or library() functions.
R scripts in the system will automatically load packages, but the necessary packages will need to be installed prior to running the system the first time. If a package is required but not installed, a warning message will appear.
The following packages are loaded in the header file global_settings.R, which is sourced at the beginning of each script: dplyr, ggplot2, gridExtra, magrittr, plyr, readxl, reshape, stringr, tidyr, openxlsx, XML, and zoo.
Additionally, the package FAOSTAT is loaded in several individual R scripts for retrieving and processing data from FAOSTAT.
When installing some of these packages, other required dependencies will be automatically installed as well. Ensuring that the packages listed above and below are installed, however, should be sufficient for the system to run. To quickly install all required packages, run the following lines in an R session:
packages <- c("dplyr", "ggplot2", "gridExtra", "magrittr", "plyr", "readxl", "reshape", "stringr", "tidyr", "openxlsx", "XML", "zoo")
new.packages <- packages[!(packages %in% installed.packages()[,"Package"])]
if(length(new.packages)) install.packages(new.packages)
In order to be able to run the CEDS system as a whole, it is necessary to acquire a copy of the data files OECD_E_Stat.csv and NonOECD_E_Stat.csv (and their metadata files) and place them in the emissions-data-system/input/energy directory. They are required by the script A1.2.IEA_downscale_ctry.R, but are proprietary data and not allowed to be a versioned part of a public-domain system such as CEDS. More details about using IEA data can be found in the User Guide.
While individual components of CEDS can be run individually just with R, the system as a whole should be executed using a Makefile system. To run CEDS with the Makefile, you will need to install Make.
To test if you have Make already installed, simply type make in the command line. If you do not have it, you will see the error:
bash: make: command not found.
Make can easily be installed with Xcode, which can be downloaded for free from the Apple App Store.
Whithin Xcode, you can install Command Line Tools by selecting Xcode→Preferences→Downloads, then clicking Components and Install on the command line tools line.
|
Tip
|
Make can also be installed with the HomeBrew command brew install make.
|
There are a number of options for running a Makefile in Windows. The make functionality is not native to the Windows operating system, so it must be downloaded. Some options for installing Make are:
-
-
During the installation of Cygwin make sure to specify that you would like Make as well. On the Select Packages screen, under
All→Devel, ensure that the Bin box is checked for the file labeledmake: the GNU version of the ‘make’ utility. Src is not necessary.
-
|
Tip
|
Installing Cygwin also gives the option to install other command line tools as well such as R commands like Rscript and R CMD BATCH, gcc functionalities, or command line text editors. |
-
-
This option will provide the
makecommand to the Windows command prompt
-
-
-
This option will provide the
nmakecommand to the Windows command prompt
-
Once Make is installed, Makefiles can be run by opening the command prompt, pointing to the location of the Makefile, and entering make (or nmake).
The commands Rscript or R CMD BATCH are necessary, as they are used in the Makefile. These commands can also be used in the command line independently to run specified individual scripts, if desired.
Use git to download CEDS to a local repository on your system. After making sure all prerequisites are properly installed, run the entire system by simply navigating to the CEDS folder and executing the make all command. The Makefile system will detect any changes made and re-build the outputs as necessary. If the system is up to date, it will do nothing.
All modules are included in a Makefile in the emissions data system. Running the modules through the Makefile is advantageous because make will automatically run only what needs to be run to keep everything properly updated.
|
Caution
|
Make sure you are in the root CEDS directory containing the Makefile. If you are not you will see the error: No targets specified and no makefile found. Stop.
|
To rerun the entire system use the make clean-all command, then the make command. This will remove all intermediate outputs and log files, forcing the Makefile system to build the system from the first output file again and running all integrated scripts. For more information on using the Makefile, see the User Guide.
It is also possible to run individual scripts in CEDS without running the whole system. Simply use the RScript command from the command line, or open the file you wish to run in an R GUI and run from there. Make sure you are running the script from either the root directory of the system (the CEDS directory, by default), or the input directory.
At the present, the CEDS modules require several packages to run properly such as dplyr and openxlsx. If these packages are not already present in your R Library, the system should attempt to install them for you. Depending on your system setup and permissions, these packages will either be installed into the default library or one local to your account. Errors with packages can usually be resolved by reinstalling them, making sure to get the latest version.
If CEDS gives you an error saying that it cannot find a package, you need to manually install the package with the install.packages() function. The full list of packages can be found in the Prerequisites section above.
Additional problems are usually caused by R being unable to locate the packages you have installed. When installing packages, the system should have offered you the option to create a personal or user library. Run the R command .libPaths() to check if this library exists. It should print out the file path for the original library, either under Program Files on Windows or Library on OSX. Any User library that you added will also be listed here under your User account.
If the new library does not show up, search for the file entitled .Renviron or just Renviron. Open it with your preferred text editor and scroll down to the entry for R_LIBS_USER, if there is one. If it exists, remove any comment operators (#) preceding it, and edit the designation to your new User library. If it does not exist, create it. For Windows this would be:
R_LIBS_USER=${R_LIBS_USER-'C:/Users/<user-name>/Documents/R/win-library/3.4.2'}
This should ensure that R recognizes the user library, and will know to look there for packages and install them there if necessary.