metools

This is the official guide of the metools package, its purpose is to explain the functions of the package and examples of how they can be applied correctly.

The main objective of the metools package is to facilitate the production of graphs and reports, more specifically in macroeconomic work, the functions are divided into graphs and data manipulators.
See below the package functions and their respective divisions:

Data manipulation


cuminyear	Accumulated variation in year
cuminyear_var	Accumulated variation in year to decimal data
cum_var	Accumulated variation
pct_change	Percentual change in t periods of a serie
num2month	Transform month names to month numbers
month2num	Transform month numbers to month names
me.lag	Lag or lead a vector, according value of t
me.spread	Spread an dataframe
stattable	Descritive statistic table


col2char	Transform defined columns to character
col2factor	Transform defined columns to factor
col2num	Transform defined columns to numeric
col2percent	Add percent in column
colpct2num	Remove percent from a column, and transform in number
colround	Round defined columns

	Plot
p.line	Line plot
p.col	Bar plot
p.col_ord	Ordered bar plot
p.col_ord_wl	Ordered bar plot with legend
p.col_wl	Bar plot with legend
p.tscol	Bar plot in time serie format
p.tsl	Line plot in time serie format
p.gradientcolor	Create Gradient
p.seqdatebreaks	Create Date Interval
p.colorbypositive	Color by positive or negative
p.colorbyvar	Color by variation
mp.s	Multi serie plot
mp.ts	Multi serie plot in time serie format

	Graphic models
gm.col	Bar Graphic Model
gm.col_ord	Ordered Bar Graphic Model
gm.col_ord_wl	Ordered Bar Graphic with Legend Model
gm.col_wl	Bar Graphic with Legend Model
gm.line	Line Graphic Model
gm.tsl	Time serie line Graphic Model
gm.tscol	Time serie bar Graphic Model
gm.tscol2	Time serie bar Graphic Model

Note that all functions of graphical category have a prefix,
the function of it is to distinguish the graphical functions
from the data manipulate functions.
In the next session we will explain each category and its function.

For the application of the examples will be use a timeserie of the United States GDP, it was taken from the World Bank, for a reliable execution of the examples it is available for download clicking here. Some examples will be use codes from the preparation of this guide, due to the similarity with the preparation of a report, as it was done in R Markdown.

Data manipulation functions

The data manipulation functions do not have a defined suffix, a good part of their functions work with data.frames, a few exceptions should be worked at vector. See below each of the data manipulation functions in detail.

col2char

col2char function receive a data.frame object in x parameter and return a new data.frame object with the columns defined between the start and end parameter in character class.

col2char(x,start,end)

x: a data.frame object
start: number of start column
end: number of end column

Class transformations into data.frames can require a good number of lines of code, especially when done by beginner programmers. The col2char function serves to meet this need. Making this guide I needed to do some transformations in the data.frame of the functions table, even being a small example, it works well to demonstrate the usefulness of this function.

# Using R base function
mp_functions[[1]]=as.character(mp_functions[[1]])
mp_functions[[2]]=as.character(mp_functions[[2]])
plot_functions[[1]]=as.character(plot_functions[[1]])
plot_functions[[2]]=as.character(plot_functions[[2]])

# Using metools col2char function
mp_functions=col2char(mp_functions,start=1)
plot_functions=col2char(plot_functions,start=1)

Using the R base function we use about four rows, to transform two columns of two data.frames, using the col2char function we reduce the number of rows of code required by half. This is very important, because often data.frames contain more than ten lines.

col2factor

col2factor function receive a data.frame object in x parameter and return a new data.frame object with the columns defined between the start and end parameter in factor class.

col2factor(x,start,end)

x: a data.frame object
start: number of start column
end: number of end column

#Transform Date column in factor.
usagdp=col2factor(usagdp,start=1,end=1)
usagdp

##         Date GDP..current.US.. GDP.growth..annual...
## 1 2010-01-01          14.99205              2.563767
## 2 2011-01-01          15.54258              1.550836
## 3 2012-01-01          16.19701              2.249546
## 4 2013-01-01          16.78485              1.842081
## 5 2014-01-01          17.52175              2.451973
## 6 2015-01-01          18.21930              2.880910
## 7 2016-01-01          18.70719              1.567215
## 8 2017-01-01          19.48539              2.217010
## 9 2018-01-01          20.54434              2.927323

#See factor levels
levels(usagdp[[1]])

## [1] "2010-01-01" "2011-01-01" "2012-01-01" "2013-01-01" "2014-01-01"
## [6] "2015-01-01" "2016-01-01" "2017-01-01" "2018-01-01"

col2num

col2num function receive a data.frame object in x parameter and return a new data.frame object with the columns defined between the start and end parameter in numeric class.

col2num(x,start,end)

x: a data.frame object
start: number of start column
end: number of end column

#Transform GDP columns in numeric.
usagdp=col2num(usagdp,start=2,end=3)
usagdp

##         Date GDP..current.US.. GDP.growth..annual...
## 1 2010-01-01          14.99205              2.563767
## 2 2011-01-01          15.54258              1.550836
## 3 2012-01-01          16.19701              2.249546
## 4 2013-01-01          16.78485              1.842081
## 5 2014-01-01          17.52175              2.451973
## 6 2015-01-01          18.21930              2.880910
## 7 2016-01-01          18.70719              1.567215
## 8 2017-01-01          19.48539              2.217010
## 9 2018-01-01          20.54434              2.927323

col2percent

col2percent function receive a data.frame object in x parameter and return a new data.frame object with the columns defined between the start and end parameter in character class but with percent sign.

col2percent(x,start,end,mult100)

x: a data.frame object
start: number of start column
end: number of end column
mult100: if values are in decimal form, use this to solve

#Transform GDP growht column in percent.
usagdp=col2percent(usagdp,start=3,end=3)
usagdp

##         Date GDP..current.US.. GDP.growth..annual...
## 1 2010-01-01          14.99205     2.56376655876581%
## 2 2011-01-01          15.54258     1.55083550568156%
## 3 2012-01-01          16.19701     2.24954585236992%
## 4 2013-01-01          16.78485     1.84208107101102%
## 5 2014-01-01          17.52175     2.45197303536034%
## 6 2015-01-01          18.21930     2.88091046605219%
## 7 2016-01-01          18.70719     1.56721516997864%
## 8 2017-01-01          19.48539     2.21701033031884%
## 9 2018-01-01          20.54434     2.92732272821085%

