Lesson 6 of 9
Module 3 · Coding with AI assistants
Some of the most useful jobs for an assistant involve no new logic at all: explaining code you inherited, writing documentation, and translating between R and Python. All three are easy to check.
Explain, line by line
Paste a function and ask: “Explain this line by line for someone who knows basic Python. Point out anything that could fail.” Then test one claim from the explanation yourself. Explanations can be wrong too, especially about what a library function does in edge cases.
Why test a claim, if the explanation sounds right? Because the explanation is produced the same way as code: as likely text. Suppose the assistant says "count ignores case". You can check that in one line on "ggccat", and in Read before you run you saw that it does not. One quick check tells you how far to trust the rest. The best claims to test are the ones about edge cases: what happens with empty input, with lower case, with missing values.
A useful explanation says why a line is there, not just what it says. "This line loops over the bases" repeats the code in words. "This line looks up each base's partner; it will fail for any letter not in the dictionary" tells you something you can check. If the explanation you get is the first kind, ask again for the second.
The same approach works on pandas code you have inherited. Asked to explain tg.groupby("dose")["len"].agg(["mean", "std"]), an assistant should say that it splits the table by dose, takes the length column in each group, and computes a mean and a standard deviation for each. A claim worth testing is how that standard deviation is calculated. Compute one group's value by hand, or with np.std(..., ddof=1), and see whether it matches. You learn the code and check the explanation at the same time.
Finally, turn it round. Once you have read an explanation, close it and explain the function in your own words, aloud or in a comment. Where you get stuck is where your understanding, or the explanation, has a gap. The project at the end of this module asks you to do exactly this for your own tool.
Document
Docstrings and type hints, as in the seqtools.py from Testing AI-written code, make code easier for people and for assistants to use correctly. Ask for them, then read them: a docstring that describes what the code should do, not what it does, is a bug report waiting to happen.
A docstring is the description in triple quotes at the start of a function; it is what help(gc_content) shows. A type hint, such as seq: str or -> float, records what kind of value goes in and comes out. Neither changes what the code does, which is exactly why they can drift apart from it. For example, an assistant might write "Return the fraction of G and C" above code that multiplies by 100 and returns a percentage. Anyone who trusts the docstring will be out by a factor of 100. Read each docstring against the code line by line, and check that every case it mentions, such as "case-insensitive" or "N stays N", is covered by a test.
A good docstring answers the questions a user would otherwise have to read the code to answer: what goes in, what comes out and in what units, and what happens with awkward input. For mean_quality, that means saying it expects a FASTQ quality string, that it assumes Phred+33 encoding, that it returns a mean Phred score rather than an error probability, and what it does with an empty string. Each of those is a fact a reader can check against the code and against the tests.
Docstrings and comments do different jobs. A docstring describes how to use the function from outside. A comment, a line starting with #, explains a choice inside it, as in the test file of Testing AI-written code: # "I" is ASCII 73; 73 - 33 = 40. Assistants tend to add comments that repeat the code, such as # add 1 to count. Keep the ones that say why, and delete the rest.
Go deeper: docstrings that test themselves
Python can check that the examples in a docstring are true. Inside the docstring, write a line starting with >>>, like an interactive session, then the expected output on the next line: >>> round(gc_content("GGCCAT"), 2) followed by 66.67. Running python -m doctest -v seqtools.py runs every such example and reports any whose output differs. This is the standard library’s doctest module.
Doctest compares the printed text exactly, character by character. That is why the example rounds the result: the unrounded value prints as 66.66666666666666, and one changed digit would fail. Doctests keep a docstring honest, because a docstring whose example is wrong now fails loudly. They suit simple examples; keep edge cases and error checks in pytest.
Translate R to Python
A colleague's R function, and a Python translation:
Translation is a good job for an assistant because the original gives you a ready-made test: both versions must return the same answer for the same input. The function below is the GC-content calculation again, written in R.
gc_content <- function(seq) {
bases <- strsplit(toupper(seq), "")[[1]]
100 * mean(bases %in% c("G", "C"))
}
round(gc_content("ggccat"), 2)What the R code does
gc_content <- function(seq) { ... }defines a function and stores it under the name gc_content; in R, <- means "assign".toupper(seq)turns the sequence into capitals.strsplit(..., "")splits it into single letters. Becausestrsplitcan split many strings at once, it returns a list with one entry per input string;[[1]]takes the first (and only) entry, a vector of letters.bases %in% c("G", "C")asks, for each letter, "is it G or C?" and gives a vector of TRUE and FALSE. Themeanof TRUE and FALSE values is the proportion that are TRUE, because R counts TRUE as 1 and FALSE as 0. Multiplying by 100 makes it a percentage. An R function returns the value of its last line, so noreturnis needed.- The [1] in the output is R's way of numbering printed values: the value that follows is element 1 of the result.
def gc_content_translated(seq: str) -> float:
bases = list(seq.upper())
return 100 * sum(b in ("G", "C") for b in bases) / len(bases)
print(round(gc_content_translated("ggccat"), 2))What the Python translation does
list(seq.upper())turns the sequence into capitals and splits it into a list of single letters, the equivalent of R'sstrsplit(toupper(seq), "")[[1]].b in ("G", "C") for b in basesasks the same "is it G or C?" question for each letter, giving True or False.sumadds them up, counting True as 1, and dividing bylen(bases)gives the proportion. Python has no built-in mean of True and False values, so the translation spells it out as a sum divided by a count.print(round(..., 2))rounds to two decimal places and prints the result. Python prints the bare number, without R's [1].
Both versions give 66.67 for "ggccat". That is a good start, but it is one normal example; the worked example below lists where the two languages part company.
Worked example · differences to watch when translating
missing values: R's
mean(c(1, NA)) is NA; pandas skips NaN by defaultempty input: R's mean of nothing is NaN; Python's division by zero is an error
Step by step. (1) Indexing. For the letters of "ggccat", R's bases[1] is the first letter, while Python's bases[1] is the second. Negative numbers differ too: in Python, x[-1] is the last element, but in R, x[-1] means "everything except the first". (2) Missing values. R's NA and pandas' NaN both mark a missing value. R's mean returns NA if any value is missing, unless you add na.rm = TRUE; a pandas column's .mean() leaves missing values out unless told otherwise. (3) Empty input. For "", R splits into zero letters, and the mean of zero values is NaN ("not a number"), so the function returns NaN quietly. The Python version divides by len(bases), which is 0, and stops with ZeroDivisionError.
What the answer means. Two versions that agree on "ggccat" can still behave differently on empty input, on missing values and on any code that picks elements by position. If your pipeline sometimes receives an empty sequence, the R version would pass NaN into the next step and the Python version would stop. Neither is wrong in itself, but they are not the same function until you decide which behaviour you want and test for it.
Run both versions on the same inputs, including awkward ones, and compare. Agreement on one normal example is not enough.
The biggest translation risks are in library defaults, because the code can look like a perfect line-for-line match while computing something different. Three examples are worth knowing. R's sd() divides by n − 1, as pandas' .std() does, but NumPy's np.std() divides by n unless you pass ddof=1. R's t.test() runs Welch's t-test by default, which does not assume the two groups have equal variances, while SciPy's scipy.stats.ttest_ind() assumes equal variances unless you pass equal_var=False. And an R factor carries an explicit order of its levels, such as control before treated, which tables and plots follow. A plain text column in pandas has no such order, and groupby sorts groups alphabetically, so an order set carefully in R can be lost in translation unless you make the column a pandas categorical with the same order.
None of these differences raises an error. A translated analysis can produce a p-value or an error bar that differs from the original for reasons that are invisible in the code. So when you ask an assistant to translate, ask it also to list every default that differs between the two functions it used, then check that list in the documentation and with a comparison on the same data.
R and Python both store decimals as double-precision numbers defined by the IEEE 754 standard for floating-point arithmetic. A clear explanation of why such numbers are inexact is Goldberg (1991), “What every computer scientist should know about floating-point arithmetic”, ACM Computing Surveys. Two correct translations can still differ in the last digits, because they add numbers in a different order.
So compare translations with a tolerance, not exact equality. R’s all.equal() uses a relative tolerance of about 1.5 × 10⁻⁸ by default, and Python’s math.isclose() uses 10⁻⁹. Choose the tolerance for your data’s scale and state it. A tolerance that is too loose would hide a real difference between the two versions.
Key point
For translations, the original is your test: same inputs, same outputs. Write those comparisons down as tests.
A second example. When translating an R function that normalises counts to counts per million, run both versions on the same small table: one ordinary sample, one sample with a zero count and one with a missing value. Save the R results to a file and write a Python test that loads them and compares, allowing for tiny rounding differences. That test then guards the translation every time you change it.
Further reading · Module 3Wilson et al. 2014: testing and review habits that apply to AI-written code too. · All reading for this course
Check your understanding
1. How do you check a translated function?
2. x[1] in R is which element, in Python terms?
3. What is the risk of an AI-written docstring?
Up next
Lesson 7
Privacy, security and licences