ВУЗ: Не указан
Категория: Не указан
Дисциплина: Не указана
Добавлен: 06.04.2021
Просмотров: 864
Скачиваний: 1
9.8. EXAMPLE
CIRCLE 9. UNHELPFULLY SEEKING HELP
The question lacks both specificity and background (though it is mercifully
brief). The answer to how to do the operation could depend on whether you
want it delivered, and what size it should be. And do you want anchovies? If
you provide background, you may get an answer that proposes a better—but
entirely different—way of getting nutrients into your bloodstream.
Do not confuse a warning with an error. There are two differences:
1. warnings say “warning” and errors say “error”.
2. the computation continues when there is a warning but is interrupted
when there is an error.
If there really is an error, then give the results of:
traceback()
The word “crash” is very ambiguous. It would be better if you didn’t use the
word at all. If you do use it, you need to explain
exactly
what you mean. In
addition to avoiding the use of vague words like “crash”, you can be informative
by displaying the results of
sessionInfo()
.
If error or warning messages are not in English and you are writing to an
English mailing list, then translating pertinent messages would be in your best
interest. But do show the real message as well.
If you are asking if method XYZ is implemented in R, then say that XYZ
stands for Xeric Yare Zeugma (and hence not X-raY Zoometry). Give a brief
explanation and a reference (preferably available online). The same technique,
or something suitably similar, may well go by a different name.
Did I say you should give the results of
sessionInfo()
? The more infor-
mation about the version of R you are using and your machine, the better. If
the information is accurate, that’s a plus.
9.8
Give a minimal, self-contained example
Note this does not say, “Give an example.” It says to give a minimal, self-
contained example. A minimal, self-contained example allows readers to repro-
duce the problem easily. The easier you make it for your readers, the more likely
you receive help.
The word “minimal” implies an optimization. Elements of that optimization
include:
•
Minimize the number of packages involved. Ideal is if a vanilla session
suffices.
•
Minimize the number of functions involved.
•
Minimize the size of any functions that are yours.
120
9.9. WAIT
CIRCLE 9. UNHELPFULLY SEEKING HELP
•
Minimize the number and size of datasets involved. If peculiar data are
required and your data are complicated, large and/or proprietary, then
make up some data that exhibits the problem.
Often the process of making a
minimal
example reveals the problem. If the
problem does not reveal itself, then keep these hints in mind:
•
Make your example easy to cut and paste. The
dput
function is sometimes
useful for this.
•
If the example involves random numbers, then use
set.seed
to make the
numbers non-random.
•
Using data that comes with R is often the easiest for your readers.
•
Format the code to be easy to understand—the space bar is an excellent
resource.
Your minimal, self-contained example should
never ever
include a line of code
like:
rm(list=ls())
There’s a special special place for those who try to lull their would-be helpers
into destroying their data.
It can not be emphasized enough that a message is putting yourself at the
mercy of strangers. If someone has the wit and knowledge to answer your
question, they probably have other things they would like to do. Making your
message clear, concise and user-friendly gives you the best hope of at least one
of those strangers diverting their attention away from their life towards your
problem.
9.9
Wait
Don’t send the message immediately. Wait some amount of time—at least 1
hour, at most 1.7348 days. Leave the room you’re in.
Now reread the message from a typical list member’s point of view. The
answer may become apparent. More likely you may see how the question could
be made more clear. Add information that only you know but which the message
assumes the reader knows. Imagine yourself going through all of the steps of
your problem from the beginning.
Send the message in plain text, not html.
Only send the message once. Just because you don’t immediately see your
message on the list does not mean it didn’t go through. Seeing the same message
multiple times annoys people and reduces the chances they will answer you.
There seems to be positive correlation between a person’s level of annoyance at
this and ability to answer questions.
121
Postscript
irgil
and I came upon the road leading to the bright world. We climbed
through an opening to see once again the stars.
Most of this was stolen from the archives of R-help (thieves are consigned to
Circle 9 [page
], as you’ll recall). Thanks go to Tim Triche, Jr. and especially
Mark Difford for help with the table of contents and the index, and for well-
placed prods. Mark’s version of the source document went through an inferno
of its own.
What spark of life there may be in these scribblings is due largely to the con-
tributors of R-help, and to Beatrice.
122
Index
1-D arrays,
tapply
,
Assignment operators,
Attributes,
see
Objects, S3 methods,
S4 methods
Backslashed characters,
see
Table
Braces, curly,
Breathe,
Calculating products,
see
Vectorization
safe, efficient calculation,
Capitalization,
Circle I,
virtuous pagans, floating point and
all that,
Circle III,
cold, dead weight of the past,
foreign tongues,
pain and pleasure of perfection,
Complex numbers,
Computing on the language,
Corrupted .RData,
Curly braces,
Data frame,
Double brackets versus single brackets,
Empty cells
aggregate, by, sapply, tapply
(behaviour),
split
and
sapply
,
Factors,
File extension conventions,
Floating Point Trap,
floating point,
numerical error and wrong calcu-
lation,
rank of a matrix,
Functions (R + other)
all.equal
,
as.numeric
,
cbind
,
c
,
data.table
,
ifelse
,
if
,
integrate
,
is.integer
,
is.matrix
,
max
,
pmax
,
return
,
Vectorize
,
aggregate
,
as alternative to
tapply
,
all.equal
,
apply
,
as.complex
,
as.integer
,
attach
,
by
,
as alternative to
tapply
,
data frames,
cbind
,
circle.area
,
do.call
,
for
,
123
INDEX
INDEX
getAnywhere
,
help.request
,
help
,
identical
,
ifelse
,
if
,
is.complex
,
is.integer
,
is.matrix
,
is.na
,
equality of missing values,
is.numeric
,
isTRUE
,
library
,
max
,
mean
,
memory.size
,
min
,
na.rm
,
outer
,
prod
,
quadratic.formula
,
range
,
rbind
,
read.table
,
replicate
,
require
,
return
,
rm
,
runif
,
sample
,
sapply
,
inside functions,
save
,
seq
,
sessionInfo
,
sqrt
,
str
,
subset
,
sum
,
system.time
,
tapply
,
alternatives,
see
by, aggregate
traceback
,
unique
,
update.packages
,
vapply
,
write.table
,
formatting,
passing information,
writing functions
consistency,
indenting,
simplicity,
spaces between (logical) opera-
tors,
Global Assignments,
memoization,
Green book,
see
S4 methods
Help (asking for),
rtfm
,
dput
,
help.request
,
sessionInfo
,
set.seed
,
traceback
,
update.packages
,
check the
faq
,
descriptive subject line,
filing bug reports,
hijack thread,
minimal example (value of),
read the posting guide,
repeating a message,
select best list,
special interest groups,
types of list,
vanilla session,
wait before posting,
Integers,
Namespaces,
::
(accessing public [exported] ob-
jects),
:::
(accessing private [non-exported]
objects),
accessing functions/objects with the
same name,
124