If values are in decimal form, you can use the mult100 parameter, see below:

#Transform GDP growht column in percent.
usagdp2=col2percent(usagdp,start=3,end=3,mult100=TRUE)
usagdp=cbind(usagdp,"Function result"=usagdp2[,3])
usagdp

##         Date GDP..current.US.. GDP.growth..annual...   Function result
## 1 2010-01-01          14.99205            0.02563767 2.56376655876581%
## 2 2011-01-01          15.54258            0.01550836 1.55083550568156%
## 3 2012-01-01          16.19701            0.02249546 2.24954585236992%
## 4 2013-01-01          16.78485            0.01842081 1.84208107101102%
## 5 2014-01-01          17.52175            0.02451973 2.45197303536034%
## 6 2015-01-01          18.21930            0.02880910 2.88091046605219%
## 7 2016-01-01          18.70719            0.01567215 1.56721516997864%
## 8 2017-01-01          19.48539            0.02217010 2.21701033031884%
## 9 2018-01-01          20.54434            0.02927323 2.92732272821085%

colpct2num

colpct2num function receive a data.frame object in x parameter and return a new data.frame object with the columns defined between the start and end parameter in integer class, use this to transform columns with percent sign in integer or decimal.

colpct2num(x,start,end,div100)

x: a data.frame object
start: number of start column
end: number of end column
div100: if you need result in decimal form use this.

#Transform GDP growht column in percent.
usagdp=colpct2num(usagdp,start=3,end=3,div100=FALSE)
usagdp

##         Date GDP..current.US.. GDP.growth..annual...
## 1 2010-01-01          14.99205              2.563767
## 2 2011-01-01          15.54258              1.550836
## 3 2012-01-01          16.19701              2.249546
## 4 2013-01-01          16.78485              1.842081
## 5 2014-01-01          17.52175              2.451973
## 6 2015-01-01          18.21930              2.880910
## 7 2016-01-01          18.70719              1.567215
## 8 2017-01-01          19.48539              2.217010
## 9 2018-01-01          20.54434              2.927323

If values are in integer form, you can use the div100 parameter, see below:

#Transform GDP growht column in percent.
usagdp=colpct2num(usagdp,start=3,end=3,div100=TRUE)
usagdp=cbind(usagdp,"Function result"=usagdp2[,3])
usagdp

##         Date GDP..current.US.. GDP.growth..annual...   Function result
## 1 2010-01-01          14.99205            0.02563767 2.56376655876581%
## 2 2011-01-01          15.54258            0.01550836 1.55083550568156%
## 3 2012-01-01          16.19701            0.02249546 2.24954585236992%
## 4 2013-01-01          16.78485            0.01842081 1.84208107101102%
## 5 2014-01-01          17.52175            0.02451973 2.45197303536034%
## 6 2015-01-01          18.21930            0.02880910 2.88091046605219%
## 7 2016-01-01          18.70719            0.01567215 1.56721516997864%
## 8 2017-01-01          19.48539            0.02217010 2.21701033031884%
## 9 2018-01-01          20.54434            0.02927323 2.92732272821085%

colround

colround function receive a data.frame object in x parameter and return a new data.frame object with the columns defined between the start and end parameter rounded. To summarize, this function round columns.

colround(x,start,end,div100)

x: a data.frame object
start: number of start column
end: number of end column
digits: number of digits

#Round GDP columns
usagdp=colround(usagdp,start=2,end=3,digits=2)
usagdp

##         Date GDP..current.US.. GDP.growth..annual...
## 1 2010-01-01             14.99                  2.56
## 2 2011-01-01             15.54                  1.55
## 3 2012-01-01             16.20                  2.25
## 4 2013-01-01             16.78                  1.84
## 5 2014-01-01             17.52                  2.45
## 6 2015-01-01             18.22                  2.88
## 7 2016-01-01             18.71                  1.57
## 8 2017-01-01             19.49                  2.22
## 9 2018-01-01             20.54                  2.93

cuminyear

cuminyear calculates an accumulated variation in year of a index. Data must be start in january, use start to set this, if you data don’t start in january and you need use this values, consider complete the previous months with 0.

cuminyear(data,coldate,colnum,start)

data: a data.frame object
coldate: number of date column
colnum: number of values column
start: number of start row

randomts=data.frame("Date"=as.Date(seq.Date(as.Date('2019-01-01'),as.Date('2019-12-01'),'month')),
            "Values"=c(100,110,105,115,118,95,92,100,108,105,110,112)) #Creating a random time serie

cuminyear(randomts,coldate = 1,colnum=2,start=1)

##  [1]  0.00  0.10  0.05  0.15  0.18 -0.05 -0.08  0.00  0.08  0.05  0.10  0.12

As previously mentioned, the data must be start in january, see below examples of how to solve this problem.

randomts=data.frame("Date"=as.Date(seq.Date(as.Date('2019-04-01'),as.Date('2019-12-01'),'month')),
            "Values"=c(115,118,95,92,100,108,105,110,112)) #Creating a random time serie

# How we can see, data don't start in january, we have two ways to solve this:
# first -> complete data with first value:
randomts=merge.data.frame(x=data.frame("Date"=as.Date(seq.Date(as.Date('2019-01-01'),as.Date('2019-03-01'),'month')),"Values"=rep(randomts[1,2])),y=randomts,all = T)
cuminyear(randomts,coldate = 1,colnum=2,start=1)

##  [1]  0.00000000  0.00000000  0.00000000  0.00000000  0.02608696 -0.17391304
##  [7] -0.20000000 -0.13043478 -0.06086957 -0.08695652 -0.04347826 -0.02608696

# second -> using start parameter to define row to start
# In this case we need a more one year in data, lets create a new time serie.
randomts=data.frame("Date"=as.Date(seq.Date(as.Date('2018-09-01'),as.Date('2019-12-01'),'month')),
            "Values"=c(100,102,96,98,100,110,105,115,118,95,92,100,108,105,110,112))
