Skip to content

Commit 28eb88d

Browse files
author
Susan Vanderplas
committed
Update intro
1 parent bc58a97 commit 28eb88d

File tree

2 files changed

+333
-9
lines changed

2 files changed

+333
-9
lines changed

‎images/tools/RStudio-error-indicator-reserved.png

27.4 KB
Loading

‎part-gen-prog/00-intro.qmd

Lines changed: 333 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -26,9 +26,24 @@ The problem solving skills are the same for all programming languages, though, a
2626
Just as you wouldn't expect to learn French or Mandarin fluently after taking a single class, you cannot expect to be fluent in R or python once you've worked through this book.
2727
Fluency takes years of work and practice, and lots of mistakes along the way.
2828
You *cannot* learn a language (programming or otherwise) if you're worried about making mistakes.
29-
Take a minute and put those concerns away somewhere, take a deep breath, and remember the Magic School Bus Motto:
3029

31-
![For those who don't know, the Magic School Bus is a PBS series that aired in the 1990s and was brought back by Netflix in 2017. It taught kids about different principles of science and the natural world.](../images/gen-prog/ms-frizzle.png){fig-alt="A picture of Ms. Frizzle, a teacher with red curly hair and a lizard around her neck, saying 'Take chances, make mistakes, get messy'" width="50%"}
30+
::: column-margin
31+
Take a minute and put those concerns away, take a deep breath, and remember the Magic School Bus Motto:
32+
33+
![For those who don't know, the Magic School Bus is a PBS series that aired in the 1990s and was brought back by Netflix in 2017. It taught kids about different principles of science and the natural world.](../images/gen-prog/ms-frizzle.png){fig-alt="A picture of Ms. Frizzle, a teacher with red curly hair and a lizard around her neck, saying 'Take chances, make mistakes, get messy'"}
34+
:::
35+
36+
## Strategies for Programming
37+
38+
As you start to program, you will need to develop some skill at reading and interpreting error messages, breaking problems down into smaller parts, and thinking through what code instructs the computer to do.
39+
It's useful to at least mention some strategies here, though @sec-debugging goes into much more detail.
40+
41+
1. Google the error message (or put the code and the error into AI and ask it to explain why there is an error).
42+
43+
2. Make a list of steps or a flowchart illustrating what the code does, breaking the code down into smaller pieces each time.
44+
45+
Keep an eye out for how these strategies are used in @sec-basic-var-types and @sec-use-functions.
46+
3247

3348
## Programming Vocabulary: Hello World
3449

@@ -92,35 +107,344 @@ The "Hello World" program looks exactly the same in R as it does in python!
92107
In many situations, R and python will be similar because both languages are based on C.
93108
R has a more complicated history [@ihakaFutureHistory1998], because it is also similar to Lisp, but both languages are still very similar to C and often run C or C++ code in the background.
94109

110+
::: example
111+
### Reserved Word Errors {-}
112+
113+
What happens when we try to assign a new value to a reserved word? We'll learn more about **assignment** in the next chapter, but for now, know it is equivalent to setting the value of a variable.
114+
`x = 3` or `x <- 3` defines the variable $x$ as having the value 3.
115+
116+
::: panel-tabset
117+
118+
#### R {-}
119+
```{r}
120+
#| error: true
121+
122+
for <- 3 # <1>
123+
```
124+
1. We just tried to assign the value 3 to the word `for`. `for` is a reserved word and cannot have a different value assigned to it, so we get an unexpected assignment error.
125+
126+
When we assign the value of a non-reserved word, things work just fine:
127+
128+
```{r}
129+
x <- 3 # <1>
130+
```
131+
1. x is not a reserved word, so we can safely assign x the value 3 without getting any errors.
132+
133+
![RStudio alerts us to the syntax error in the left column of the editor window and even helps identify the error via mouseover text.](../images/tools/RStudio-error-indicator-reserved.png){#fig-assign-reserved-word fig-alt="A code line reading `for <- 3` has a red X next to the line number. Mouseover text says 'unexpected token '<-', expected 'LPAREN'." width="100%"}
134+
135+
#### Python {-}
136+
137+
```{python}
138+
#| error: true
139+
for = 3 # <1>
140+
```
141+
1. We just tried to assign the value 3 to the word `for`. `for` is a reserved word and cannot have a different value assigned to it, so we get an invalid syntax error located at the `=`.
142+
143+
When we assign the value of a non-reserved word, things work just fine:
144+
145+
```{python}
146+
x = 3 # <1>
147+
```
148+
1. x is not a reserved word, so we can safely assign x the value 3 without getting any errors.
149+
150+
:::
151+
152+
:::
153+
95154

96155
## Getting help
97156

98-
In both R and python, you can access help with a `?` - the order is just slightly different.
157+
In both R and python, you can access help with a `?` via the terminal/console.
158+
159+
::: demo
160+
### Demo: Getting Help {-}
161+
162+
::: panel-tabset
163+
#### R {-}
164+
```{r}
165+
#| eval: false
166+
167+
?list # Get help with the list function
168+
```
169+
170+
#### Python {-}
171+
172+
Sometimes, it is easier to start a python terminal outside of RStudio (or in the RStudio terminal window), as the `reticulate` R package that allows us to run python code doesn't always react the same as the normal python terminal.
173+
Help is one particular case where this seems to be true
174+
175+
```{python}
176+
#| eval: true
177+
help(list)
178+
```
179+
180+
```
181+
Help on class list in module builtins:
182+
183+
class list(object)
184+
| list(iterable=(), /)
185+
|
186+
| Built-in mutable sequence.
187+
|
188+
| If no argument is given, the constructor creates a new empty list.
189+
| The argument must be an iterable if specified.
190+
|
191+
| Methods defined here:
192+
|
193+
| __add__(self, value, /)
194+
| Return self+value.
195+
|
196+
| __contains__(self, key, /)
197+
| Return key in self.
198+
|
199+
| __delitem__(self, key, /)
200+
| Delete self[key].
201+
|
202+
| __eq__(self, value, /)
203+
| Return self==value.
204+
|
205+
| __ge__(self, value, /)
206+
| Return self>=value.
207+
|
208+
| __getattribute__(self, name, /)
209+
| Return getattr(self, name).
210+
|
211+
| __getitem__(...)
212+
| x.__getitem__(y) <==> x[y]
213+
|
214+
| __gt__(self, value, /)
215+
| Return self>value.
216+
|
217+
| __iadd__(self, value, /)
218+
| Implement self+=value.
219+
|
220+
| __imul__(self, value, /)
221+
| Implement self*=value.
222+
|
223+
| __init__(self, /, *args, **kwargs)
224+
| Initialize self. See help(type(self)) for accurate signature.
225+
|
226+
| __iter__(self, /)
227+
| Implement iter(self).
228+
|
229+
| __le__(self, value, /)
230+
| Return self<=value.
231+
|
232+
| __len__(self, /)
233+
| Return len(self).
234+
|
235+
| __lt__(self, value, /)
236+
| Return self<value.
237+
|
238+
| __mul__(self, value, /)
239+
| Return self*value.
240+
|
241+
| __ne__(self, value, /)
242+
| Return self!=value.
243+
|
244+
| __repr__(self, /)
245+
| Return repr(self).
246+
|
247+
| __reversed__(self, /)
248+
| Return a reverse iterator over the list.
249+
|
250+
| __rmul__(self, value, /)
251+
| Return value*self.
252+
|
253+
| __setitem__(self, key, value, /)
254+
| Set self[key] to value.
255+
|
256+
| __sizeof__(self, /)
257+
| Return the size of the list in memory, in bytes.
258+
|
259+
| append(self, object, /)
260+
| Append object to the end of the list.
261+
|
262+
| clear(self, /)
263+
| Remove all items from list.
264+
|
265+
|
266+
| copy(self, /)
267+
| Return a shallow copy of the list.
268+
|
269+
| count(self, value, /)
270+
| Return number of occurrences of value.
271+
|
272+
| extend(self, iterable, /)
273+
| Extend list by appending elements from the iterable.
274+
|
275+
| index(self, value, start=0, stop=9223372036854775807, /)
276+
| Return first index of value.
277+
|
278+
| Raises ValueError if the value is not present.
279+
|
280+
| insert(self, index, object, /)
281+
| Insert object before index.
282+
|
283+
| pop(self, index=-1, /)
284+
| Remove and return item at index (default last).
285+
|
286+
| Raises IndexError if list is empty or index is out of range.
287+
|
288+
| remove(self, value, /)
289+
| Remove first occurrence of value.
290+
|
291+
| Raises ValueError if the value is not present.
292+
|
293+
| reverse(self, /)
294+
| Reverse *IN PLACE*.
295+
|
296+
| sort(self, /, *, key=None, reverse=False)
297+
| Sort the list in ascending order and return None.
298+
|
299+
| The sort is in-place (i.e. the list itself is modified) and stable (i.e. the
300+
| order of two equal elements is maintained).
301+
|
302+
| If a key function is given, apply it once to each list item and sort them,
303+
| ascending or descending, according to their function values.
304+
|
305+
| The reverse flag can be set to sort in descending order.
306+
|
307+
| ----------------------------------------------------------------------
308+
| Class methods defined here:
309+
|
310+
| __class_getitem__(...) from builtins.type
311+
| See PEP 585
312+
|
313+
| ----------------------------------------------------------------------
314+
| Static methods defined here:
315+
|
316+
| __new__(*args, **kwargs) from builtins.type
317+
| Create and return a new object. See help(type) for accurate signature.
318+
|
319+
| ----------------------------------------------------------------------
320+
| Data and other attributes defined here:
321+
|
322+
| __hash__ = None
323+
```
324+
:::
325+
326+
:::
327+
328+
329+
::: example
330+
### Example: Debugging - Getting help with for loops {-}
99331

100332
Suppose we want to get help on a `for` loop in either language.
101333

102-
In R, we can run this line of code to get help on `for` loops.
334+
::: panel-tabset
335+
#### R {-}
336+
337+
To get help in R, we put a `?` in front of a function name to pull up the help file on that function.
338+
However, when we try this with a `for` loop by typing `?for` into the console, we get a + sign.
339+
340+
```
341+
> ?for
342+
+
343+
```
344+
345+
That isn't what we expected! The `+` sign indicates that R is still waiting for some input - we haven't given it a complete statement.
346+
But why is the statement not complete?
347+
Googling for "?for" in R gets us something -- a help page about [Getting Help with R](https://www.r-project.org/help.html).
348+
349+
We get a tiny hint here:
350+
351+
> Standard names in R consist of upper- and lower-case letters, numerals (0-9), underscores (_), and periods (.), and must begin with a letter or a period. To obtain help for an object with a non-standard name (such as the help operator ?), the name must be quoted: for example, help('?') or ?"?".
352+
353+
Is it possible that `for` is a non-standard name? Perhaps because it's a reserved word?
354+
We can try it out: `?"for"` (but first, we need to hit Escape while the console pane is selected, to get out of the incomplete command `?for`).
355+
And, that works! We get a complete statement (a `>` on the next line in the console waiting for more input), and the help page titled "Control Flow" pops up.
103356

104357
```{r}
105-
#| eval: !expr F
358+
#| eval: false
359+
?"for"
106360
?`for`
107361
```
108362

109-
Because `for` is a reserved word in R, we have to use backticks (the key above the `TAB` key) to surround the word `for` so that R knows we're talking about the function itself. Most other function help can be accessed using `?function_name`. The backtick trick also works for functions that don't start with letters, like `+`.
363+
Because `for` is a reserved word in R, we have to use quotes or backticks (the key above the `TAB` key) to surround the word `for` so that R knows we're talking about the function itself.
364+
Most other function help can be accessed using `?function_name`.
365+
The backtick trick also works for functions that don't start with letters, like `+`.
366+
367+
#### Python {-}
110368

111-
In python, we use `for?` to access the same information.
369+
In python, we try to use `?for` to access the same information (this works for many python functions).
112370

113371
```{python}
114-
#| eval: !expr F
115-
for? # help printed in the terminal
372+
#| eval: false
116373
?for # help printed in the help pane
117374
```
118375

119376
(You will have to run this in interactive mode for it to work in either language)
120377

378+
We can also just type in `help` in the python console.
379+
The prompt will change to `help> `.
380+
381+
We then type `for` at the help prompt.
382+
383+
```
384+
help> for
385+
```
386+
387+
This gets us:
388+
389+
```
390+
The "for" statement
391+
*******************
392+
393+
The "for" statement is used to iterate over the elements of a sequence
394+
(such as a string, tuple or list) or other iterable object:
395+
396+
for_stmt ::= "for" target_list "in" starred_list ":" suite
397+
["else" ":" suite]
398+
399+
The "starred_list" expression is evaluated once; it should yield an
400+
*iterable* object. An *iterator* is created for that iterable. The
401+
first item provided by the iterator is then assigned to the target
402+
list using the standard rules for assignments (see Assignment
403+
statements), and the suite is executed. This repeats for each item
404+
provided by the iterator. When the iterator is exhausted, the suite
405+
in the "else" clause, if present, is executed, and the loop
406+
terminates.
407+
408+
A "break" statement executed in the first suite terminates the loop
409+
without executing the "else" clause’s suite. A "continue" statement
410+
executed in the first suite skips the rest of the suite and continues
411+
with the next item, or with the "else" clause if there is no next
412+
item.
413+
414+
The for-loop makes assignments to the variables in the target list.
415+
This overwrites all previous assignments to those variables including
416+
those made in the suite of the for-loop:
417+
418+
for i in range(10):
419+
print(i)
420+
i = 5 # this will not affect the for-loop
421+
# because i will be overwritten with the next
422+
# index in the range
423+
424+
Names in the target list are not deleted when the loop is finished,
425+
but if the sequence is empty, they will not have been assigned to at
426+
all by the loop. Hint: the built-in type "range()" represents
427+
immutable arithmetic sequences of integers. For instance, iterating
428+
"range(3)" successively yields 0, 1, and then 2.
429+
430+
Changed in version 3.11: Starred elements are now allowed in the
431+
expression list.
432+
433+
Related help topics: break, continue, while
434+
```
435+
436+
437+
438+
Of course, we can also google "python for loop" and get [documentation that way](https://wiki.python.org/moin/ForLoop).
439+
When you are just learning how to program, it is often easier to read web documentation that provides lots of examples than the highly technical "manual" or "man" pages for commands that are shown by default^[In Linux, you access manual pages for commands by running `man <command-name>`. There is an old joke about running the command `man woman`, only to get the response `No manual entry for woman`, because there is no manual page that will help men understand women. Of course, in reality, there is also no command named `woman`...].
440+
This is completely normal -- manual pages are written for reference while programming (which assumes you know how to program), and tutorials online are written for people learning how to program.
441+
Reading manual pages is a skill that you develop over time.
442+
121443
w3schools has an excellent python [help page](https://www.w3schools.com/python/python_for_loops.asp) that may be useful as well.
122444
Searching for help using google also works well, particularly if you know what sites are likely to be helpful, like w3schools and stackoverflow.
123445
A similar set of pages exists for [R help on basic functions](https://www.w3schools.com/r/r_for_loop.asp)
446+
:::
447+
:::
124448

125449
::: callout-note
126450
## Learn More

0 commit comments

Comments
 (0)