Linux: . Windows:

macroutils

Page content: In short · Installation · Official CKB release · Development version · Text based graphical user interface · Documentation · Issues and bug reports

R utility functions for the MACRO and SOILNDB models. Read and write binary files, create plots, and more.

MACRO and SOILNDB use binary files for both input (climate variables) and output (simulation results). The format of these files is not standard and macroutils provides functions to handle them.

In short

• Author: Julien MOEYS (SLU/CKB)
• Tutorial and On-line documentation
• Package description: See DESCRIPTION.
• View and report issues: https://github.com/julienmoeys/macroutils/issues Note: not for reporting issues related to MACRO (core model)
• Homepage of the MACRO model: here

Installation

For all versions you need to install beforehand the sofware R ("a free software environment for statistical computing and graphics").

From R homepage, go to the CRAN homepage or (better) choose the nearest CRAN mirror.

From there, choose 'Download R for Windows' (or Mac or Linux), and then choose 'base' or 'install R for the First time'.

• If you want to install the official CKB release (see below), you must download the R version that corresponds to the package requirement as indicated on macroutils / MACRO 5.2 homepage on CKB website (see below).

• If you want to install the development version of macroutils (see below), you can download latest R version, or (safer) the R version that is indicated in the DESCRIPTION file.

Download the R installer, and install R (follow the instructions).

Official CKB release

Note: Windows only (the source package is not provided on this page).

On MACRO 5.2 official homepage, you can download the latest version of the package

The package binary Files are usually named macroutils_x.y.z.zip, where x, y and z form the version number (major milestone, minor milestone, minor revision).

Notice that you don't need to uncompress this .zip File! (it is an installer). Open R Graphical User Interface, and in the packages menu (top menu bar), choose 'Install package(s) from local zip File(s)', and select the package binary File (macroutils_x.y.z.zip).

Development version

Note: May work on other platforms than Windows, but this has not been tested (MACRO only runs on Windows).

Note: If you are not familiar with R (and R developments), you should probably avoid that method, as some complications may arise.

The development version of macroutils is publicly available on GitHub (the page you are actually reading). This page allows you to explore the package source code, to install the package development version (see below) and to report some issues (bugs)

• On Windows computers, install Rtools Install the version that corresponds to your the version of R that is installed on your computer. On other machines, read the instructions here (Windows users may also have a look at this page).

• Install the package devtools. devtools is a package developed by Hadley Wickham to install development version of R packages that are hosted on GitHub (among other useful things).

• Open a new R cession and type install.packages("devtools"). Follow the additional instructions here.

• Install the development version of macroutils. Open a new R cession and type:

  devtools::install_github("julienmoeys/macroutils/pkg/macroutils")

Text based graphical user interface

See also: The package tutorial.

macroutils provides simple but effective text based graphical user interfaces for the most useful functions provided by the package. Once the package has been installed, you just need to type one simple command (per function) and then follow the instructions given to you.

Plotting the content of one (or several) bin file(s)

Launch R and type:

macroutils::macroPlot()

and follow the instructions. This is equivalent to:

library( "macroutils" )
macroPlot()

Converting one (or several) bin file(s)

Launch R and type:

macroutils::macroConvertBin()

and follow the instructions. This is equivalent to:

library( "macroutils" )
macroConvertBin()

View one bin file

Launch R and type:

macroutils::macroViewBin()

and follow the instructions. This is equivalent to:

library( "macroutils" )
macroViewBin()

Documentation

See also: The package tutorial.

On-line documentation

The package help pages can be browsed on-line from this page. Notice that this may not always be the very latest version of the package.

Loading the package

Open R graphical user interface and type:

library( "macroutils" )

Package documentation (help pages)

To go further, you can access the help page by typing:

help( package = "macroutils" )

There, see in particular the vignette (tutorial) in "User guides, package vignettes and other documentation" (to get started). You can also access that tutorial with the command

vignette( "macroutils_vignette" )

Notice that if you have installed the development version from GitHub the vignette may not have been generated with the package. But the vignette can be extracted from the package Windows binaries that can be downloaded on MACRO homepage (macroutils_x.y.z.zip > macroutils > doc > macroutils_vignette.pdf).

Issues and bug reports

Issues and bugs can be reported here. Do not report issues related to the model MACRO (i.e. not related to macroutils) on that page. Do not either report more general questions that are related to R and R usage. Provide a reproducible (self standing) example of your problem, as it generally greatly helps to narrow down the problem.