#now we can start in third line, in 2019 january.
cuminyear(randomts,coldate = 1,colnum=2,start=5)

##  [1]    NA    NA    NA    NA  0.00  0.10  0.05  0.15  0.18 -0.05 -0.08  0.00
## [13]  0.08  0.05  0.10  0.12

cuminyear_var

cuminyear_var calculates an accumulated variation in year of a rate, _var means the data must be a percentage variation. Data must be start in january, if you data don’t start in january and you need use this values, consider complete the previous months with 0.

cuminyear_var(data,coldate,colnum,start)

data: a data.frame object
coldate: number of date column
colnum: number of values column
div100: if data percent are in integer representation, use this

randomts=data.frame("Date"=as.Date(seq.Date(as.Date('2019-01-01'),as.Date('2019-12-01'),'month')),
            "Values"=c(0.02,0.06,0.04,-0.06,-0.02,0.01,-0.06,0.03,0.08,0.01,0.05,0.03))

cuminyear_var(randomts,coldate = 1,colnum = 2)

##         Values
## 1   0.02000000
## 2   0.08120000
## 3   0.12444800
## 4   0.05698112
## 5   0.03584150
## 6   0.04619991
## 7  -0.01657208
## 8   0.01293076
## 9   0.09396522
## 10  0.10490487
## 11  0.16015011
## 12  0.19495461

As previously mentioned, the data must be start in january, see below examples of how to solve this problem.

randomts=data.frame("Date"=as.Date(seq.Date(as.Date('2019-04-01'),as.Date('2019-12-01'),'month')),
            "Values"=c(-0.06,-0.02,0.01,-0.06,0.03,0.08,0.01,0.05,0.03))
randomts

##         Date Values
## 1 2019-04-01  -0.06
## 2 2019-05-01  -0.02
## 3 2019-06-01   0.01
## 4 2019-07-01  -0.06
## 5 2019-08-01   0.03
## 6 2019-09-01   0.08
## 7 2019-10-01   0.01
## 8 2019-11-01   0.05
## 9 2019-12-01   0.03

# How we can see, data don't start in january,to solve this we can complete data with 0.
randomts=merge.data.frame(x=data.frame("Date"=as.Date(seq.Date(as.Date('2019-01-01'),as.Date('2019-03-01'),'month')),"Values"=rep(0)),y=randomts,all = T)
cuminyear_var(randomts,coldate = 1,colnum=2)

##         Values
## 1   0.00000000
## 2   0.00000000
## 3   0.00000000
## 4  -0.06000000
## 5  -0.07880000
## 6  -0.06958800
## 7  -0.12541272
## 8  -0.09917510
## 9  -0.02710911
## 10 -0.01738020
## 11  0.03175079
## 12  0.06270331

If your data are in integer representation, div100 parameter must be TRUE to correct results. See the div100 parameter used in below example.

randomts=data.frame("Date"=as.Date(seq.Date(as.Date('2019-01-01'),as.Date('2019-12-01'),'month')),
            "Values"=c(2,6,4,-6,-2,1,-6,3,8,1,5,3))
cuminyear_var(randomts,coldate = 1,colnum=2,div100=T)

##         Values
## 1   0.02000000
## 2   0.08120000
## 3   0.12444800
## 4   0.05698112
## 5   0.03584150
## 6   0.04619991
## 7  -0.01657208
## 8   0.01293076
## 9   0.09396522
## 10  0.10490487
## 11  0.16015011
## 12  0.19495461

cum_var

cum_var calculates an accumulated variation of a rate during a certain period of time, _var means the data must be a percentage variation.

cum_var(data,colnum,t,div100=F)

data: a data.frame object
colnum: number of values column
t: number of times to acummulate
div100: if data percent are in integer representation, use this

randomts=data.frame("Date"=as.Date(seq.Date(as.Date('2019-01-01'),as.Date('2019-12-01'),'month')),
            "Values"=c(0.02,0.06,0.04,-0.06,-0.02,0.01,-0.06,0.03,0.08,0.01,0.05,0.03))
cum_var(randomts,colnum=2,t=3,div100=F)

##       Values
## 1         NA
## 2         NA
## 3   0.124448
## 4   0.036256
## 5  -0.041952
## 6  -0.069588
## 7  -0.069588
## 8  -0.022118
## 9   0.045656
## 10  0.123524
## 11  0.145340
## 12  0.092315

If your data are in integer representation, div100 parameter must be TRUE to correct results. See the div100 parameter used in below example.

randomts=data.frame("Date"=as.Date(seq.Date(as.Date('2019-01-01'),as.Date('2019-12-01'),'month')),
            "Values"=c(2,6,4,-6,-2,1,-6,3,8,1,5,3))
cum_var(randomts,colnum=2,t=3,div100=T)

##       Values
## 1         NA
## 2         NA
## 3   0.124448
## 4   0.036256
## 5  -0.041952
## 6  -0.069588
## 7  -0.069588
## 8  -0.022118
## 9   0.045656
## 10  0.123524
## 11  0.145340
## 12  0.092315

pct_change

pct_change calculate the percentual change in t periods of a serie. We can use this function to calculate the acumulated variation of an index, for example to calculate the accumulated variation in 12 months just set t parameter to 12.

pct_change(data,colnum,t,nafill)

data: a data.frame object
colnum: number of values column
t: number of periods to accumulate
nafill: set value to fill NA’s before first t value

pct_change(usagdp,colnum=2,t=3)

##   GDP..current.US..
## 1                NA
## 2                NA
## 3                NA
## 4         0.1195831
## 5         0.1273383
## 6         0.1248558
## 7         0.1145282
## 8         0.1120692
## 9         0.1276145

num2month

num2month transform month numbers to month names.

num2month(date,abbreviate,ptbr)

date: a month numbers vector
abbreviate: abbreviate months name in result
ptbr: translate result to “Português (Brasil)”

randomts=data.frame("Month"=seq(from=1,to=12,by=1),
            "Values"=c(0.02,0.06,0.04,-0.06,-0.02,0.01,-0.06,0.03,0.08,0.01,0.05,0.03))
num2month(randomts[[1]])

##  [1] "january"   "february"  "march"     "april"     "may"       "june"     
##  [7] "july"      "august"    "september" "october"   "november"  "december"

