| Topic | Teaching | Activity | Output to keep |
|---|---|---|---|
| Call existing functions | 10 min | 5 min | A checked function call and interpretation |
| Define and return a calculation | 10 min | 5 min | A saved temperature conversion |
| Arguments, composition and precision | 10 min | 5 min | Equivalent conversions and a rounding decision |
| Break | — | — | 10 min, recorded separately |
| Scope and vector inputs | 10 min | 5 min | A documented input/output contract |
| Validate inputs and recognise failures | 10 min | 5 min | A checked function and failure example |
| Check and hand over reusable code | 10 min | 5 min | A documented script with known-value checks |
| Total | 60 min | 30 min | 100 min overall, including the break |
This is lesson 3 of eight. The six room activities each take five minutes, including their room responses and debriefs. Complete Research Data first and open the project from Setup.
data folder. Its observations are historical country–year records. Temperature readings below are fictional teaching examples.functions_practice.R in the course project. Keep definitions before calls so the script runs from the beginning.You need a short description of the countries represented in the Gapminder data for 2007. R already provides functions for reading a table, counting its rows and calculating a mean. Before writing new code, find an existing operation and understand what it expects.
[1] "country" "year" "pop" "continent" "lifeExp" "gdpPercap" country year lifeExp
12 Afghanistan 2007 43.828
24 Albania 2007 76.423
36 Algeria 2007 72.301
48 Angola 2007 42.731
60 Argentina 2007 75.320
72 Australia 2007 81.235[1] 142The selection keeps country and year, which identify each record. The lifeExp column contains life expectancy in years. Inspect a few rows and the selected year before making a summary.
Room prediction: ask pairs whether nrow(gapminder_2007) counts countries, years or individual people. Take two reasons before running it.
[1] 67.00742[1] 67.01| Part | Meaning in this example |
|---|---|
round |
The function being called |
life_expectancy_mean |
The value supplied as its first argument |
digits = 2 |
A named argument controlling the number of decimal places |
| Returned result | A number that can be saved or passed to another function |
The mean gives each represented country equal weight. It is not a population-weighted global life expectancy or a summary of individual participants. That distinction follows from the input and calculation, even when the code runs successfully.
In the console, open ?mean and ?round. Read Usage, Arguments and Value; look for the missing-value and rounding choices rather than reading every detail.
[1] NA[1] 11[1] 1These three values are fictional. The first mean retains the effect of a missing value. The second excludes it deliberately and answers a different question. na.rm = TRUE does not recover the missing observation. Record exclusions and their reason in a research workflow.
Goal: connect a function’s arguments to the meaning of its result. Input: the Gapminder selection and fictional practice_readings above. Work in pairs in functions_practice.R.
gapminder_2007 represents and the unit of lifeExp.mean() and round() on the selected column. Compare the two mean(practice_readings) calls and inspect ?mean.na.rm = TRUE.Keep: the calls, their results and the two interpretation comments. If access fails: inspect the displayed selection and calculate the fictional non-missing mean on paper.
A collaborator sends temperature readings in Fahrenheit, while your analysis uses Celsius or kelvin. Repeating the conversion throughout a script creates several places where a formula could be mistyped. A named function gives the operation one implementation and a clear interface.
A function accepts arguments, performs its body and returns a result. A clear function can improve reuse and checking; it does not automatically make a calculation scientifically appropriate or computationally faster.
Room question: ask pairs to name one calculation they repeat in a spreadsheet or script and the units it expects.
The calculation has four parts: an input with a known unit, a fixed conversion, a result with a different unit and a check. Keep this operation separate from reading files, making plots or writing a report.
| Stage | Temperature example |
|---|---|
| Input | A value in degrees Fahrenheit |
| Operation | Subtract 32, multiply by 5 / 9, then add 273.15 |
| Returned result | The converted value in kelvin |
| Check | 32 °F should give 273.15 K |
A function should do one coherent job. Combining conversion, file import and plotting would make the calculation harder to test or reuse for a different table.
[1] 3function() defines the arguments and the code inside {}. R returns the last evaluated expression unless an explicit return() ends the function earlier. Names such as param1 illustrate the structure; use descriptive names in actual analysis.
[1] 309.8167The original course formula is retained. temp is in degrees Fahrenheit; the result is in kelvin (K), written without a degree sign. Defining the function does not yet perform a conversion; calling it supplies the input. The R manual explains function definitions and returned values.
[1] 309.8167[1] TRUESaving a returned value lets another calculation use it. return(kelvin) makes the output explicit here; the earlier addition function instead uses its final expression. Both approaches return a value.
print() and cat() display information; displaying a result alone does not define a useful return contract. In particular, cat() returns NULL, so a function whose final action is cat() will not return the displayed number for later calculation. Keep presentation separate from the conversion.
Room prediction: show temperature_k <- fahr_to_kelvin(98) and ask which name refers to a function and which refers to a converted value. Ask a pair to justify the distinction in the Environment panel.
Goal: keep a reusable calculation with a known-value check. Input: fahr_to_kelvin() above. Work in pairs using a saved script in the course project.
98; then check that 32 returns 273.15.Keep: the function and check. If access fails: calculate the 32 example on paper and annotate the definition.
A parameter is the name in the function definition; an argument is the value supplied in a call. A default supplies a value when the caller does not specify it. Use named arguments when they make a choice clearer.
The original task asks for a result rounded to two decimal places. Make that choice explicit:
[1] 309.82[1] 309.8[1] 309.8This uses a default argument and reuses the unrounded conversion. The last two calls give the same result because both arguments are named. A caller may override digits; omitting it uses 2. Name important choices and use full parameter names rather than relying on partial matching.
Retain full precision for subsequent calculations unless the analysis explicitly calls for rounding; rounding for a table is a presentation decision. The rounded helper is useful at that presentation boundary, while fahr_to_kelvin() remains the calculation to reuse elsewhere.
[1] 36.66667An equivalent composition converts to kelvin and then subtracts the offset:
[1] 36.66667The two paths should agree within floating-point tolerance. Names and documentation tell the caller which units to supply; a bare number does not encode its unit.
unrounded rounded_first
36.66667 36.67000 [1] 0.003333333The second path rounds kelvin before converting to Celsius, so its result differs slightly. This demonstrates a processing choice, not a change in the temperature formula. A display rounded to two decimal places does not imply that the source measurement is accurate to two decimal places.
Room prediction: ask which path retains more information for later calculations. Ask a pair where they would put rounding in a script that prepares both an analysis and a report table.
Goal: explain composition and rounding without changing the conversion. Input: the functions above. Swap operator and checker.
fahr_to_celsius() in your script using the demonstrated formula; compare its calls with the composed path for 32 and 98.Keep: both conversion examples and the precision note. If access fails: substitute 32 into both formulas and compare the steps.
Save functions_practice.R. On returning, swap operator and checker. Keep the unrounded conversions available for the remaining examples.
Parameters and variables assigned inside a function belong to that call. This makes temp a local parameter in the conversion, even when an object named temp also exists outside it.
[1] 273.15[1] 999The call converts 32 °F, and the outside temp remains 999. The local name kelvin stores an intermediate result inside the function; the caller receives its returned value. To keep that result outside, assign the call to temperature_k or another descriptive name.
If a function uses a name that is neither an argument nor defined locally, R can look in the environment where the function was defined. Such a dependence may be intentional, but an unexplained setting in the workspace makes a research calculation harder to rerun. Pass changing settings as arguments and keep fixed conversion constants visible.
Room prediction: before running the example, vote on whether the outside temp becomes 32, becomes 273.15 or stays 999. Take one reason from each position represented in the room.
These simple functions expect numeric Fahrenheit or kelvin values as named. R’s vectorised arithmetic also lets them convert a numeric vector:
[1] 0.00000 36.66667 100.00000The arithmetic is vectorised: it operates on each entry without requiring an explicit loop. Keep the association between each input and output.
reference reading missing boiling
0.00000 36.66667 NA 100.00000 [1] TRUE[1] TRUEThese labels identify the fictional teaching readings. The missing input stays in the same position as a missing output. This function does not discard readings, reorder them or fill a missing value with zero. NA_real_ explicitly represents a missing numeric value.
A contract tells the caller what the function expects and promises. For this temperature helper, record:
| Requirement | Choice for this lesson |
|---|---|
| Input shape and type | A numeric vector, including a single numeric value |
| Input unit | Degrees Fahrenheit |
| Missing observations | Retain their positions and return missing values |
| Output | A Celsius vector in the original order with names retained |
| Precision | Do not round inside the main conversion |
| Side effects | Do not change outside objects, read files or write outputs |
The original arithmetic can also operate on some other R structures, such as a numeric matrix. The checked interface in the next block deliberately accepts a vector only. Define a supported shape rather than letting accidental input determine the interface.
In a real workflow, decide whether missing readings should be retained, rejected or handled separately. That is an analytical decision to document. A short comment above the function should state the purpose, units and relevant assumptions.
Goal: explain which objects change and whether entries remain identifiable. Input: the scope example and named temperature_f vector above. Work in pairs, swapping operator and checker.
temp and the position of the missing converted reading.Keep: the named vectors, identity checks and contract comment. If access fails: draw four labelled input/output pairs and annotate the local and outside temp names.
temp stays 999. Length checks expose a dropped entry; comparing names checks the labels and their order. The missing entry remains missing at its original position.The simple conversion assumes its caller already supplies appropriate data. A helper used by collaborators or fed by an external file benefits from checks that reject unsupported inputs with an informative message.
| Input | Deliberate handling in the checked helper |
|---|---|
c(32, 98, 212) |
Return a numeric Celsius vector |
c(32, NA_real_, 212) |
Preserve the missing reading and its position |
"98" or a factor |
Reject the input; do not silently coerce it |
| A matrix or data frame | Reject the unsupported shape |
Inf or NaN |
Reject a non-finite value that is not the permitted NA marker |
Here Inf denotes infinity and NaN denotes a numerical result that is “not a number”. The helper accepts NA as the documented missing-value marker. It does not establish that a reading is scientifically plausible or that the caller has supplied the correct unit.
[1] 0 NA 100if evaluates a condition and runs its body when that condition is true. ! means “not”; || joins two single conditions with “or”. dim() identifies a matrix or array shape, and any() asks whether at least one entry matches a condition. stop() ends the call with an error instead of returning a misleading conversion.
This wrapper delegates the calculation to the original function, keeping one implementation of the formula. The missing-value policy is explicit, and unsupported input is neither discarded nor reinterpreted.
Expected rejection in this demonstration: temp must be a numeric vector in degrees Fahrenheit.This demonstration catches the deliberately triggered error only to display its message; it supplies no substitute measurement. In ordinary analysis, let an unexpected failure stop the workflow, inspect the offending input and correct its source or handling. Retain the error text when asking for help.
| Symptom | First useful check |
|---|---|
| Function not found | Was its definition run before this call? |
| Argument is missing | Does the call supply every required argument? |
| Numeric-vector error | Inspect str(input) and the column selected from the source |
| Unexpected result | Check units, missingness and one known conversion |
Room question: “If a collaborator supplies "98", what information must you check before deciding to convert that text to a number?” Expect discussion of the source format, units and other entries; changing type alone does not establish validity.
Goal: keep a useful failure visible while preserving permitted missing data. Input: checked_fahr_to_celsius() and the two demonstration calls above. Work in pairs.
c(32, NA_real_, 212) and to the text value "98".Keep: the checked function, a valid example and the expected rejection message. If access fails: annotate the checks and identify which branch each input follows.
NA different from returning zero after a failed conversion?”NA records a missing reading under the stated policy. Zero is a numerical temperature and would invent an observation. The text input is rejected until its meaning and format are checked.Each check connects a specific input to an expected result. stopifnot() stops if a condition fails; successful checks continue without printing a success message. all.equal() compares calculated numbers with a tolerance, and isTRUE() turns its answer into a single pass/fail condition.
A check that passes is evidence for those cases, not proof of every possible use. Do not truncate a measurement to an integer or change the expected value merely to make the comparison pass.
The final comparison uses only the named reference and boiling entries, whose expected conversions are known. unname() removes labels from that temporary comparison, because the expected vector has no labels; the retained converted vector still has its original names.
| Check | What it can reveal |
|---|---|
| 32 °F → 0 °C and 273.15 K | An incorrect offset |
| 212 °F → 100 °C | An incorrect multiplier or offset |
| Direct and composed paths | A disagreement between implementations |
| Names, length and missing position | Dropped or misidentified entries |
| Deliberately invalid input | A failure message that does not match the stated contract |
Two implementations may agree while sharing the same mistake. Compare with independently known values as well as with another path through the code.
For the workshop, keep functions_practice.R in this order:
Put a concise comment above each reusable helper: purpose, input/output units, missing-value policy and any default or rounding choice. Keep the definitions ahead of their calls.
As a later project grows, definitions can live in R/temperature_functions.R and their checks in a separate script. The following is a file-organisation example; run it only after creating and saving that definitions file:
source() evaluates saved commands; it does not install a package. Keep the relative file location, data source and instructions with the project so another researcher does not need objects left in your current Environment.
Room question: “Which parts of your calculation would disappear if you closed R without saving the script?” Take one answer about instructions and one about objects held only in memory.
Goal: make a conversion understandable and checkable by another researcher. Input: your saved conversion script. Work in pairs.
Keep: the documented script and checks. If access fails: annotate the instructor’s example with the contract and expected values.
str() and the help page to investigate an unexpected type or argument.You have explained an existing function call, saved conversion functions, documented their contracts and checked their arithmetic, record identity and failure handling. Next, apply repeated steps systematically in lesson 4: Iteration.
Next-week action: choose one repeated calculation from your own work, name its input/output units, put it in a cohesive function and retain one independently known-value check.
Course Overview · Previous: Research Data · Next: Iteration
