-
Notifications
You must be signed in to change notification settings - Fork 11
/
wb_dims.Rd
155 lines (136 loc) · 7.33 KB
/
wb_dims.Rd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/utils.R
\name{wb_dims}
\alias{wb_dims}
\title{Helper to specify the \code{dims} argument}
\usage{
wb_dims(..., select = NULL)
}
\arguments{
\item{...}{construct \code{dims} arguments, from rows/cols vectors or objects that
can be coerced to data frame. \code{x}, \code{rows}, \code{cols}, \code{from_row}, \code{from_col}, \code{from_dims}
\code{row_names}, and \code{col_names} are accepted.}
\item{select}{A string, one of the followings.
it improves the selection of various parts of \code{x}
One of "x", "data", "col_names", or "row_names".
\code{"data"} will only select the data part, excluding row names and column names (default if \code{cols} or \code{rows} are specified)
\code{"x"} Includes the data, column and row names if they are present. (default if none of \code{rows} and \code{cols} are provided)
\code{"col_names"} will only return column names
\code{"row_names"} Will only return row names.}
}
\value{
A \code{dims} string
}
\description{
\code{wb_dims()} can be used to help provide the \code{dims} argument, in the \verb{wb_add_*} functions.
It returns a A1 spreadsheet range ("A1:B1" or "A2").
It can be very useful as you can specify many parameters that interact together
In general, you must provide named arguments. \code{wb_dims()} will only accept unnamed arguments
if they are \code{rows}, \code{cols}, for example \code{wb_dims(1:4, 1:2)}, that will return "A1:B4".
\code{wb_dims()} can also be used with an object (a \code{data.frame} or a \code{matrix} for example.)
All parameters are numeric unless stated otherwise.
}
\details{
When using \code{wb_dims()} with an object, the default behavior is
to select only the data / row or columns in \code{x}
If you need another behavior, use \code{wb_dims()} without supplying \code{x}.
\itemize{
\item \code{x} An object (typically a \code{matrix} or a \code{data.frame}, but a vector is also accepted.)
\item \code{from_row} / \code{from_col} / \code{from_dims} the starting position of \code{x}
(The \code{dims} returned will assume that the top left corner of \code{x} is at \code{from_row / from_col}
\item \code{rows} Optional Which row span in \code{x} should this apply to.
If \code{rows} = 0, only column names will be affected.
\item \code{cols} a range of columns id in \code{x}, or one of the column names of \code{x}
(length 1 only accepted for column names of \code{x}.)
\item \code{row_names} A logical, this is to let \code{wb_dims()} know that \code{x} has row names or not.
If \code{row_names = TRUE}, \code{wb_dims()} will increment \code{from_col} by 1.
\item \code{col_names} \code{wb_dims()} assumes that if \code{x} has column names, then trying to find the \code{dims}.
}
\code{wb_dims()} tries to support most possible cases with \code{row_names = TRUE} and \code{col_names = FALSE},
but it works best if \code{x} has named dimensions (\code{data.frame}, \code{matrix}), and those parameters are not specified.
data with column names, and without row names. as the code is more clean.
In the \code{add_data()} / \code{add_font()} example, if writing the data with row names
}
\section{Using \code{wb_dims()} without an \code{x} object}{
\itemize{
\item \code{rows} / \code{cols} (if you want to specify a single one, use \code{from_row} / \code{from_col})
\item \code{from_row} / \code{from_col} the starting position of the \code{dims}
(similar to \code{start_row} / \code{start_col}, but with a clearer name.)
}
}
\section{Using \code{wb_dims()} with an \code{x} object}{
\code{wb_dims()} with an object has 8 use-cases (they work with any position values of \code{from_row} / \code{from_col}),
\code{from_col/from_row} correspond to the coordinates at the top left of \code{x} including column and row names if present.
These use cases are provided without \code{from_row / from_col}, but they work also with \code{from_row / from_col}.
\enumerate{
\item provide the full grid with \code{wb_dims(x = mtcars)}
\item provide the data grid \code{wb_dims(x = mtcars, select = "data")}
\item provide the \code{dims} of column names \verb{wb_dims(x = mtcars, select = "col_names)}
\item provide the \code{dims} of row names \code{wb_dims(x = mtcars, row_names = TRUE, select = "row_names")}
\item provide the \code{dims} of a row span \code{wb_dims(x = mtcars, rows = 1:10)} selects
the first 10 data rows of \code{mtcars} (ignoring column names)
\item provide the \code{dims} of the data in a column span \code{wb_dims(x = mtcars, cols = 1:5)}
select the data first 5 columns of \code{mtcars}
\item provide a column span (including column names) \code{wb_dims(x = mtcars, cols = 4:7, select = "x")}
select the data columns 4, 5, 6, 7 of \code{mtcars} + column names
\item provide the position of a single column by name \code{wb_dims(x = mtcars, cols = "mpg")}.
\item provide a row span with a column. \code{wb_dims(x = mtcars, cols = "mpg", rows = 5:22)}
}
To reuse, a good trick is to create a wrapper function, so that styling can be
performed seamlessly.
\if{html}{\out{<div class="sourceCode R">}}\preformatted{wb_dims_cars <- function(...) \{
wb_dims(x = mtcars, from_row = 2, from_col = "B", ...)
\}
# using this function
wb_dims_cars() # full grid (data + column names)
wb_dims_cars(select = "data") # data only
wb_dims_cars(select = "col_names") # select column names
wb_dims_cars(cols = "vs") # select the `vs` column
}\if{html}{\out{</div>}}
It can be very useful to apply many rounds of styling sequentially.
}
\examples{
# Provide coordinates
wb_dims(1, 4)
wb_dims(rows = 1, cols = 4)
wb_dims(from_row = 4)
wb_dims(from_col = 2)
wb_dims(from_col = "B")
wb_dims(1:4, 6:9, from_row = 5)
# Provide vectors
wb_dims(1:10, c("A", "B", "C"))
wb_dims(rows = 1:10, cols = 1:10)
# provide `from_col` / `from_row`
wb_dims(rows = 1:10, cols = c("A", "B", "C"), from_row = 2)
wb_dims(rows = 1:10, cols = 1:10, from_col = 2)
wb_dims(rows = 1:10, cols = 1:10, from_dims = "B1")
# or objects
wb_dims(x = mtcars, col_names = TRUE)
# select all data
wb_dims(x = mtcars, select = "data")
# column names of an object (with the special select = "col_names")
wb_dims(x = mtcars, select = "col_names")
# dims of the column names of an object
wb_dims(x = mtcars, select = "col_names", col_names = TRUE)
## add formatting to `mtcars` using `wb_dims()`----
wb <- wb_workbook()
wb$add_worksheet("test wb_dims() with an object")
dims_mtcars_and_col_names <- wb_dims(x = mtcars)
wb$add_data(x = mtcars, dims = dims_mtcars_and_col_names)
# Put the font as Arial for the data
dims_mtcars_data <- wb_dims(x = mtcars, select = "data")
wb$add_font(dims = dims_mtcars_data, name = "Arial")
# Style col names as bold using the special `select = "col_names"` with `x` provided.
dims_column_names <- wb_dims(x = mtcars, select = "col_names")
wb$add_font(dims = dims_column_names, bold = TRUE, size = 13)
# Finally, to add styling to column "cyl" (the 4th column) (only the data)
# there are many options, but here is the preferred one
# if you know the column index, wb_dims(x = mtcars, cols = 4) also works.
dims_cyl <- wb_dims(x = mtcars, cols = "cyl")
wb$add_fill(dims = dims_cyl, color = wb_color("pink"))
# Mark a full column as important(with the column name too)
wb_dims_vs <- wb_dims(x = mtcars, cols = "vs", select = "x")
wb$add_fill(dims = wb_dims_vs, fill = wb_color("yellow"))
wb$add_conditional_formatting(dims = wb_dims(x = mtcars, cols = "mpg"), type = "dataBar")
# wb_open(wb)
}