Using abbreviate function and replacing in data.frame we have:

randomts[[1]]=num2month(randomts[[1]],abbreviate=TRUE)
randomts

##    Month Values
## 1    jan   0.02
## 2    feb   0.06
## 3    mar   0.04
## 4    apr  -0.06
## 5    may  -0.02
## 6    jun   0.01
## 7    jul  -0.06
## 8    aug   0.03
## 9    sep   0.08
## 10   oct   0.01
## 11   nov   0.05
## 12   dec   0.03

month2num

month2num transform month names to month numbers.

month2num

date: a month names vector

randomts=data.frame("Month"=c("january","february","march","april","may","june","july","august","september",
                              "october","november","december"),
            "Values"=c(0.02,0.06,0.04,-0.06,-0.02,0.01,-0.06,0.03,0.08,0.01,0.05,0.03))
month2num(randomts[[1]])

##  [1] "01" "02" "03" "04" "05" "06" "07" "08" "09" "10" "11" "12"

Is possible abbreviate months name.

randomts=data.frame("Month"=c("jan","feb","mar","apr","may","jun","jul","aug","sep",
                              "oct","nov","dec"),
            "Values"=c(0.02,0.06,0.04,-0.06,-0.02,0.01,-0.06,0.03,0.08,0.01,0.05,0.03))
month2num(randomts[[1]])

##  [1] "01" "02" "03" "04" "05" "06" "07" "08" "09" "10" "11" "12"

me.lag

me.lag lag a vector if t>0 or lead a vector if t<0.

me.lag

x: a vector
t: number of times to lag (default=1)
nafill: value to fill NA’s before first t value
extrapolate: if TRUE, extrapolate excedent values, only if t>0

#basic lag usage
me.lag(usagdp[[2]],t=3)

## [1]       NA       NA       NA 14.99205 15.54258 16.19701 16.78485 17.52175
## [9] 18.21930

#lag with extrapolate
me.lag(usagdp[[2]],t=3,extrapolate = TRUE)

##  [1]       NA       NA       NA 14.99205 15.54258 16.19701 16.78485 17.52175
##  [9] 18.21930 18.70719 19.48539 20.54434

#lead with me.lag
me.lag(usagdp[[2]],t=-3)

## [1] 16.78485 17.52175 18.21930 18.70719 19.48539 20.54434       NA       NA
## [9]       NA

me.spread

me.spread transforms columns into rows and rows into columns.

me.spread

data: a data frame
namenc: name of new column
mode: if results are incorretly try set this to TRUE

Preparing this document I needed to extract the usdgpd time series for the World Bank website, but the data should be prepared for a better explanation. In the process, after the variable filter step, the data were organized in a long format, see below:

##             Series name 2010-01-01 2011-01-01 2012-01-01 2013-01-01 2014-01-01
## 1     GDP (current US$)  14.992053  15.542581  16.197007  16.784849  17.521747
## 2 GDP growth (annual %)   2.563767   1.550836   2.249546   1.842081   2.451973

The me.spread functions can solve this problem. See how use the function and the result:

me.spread(usagdp_old)

##              GDP (current US$) GDP growth (annual %)
## 1 2010-01-01      14.992052727      2.56376655876581
## 2 2011-01-01      15.542581104      1.55083550568156
## 3 2012-01-01      16.197007349      2.24954585236992
## 4 2013-01-01       16.78484919      1.84208107101102
## 5 2014-01-01      17.521746534      2.45197303536034

If you want to turn back to the long mode just use the function again.

stattable

stattable make a descritive statistic table.

stattable

data: a data frame
horiz: if TRUE,data.frame come horizontal
mode: if results are incorretly try set this to TRUE

If your data is a time serie, don’t use date column in data parameter, to do this use brackets ([row,column]) like in example below.

stattable(usagdp[,2:3])

## # A tibble: 6 x 3
##   Statistic GDP..current.US.. GDP.growth..annual...
##   <chr>                 <dbl>                 <dbl>
## 1 "Min.   "              15.0                  1.55
## 2 "1st Qu."              16.2                  1.84
## 3 "Median "              17.5                  2.25
## 4 "Mean   "              17.6                  2.25
## 5 "3rd Qu."              18.7                  2.56
## 6 "Max.   "              20.5                  2.93

Graphic models functions

Graphic models function family do graphic creation easy, is recommended for new programers, they have less and easyful parameters then p.functions but the graphic customize is more limited. The simplest way to create graphs with the metools package are using the graph template functions, these functions use the plot functions (from metools) to get simplified arguments, using these functions we will have an easier but more limited creation of graphics.

gm.col

gm.col make a bar plot.

gm.col

data :a dataframe
ncolx: number of x column in data frame
ncoly: number of y column in data frame
ntimes: number of observations to plot (count by tail)
title:title of plot
xlab: x axis label
ylab: y axis label
div100: If data percent are not in decimal format set TRUE.
percent: If TRUE, y axis in percent
fontsize: change size of all words in graphic (only numbers)
cserie: change color of serie
clines: color of lines in graphic
ctext: color of words in graphic
cbackground: color of graphic background
cbserie: color of serie border

randoms=data.frame("Period"=letters[1:12],
            "Values"=c(2,6,4,-6,-2,1,-6,3,8,1,5,3))

gm.col(randoms,ncolx = 1,ncoly = 2,ntimes = 8,title = "Metools - gm.col",xlab = NULL,ylab = NULL)

gm.col_ord

gm.col_ord make a ordered bar plot.

gm.col

data :a dataframe
ncolx: number of x column in data frame
ncoly: number of y column in data frame
ntimes: number of observations to plot (count by tail)
title:title of plot
xlab: x axis label
ylab: y axis label
percent: If TRUE, y axis in percent
div100: If data percent are not in decimal format set TRUE.
dec: If TRUE, bars plot in decrescent order. fontsize: change size of all words in graphic (only numbers)
cserie: change color of serie
clines: color of lines in graphic
ctext: color of words in graphic
cbackground: color of graphic background
cbserie: color of serie border

randoms=data.frame("Period"=letters[1:12],
            "Values"=c(2,6,4,-6,-2,1,-6,3,8,1,5,3))

gm.col_ord(randoms,ncolx = 1,ncoly = 2,ntimes = 8,title = "Metools - gm.col_ord",xlab = NULL,ylab = NULL,cserie = 'yellow')

Using dec argumente we have:

gm.col_ord(randoms,ncolx = 1,ncoly = 2,ntimes = 8,title = "Metools - gm.col_ord",xlab = NULL,ylab = NULL,cserie = 'yellow',dec=TRUE)

gm.col_ord_wl

gm.col_ord_wl make a orderer bar plot with legend.

gm.col

data :a dataframe
ncolx: number of x column in data frame
ncoly: number of y column in data frame
ntimes: number of observations to plot (count by tail)
title:title of plot
legtitle: title of legend
xlab: x axis label
ylab: y axis label
dec: If TRUE, bars plot in decrescent order.
div100: If data percent are not in decimal format set TRUE.
percent: If TRUE, y axis in percent
fontsize: change size of all words in graphic (only numbers)
colors: colors of bars (a vector with the colors of each bar)
clines: color of lines in graphic
ctext: color of words in graphic
cbackground: color of graphic background
cbserie: color of serie border
legwpos: legend words position (numeric)
legheight: height of legend box

randoms=data.frame("Period"=letters[1:12],
            "Values"=c(2,6,4,-6,-2,1,-6,3,8,1,5,3))

gm.col_ord_wl(randoms,ncolx = 1,ncoly = 2,ntimes = 5,title = "Metools - gm.col_ord_wl",legtitle = NULL,xlab = NULL,ylab = NULL,legwpos = -2.5)

gm.col_wl

gm.col_wl make a bar plot with legend.

gm.col

data :a dataframe
ncolx: number of x column in data frame
ncoly: number of y column in data frame
ntimes: number of observations to plot (count by tail)
title:title of plot
legtitle: title of legend
xlab: x axis label
ylab: y axis label
div100: If data percent are not in decimal format set TRUE.
percent: If TRUE, y axis in percent
fontsize: change size of all words in graphic (only numbers)
colors: colors of bars (a vector with the colors of each bar)
clines: color of lines in graphic
ctext: color of words in graphic
cbackground: color of graphic background
cbserie: color of serie border
legwpos: legend words position (numeric)
legheight: height of legend box

randoms=data.frame("Period"=letters[1:12],
            "Values"=c(2,6,4,-6,-2,1,-6,3,8,1,5,3))

gm.col_wl(randoms,ncolx = 1,ncoly = 2,ntimes = 5,title = "Metools - gm.col_wl",legtitle = NULL,xlab = NULL,ylab = NULL,legwpos = -2.5)

gm.tscol

gm.tscol make a bar plot in time serie format. . The data don’t need be a ts object.

gm.tscol

data :a dataframe
ncolx: number of x column in data frame
ncoly: number of y column in data frame
ntimes: number of observations to plot (count by tail)
title:title of plot
ylab: y axis label
percent: If TRUE, y axis in percent
div100: If data percent are not in decimal format set TRUE.
fontsize: change size of all words in graphic (only numbers)
datebreaks: datebreaks in x axis (default=“1 month”)
dateformat: format of date in x axis (need a dataformat string) (default =“%Y-%m”)
clines: color of lines in graphic
ctext: color of words in graphic
cbackground: color of graphic background
cbserie: color of serie border

gm.tscol(usagdp,ncolx = 1,ncoly = 3,ntimes=12,title = "Metools - gm.tscol",datebreaks = "1 year",ylab = NULL,percent = TRUE,div100 = TRUE)

gm.tscol2

gm.tscol2 make a bar plot in time serie format, the difference in tscol2 is that you can choose the color of serie.The data don’t need be a ts object.

gm.tscol2

data :a dataframe
ncolx: number of x column in data frame
ncoly: number of y column in data frame
ntimes: number of observations to plot (count by tail)
title:title of plot
ylab: y axis label
percent: If TRUE, y axis in percent
div100: If data percent are not in decimal format set TRUE.
fontsize: change size of all words in graphic (only numbers)
datebreaks: datebreaks in x axis (default=“1 month”)
dateformat: format of date in x axis (need a dataformat string) (default =“%Y-%m”)
cserie: color of serie
clines: color of lines in graphic
ctext: color of words in graphic
cbackground: color of graphic background
cbserie: color of serie border

gm.tscol2(usagdp,ncolx = 1,ncoly = 3,ntimes=12,title = "Metools - gm.tscol2",datebreaks = "1 year",ylab = NULL,percent = TRUE,div100 = TRUE,cserie="orange")

gm.line

gm.line make a line plot.

gm.line

data :a dataframe
ncolx: number of x column in data frame
ncoly: number of y column in data frame
ntimes: number of observations to plot (count by tail)
title:title of plot
xlab: x axis label
ylab: y axis label
div100: If data percent are not in decimal format set TRUE.
percent: If TRUE, y axis in percent
fontsize: change size of all words in graphic (only numbers)
lwdserie: size of serie
cserie: color of serie
clines: color of lines in graphic
ctext: color of words in graphic
cbackground: color of graphic background

gm.line(usagdp,ncolx = 1,ncoly = 2,ntimes=12,title = "Metools - gm.line",xlab=NULL,ylab = NULL)

gm.tsl

gm.tsl make a line plot.

gm.tsl

data :a dataframe
ncolx: number of x column in data frame
ncoly: number of y column in data frame
ntimes: number of observations to plot (count by tail)
title:title of plot
ylab: y axis label
percent: If TRUE, y axis in percent
div100: If data percent are not in decimal format set TRUE.
fontsize: change size of all words in graphic (only numbers)
lwdserie: size of serie
datebreaks: datebreaks in x axis (default=“1 month”)
dateformat: format of date in x axis (need a dataformat string) (default =“%Y-%m”)
cserie: color of serie
clines: color of lines in graphic
ctext: color of words in graphic
cbackground: color of graphic background

gm.tsl(usagdp,ncolx = 1,ncoly = 3,ntimes=12,title = "Metools - gm.tsl",ylab = NULL,percent = TRUE, div100= TRUE,datebreaks = "1 year",dateformat = "%Y",lwdserie = 2)

Plot functions

The plot functions are the most complete way to make graphs using metools package, they have a significant amount of parameters for a better and more detailed customization of the graphs. Its functions start with the prefix p, these include one serie plot and some tools with colors and values for the axes. To plot more one serie, in plot functions have a multi plot functions, they have prefix mp.

p.line

p.line make a line plot.

p.line

randoms=data.frame("Period"=letters[1:12],
            "Values"=c(2,6,4,-6,-2,1,-6,3,8,1,5,3))

p.line(randoms,randoms[[1]],randoms[[2]],title = "Metools - p.line",xlab = NULL,ylab = NULL,note="With p. functions we can add note")

p.col

p.col make a bar plot.

p.col

data: a dataframe
xaxis: x axis data
yaxis: y axis data
ybreaks: number of y axis breaks (default=10)
percent: If TRUE y axis in percent (default=F)
yaccuracy: a round for y axis (default=0.01)
ydecimalmark: y decimal mark (default=“.”)
title: title of plot
xlab: x axis label
ylab: y axis label
stitle: subtitle
note: note
ctitles: color of titles (title,xlab,ylab)
cscales: color of the scales (default= same ctitles)
cbgrid: color of grid background
clgrid: color of grid lines
cplot: color of plot background
cserie: color of serie
cbserie: color of serie border (default= same cserie)
cticks: color of axis ticks
lwdserie: size of serie
pnote: position of note (default=1) (only numbers)
cbord: color of plot border (default= same cplot)
titlesize: size of title (default=20) (only numbers)
wordssize: size of words (default=12) (only numbers)
snote: size of note (default=11) (only numbers)
xlim: limit of x axis (default=NULL)

randoms=data.frame("Period"=letters[1:12],
            "Values"=c(2,6,4,-6,-2,1,-6,3,8,1,5,3))

p.line(randoms,randoms[[1]],randoms[[2]],title = "Metools - p.col",xlab = NULL,ylab = NULL,cscales="blue",note="With p. functions we have a powerful customize ")

p.col_ord

p.col_ord make a ordered bar plot.

p.col_ord

data: a dataframe
xaxis: x axis data
yaxis: y axis data
ybreaks: number of y axis breaks (default=10)
dec: if TRUE, serie come be decrescent, if FALSE crescent (default=FALSE)
percent: If TRUE y axis in percent (default=F)
yaccuracy: a round for y axis (default=0.01)
ydecimalmark: y decimal mark (default=“.”)
title: title of plot
xlab: x axis label
ylab: y axis label
stitle: subtitle
note: note
ctitles: color of titles (title,xlab,ylab)
cscales: color of the scales (default= same ctitles)
cbgrid: color of grid background
clgrid: color of grid lines
cplot: color of plot background
cserie: color of serie
cbserie: color of serie border (default= same cserie)
cticks: color of axis ticks
lwdserie: size of serie
pnote: position of note (default=1) (only numbers)
cbord: color of plot border (default= same cplot)
titlesize: size of title (default=20) (only numbers)
wordssize: size of words (default=12) (only numbers)
snote: size of note (default=11) (only numbers)
xlim: limit of x axis (default=NULL)

randoms=data.frame("Period"=letters[1:12],
            "Values"=c(2,6,4,-6,-2,1,-6,3,8,1,5,3))

p.col_ord(randoms,randoms[[1]],randoms[[2]],title = "Metools - p.col_ord",xlab = NULL,ylab = NULL,cbserie='blue')

p.col_ord_wl

p.col_ord_wl make a ordered bar plot with legend.

p.col_ord_wl

data: a dataframe
xaxis: x axis data
yaxis: y axis data
ybreaks: number of y axis breaks (default=10)
percent: If TRUE y axis in percent (default=F)
dec: if TRUE, serie come be decrescent, if FALSE crescent (default=FALSE)
yaccuracy: a round for y axis (default=0.01)
ydecimalmark: y decimal mark (default=“.”)
title: title of plot
xlab: x axis label
ylab: y axis label
stitle: subtitle
note: note
ctitles: color of titles (title,xlab,ylab)
cscales: color of the scales (default= same ctitles)
cbgrid: color of grid background
clgrid: color of grid lines
cplot: color of plot background
cbserie: color of serie border (default= same cserie)
cticks: color of axis ticks
lwdserie: size of serie
legtitle: title of legend box
legsize: size of legend
cleg: color of legend box
legheight: height of legend box
pnote: position of note (default=1) (only numbers)
cbord: color of plot border (default= same cplot)
titlesize: size of title (default=20) (only numbers)
wordssize: size of words (default=12) (only numbers)
snote: size of note (default=11) (only numbers)
legpos: legend position (default= right)
legdir: legend direction (default=“horizontal”)
legcol: color of legend box
legspa: spacement in legend box
legvjust: vertical adjust in legend box
colors: colors of bars, need same number of correspondencies.

randoms=data.frame("Period"=letters[1:12],
            "Values"=c(2,6,4,-6,-2,1,-6,3,8,1,5,3))

p.col_ord_wl(randoms,randoms[[1]],randoms[[2]],title = "Metools - p.col_ord_wl",xlab = NULL,ylab = NULL,legspa = 0.3,legvjust = -0.9,legsize = 12)

p.col_wl

p.col_wl make a bar plot with legend.

p.col_wl

data: a dataframe
xaxis: x axis data
yaxis: y axis data
ybreaks: number of y axis breaks (default=10)
percent: If TRUE y axis in percent (default=F)
yaccuracy: a round for y axis (default=0.01)
ydecimalmark: y decimal mark (default=“.”)
title: title of plot
xlab: x axis label
ylab: y axis label
stitle: subtitle
note: note
ctitles: color of titles (title,xlab,ylab)
cscales: color of the scales (default= same ctitles)
cbgrid: color of grid background
clgrid: color of grid lines
cplot: color of plot background
cserie: color of serie
cbserie: color of serie border (default= same cserie)
cticks: color of axis ticks
lwdserie: size of serie
legtitle: title of legend box
legsize: size of legend
cleg: color of legend box
legheight: height of legend box
pnote: position of note (default=1) (only numbers)
cbord: color of plot border (default= same cplot)
titlesize: size of title (default=20) (only numbers)
wordssize: size of words (default=12) (only numbers)
snote: size of note (default=11) (only numbers)
legpos: legend position (default= right)
legdir: legend direction (default=“horizontal”)
legcol: color of legend box
legspa: spacement in legend box
legvjust: vertical adjust in legend box
colors: colors of bars, need same number of correspondencies.

randoms=data.frame("Period"=letters[1:12],
            "Values"=c(2,6,4,-6,-2,1,-6,3,8,1,5,3))

p.col_wl(randoms,randoms[[1]],randoms[[2]],title = "Metools - p.col_wl",xlab = NULL,ylab = NULL,legspa = 0.3,legvjust = -0.9,legsize = 12)

In both p.col_wl and p.col_ord_wl we can change the colors of the bars, to do this just change the parameter colors. See an example below:

randoms=data.frame("Period"=letters[1:12],
            "Values"=c(2,6,4,-6,-2,1,-6,3,8,1,5,3))

p.col_wl(randoms,randoms[[1]],randoms[[2]],title = "Metools - p.col_wl",xlab = NULL,ylab = NULL,note='The p.gradientcolor will be explained later',legspa = 0.3,legvjust = -0.9,legsize = 12,
         colors=p.gradientcolor('blue','red',12))

p.tscol

p.tscol make a bar plot in time serie format. The data don’t need be a ts object.

p.tscol

data: a dataframe
xaxis: x axis data
yaxis: y axis data
dateformat: format of date in x axis (need a dataformat string) (default =“%Y-%m”)
datebreaks: datebreaks in x axis (default=“1 month”)
ybreaks: number of y axis breaks (default=10)
percent: If TRUE y axis in percent (default=F)
yaccuracy: a round for y axis (default=0.01)
ydecimalmark: y decimal mark (default=“.”)
title: title of plot
xlab: x axis label
ylab: y axis label
stitle: subtitle
note: note
ctitles: color of titles (title,xlab,ylab)
cscales: color of the scales (default= same ctitles)
cbgrid: color of grid background
clgrid: color of grid lines
cplot: color of plot background
cserie: color of serie
cbserie: color of serie border (default= same cserie)
cticks: color of axis ticks
lwdserie: size of serie
pnote: position of note (default=1) (only numbers)
cbord: color of plot border (default= same cplot)
titlesize: size of title (default=20) (only numbers)
wordssize: size of words (default=12) (only numbers)
snote: size of note (default=11) (only numbers)
xlim: limit of x axis (default=NULL)

p.tscol(usagdp,as.Date(usagdp[[1]]),usagdp[[2]],title = "Metools - p.tscol",xlab = NULL,ylab = NULL,datebreaks = "1 year",dateformat="%Y")

p.tscol probably will be the most used function of package, it will be further explored.
Are important pay attention in the xaxis parameter, the input don’t need be a ts object, but need be a vector in Date class. To certainly pass the correct class, you can use as.Date() in input of xaxis parameter. Other parameter to pay attention is the datebreaks, if i don’t set datebreaks equal 1 year in previous example, look the output:

p.tscol(usagdp,as.Date(usagdp[[1]]),usagdp[[2]],title = "Metools - p.tscol",xlab = NULL,ylab = NULL,dateformat="%Y")

This occurs because the default value of the parameter datebreaks is “1 month”, if the date column was in month it would have worked. So is important look at the date breaks of your data, and adjust correctly to datebreaks parameter.

p.tsl

p.tsl make a line plot in time serie format. The data don’t need be a ts object.

p.tsl

data: a dataframe
xaxis: x axis data
yaxis: y axis data
dateformat: format of date in x axis (need a dataformat string) (default =“%Y-%m”)
datebreaks: datebreaks in x axis (default=“1 month”)
ybreaks: number of y axis breaks (default=10)
percent: If TRUE y axis in percent (default=F)
yaccuracy: a round for y axis (default=0.01)
ydecimalmark: y decimal mark (default=“.”)
title: title of plot
xlab: x axis label
ylab: y axis label
stitle: subtitle
note: note
ctitles: color of titles (title,xlab,ylab)
cscales: color of the scales (default= same ctitles)
cbgrid: color of grid background
clgrid: color of grid lines
cplot: color of plot background
cserie: color of serie
cticks: color of axis ticks
lwdserie: size of serie
pnote: position of note (default=1) (only numbers)
cbord: color of plot border (default= same cplot)
titlesize: size of title (default=20) (only numbers)
wordssize: size of words (default=12) (only numbers)
snote: size of note (default=11) (only numbers)
xlim: limit of x axis (default=NULL)

p.tsl(usagdp,as.Date(usagdp[[1]]),usagdp[[2]],title = "Metools - p.tsl",xlab = NULL,ylab = NULL,datebreaks = "1 year",dateformat="%Y")

At least we will see in sequence plot tools and multi plot functions. Plot tools have same prefix that plot functions (p.), they too have a utility without graphic but your main objective is offer support to metools plot functions.

p.gradientcolor

p.gradientcolor is a function to make easy create gradient pallet. Recommended to color graphics created with metools p.functions.

p.gradientcolor

color1: First gradient color
color2: Last gradient color
n: Number of colors

p.gradientcolor(color1="white",color2="blue",n=10)

##  [1] "#FFFFFF" "#E2E2FF" "#C6C6FF" "#AAAAFF" "#8D8DFF" "#7171FF" "#5555FF"
##  [8] "#3838FF" "#1C1CFF" "#0000FF"

Using in a metools graphic we have:

p.col_wl(usagdp,format.Date(usagdp[[1]],format="%Y"),usagdp[[2]],xlab=NULL,ylab=NULL,title = "Metools - p.gradientcolor",colors = p.gradientcolor(color1="white",color2="blue",n=10),legspa = 0.25,legvjust = -1.1)

p.seqdatebreaks

p.seqdatebreaks is a function to break a time axis from graphic in specific interval. This function are recommended to select time interval of graphics created with metools p.functions.

p.seqdatebreaks

x: Time data from a Timeserie
periodicity: Time interval(string)

p.seqdatebreaks(x = as.Date(usagdp[[1]]),periodicity = "2 years")

## [1] "2010-01-01" "2012-01-01" "2014-01-01" "2016-01-01" "2018-01-01"

This function is already used automatically when you set datebreaks parameters in plot functions.

p.colorbypositive

p.colorbypositive is a function to create a vector with colors by positive or negative. Recommended to color graphics created with metools p.functions.

p.colorbypositive

x: a numeric vector colorp: Positive values color (default=Green)
colorn: Negative values color (default=Red)

v=c(-3,-2,2,-2,3,2)

p.colorbypositive(v)

## [1] "#B21717" "#B21717" "#17B221" "#B21717" "#17B221" "#17B221"

Using in a metools graphic we have:

randoms=data.frame("time"=1:length(v),"value"=v)

p.col(randoms,randoms[[1]],randoms[[2]],title="Meplot - p.colorbypositive",ylab=NULL,xlab=NULL,cbserie='black',
      cserie=p.colorbypositive(v))

p.colorbyvar

p.colorbyvar is a function to create a vector with colors by variation. Recommended to color graphics created with metools p.functions.

p.colorbyvar

x: a numeric vector colorp: Positive values color (default=Green)
colorn: Negative values color (default=Red)
lag: Lag to comparsion (default=1)

p.colorbyvar(v)

## [1] "#B21717" "#17B221" "#17B221" "#B21717" "#17B221" "#B21717"

Using in a metools graphic we have:

randoms=data.frame("time"=1:length(v),"value"=v)

p.col(randoms,randoms[[1]],randoms[[2]],title="Meplot - p.colorbyvar",ylab=NULL,xlab=NULL,cbserie='black',
      cserie=p.colorbyvar(v))

Finally we have the multi plotting functions, these functions have mp. prefix and basically apply the parameters of the meplot plot functions to a ggplot graphic object. Use this functions to plot more one serie in a graph.

mp.s

mp.s make a plot with one or more series. The object parameter require a ggplot object (Look at the examples).

mp.s

object: a ggplot graphic object
xaxis: one x axis of your graphics
yaxis: one y axis of your graphics
ybreaks: number of y axis breaks (default=10)
percent: If TRUE y axis in percent (default=F)
yaccuracy: a round for y axis (default=0.01)
ydecimalmark: y decimal mark (default=“.”)
title: title of plot
xlab: x axis label
ylab: y axis label
stitle: subtitle
note: note
ctitles: color of titles (title,xlab,ylab)
cscales: color of the scales (default= same ctitles)
cbgrid: color of grid background
clgrid: color of grid lines
cplot: color of plot background
cticks: color of axis ticks
pnote: position of note (default=1) (only numbers)
cbord: color of plot border (default= same cplot)
titlesize: size of title (default=20) (only numbers)
wordssize: size of words (default=12) (only numbers)
snote: size of note (default=11) (only numbers)
xlim: limit of x axis (default=NULL)

randoms=data.frame("Period"=letters[1:12],
            "V1"=c(2,6,4,-6,-2,1,-6,3,8,1,5,3),
            "V2"=c(4,2,-3,-5,-1,5,8,-2,7,3,5,3))

g=ggplot()+geom_line(aes(x=randoms[[1]],y=randoms[[2]],color='blue',group=1),lwd=1.5)+geom_line(aes(x=randoms[[1]],y=randoms[[3]],color='red',group=1),lwd=1.5)

mp.s(g,randoms[[1]],randoms[[3]],title="Metools - mp.s",xlab=NULL,ylab=NULL)

Other example:

g=ggplot()+geom_col(aes(x=randoms[[1]],y=randoms[[2]],group=1),color='black',fill='black',lwd=1.5)+geom_line(aes(x=randoms[[1]],y=randoms[[3]],group=1),color='red',lwd=1.5)

mp.s(g,randoms[[1]],randoms[[3]],title="Metools - mp.s",xlab=NULL,ylab=NULL)

mp.ts

mp.ts make plot in time serie format with one or more series. The data don’t need be a ts object. The object parameter require a ggplot object (Look at the examples).

mp.ts

object: a ggplot graphic object
xaxis: one x axis of your graphics
yaxis: one y axis of your graphics
dateformat: format of date in x axis (need a dataformat string) (default =“%Y-%m”)
datebreaks: datebreaks in x axis (default=“1 month”)
ybreaks: number of y axis breaks (default=10)
percent: If TRUE y axis in percent (default=F)
yaccuracy: a round for y axis (default=0.01)
ydecimalmark: y decimal mark (default=“.”)
title: title of plot
xlab: x axis label
ylab: y axis label
stitle: subtitle
note: note
ctitles: color of titles (title,xlab,ylab)
cscales: color of the scales (default= same ctitles)
cbgrid: color of grid background
clgrid: color of grid lines
cplot: color of plot background
cticks: color of axis ticks
pnote: position of note (default=1) (only numbers)
cbord: color of plot border (default= same cplot)
titlesize: size of title (default=20) (only numbers)
wordssize: size of words (default=12) (only numbers)
snote: size of note (default=11) (only numbers)
xlim: limit of x axis (default=NULL)

randoms=data.frame("Date"=seq.Date(as.Date("2019-01-01"),as.Date("2019-12-01"),by='month'),
            "V1"=c(2,6,4,-6,-2,1,-6,3,8,1,5,3),
            "V2"=c(4,2,-3,-5,-1,5,8,-2,7,3,5,3))

g=ggplot()+geom_line(aes(x=randoms[[1]],y=randoms[[2]],color='blue',group=1),lwd=1.5)+geom_line(aes(x=randoms[[1]],y=randoms[[3]],color='red',group=1),lwd=1.5)

mp.ts(g,randoms[[1]],randoms[[3]],title="Metools - mp.ts",xlab=NULL,ylab=NULL,dateformat="%m/%y")

You can use too the multiplot functions to have more types of graphics, the area graph is an example:

randoms=data.frame("Date"=seq.Date(as.Date("2019-01-01"),as.Date("2019-12-01"),by='month'),
            "V"=c(2,4,6,3,5,8,6,3,5,4,5,6))

g=ggplot()+geom_area(aes(x=randoms[[1]],y=randoms[[2]],group=1),color='blue',fill='blue',lwd=1.5)

mp.ts(g,randoms[[1]],randoms[[3]],title="Metools - mp.ts",xlab=NULL,ylab=NULL,dateformat = "%b")