Paul Natsuo Kishimoto - article

Codes of conduct

2026-08-25T00:00:00+02:00

Over the last year and a half, I've watched with growing horror as “vibe coding” and similar practices have grown from niche to widespread, especially within Free Software communities. (This is only one facet of the concerted push by moneyed and powerful people to normalize LLM products like “generative AI” and their use. [1])

There are a few kinds of responses that are notable:

People eagerly drinking the Kool-Aid.
Those who've had a sip or gulp, but have expressed regret and stopped using the products. (See one recent example.)
People and groups making strong statements against the use of LLM products, for instance here.

(3) in particular have spoken to me because they include positive statements about what is good, valuable, and rewarding about both programming as a solo pursuit, and participation in Free Software projects and the communities that surround them. Many of these have resonated. On the individual side, in 2021 I named a project ‘genno’ after a Japanese type of hammer. This was a nod to the Acorn to Arabella project to build a wooden boat from scratch, whose videos helped me through many days of long COVID-19 lockdowns, and helped me appreciate the joy of focused and patient work, whether carpentry or coding. [2] On the collective side, my work developing research software has increasingly been driven by a desire to serve other researchers, especially those without the privileges I've enjoyed. Developing and maintaining research tools for (and with!) these people—rather than for well-resourced people and organizations—guides many of my choices. It's also immensely rewarding per se.

A palm held outwards in a 'stop' command. On it is written "AI. No, thanks!". The hand has six fingers. Image by Caolan McMahon.

As lovely as it is to see expressions of these shared values, there are still too many people in category (1), and they are inflicting severe and growing harms on Free Software projects both small and large. At least until the ‘AI’ bubble pops—and still then—it's clear that defensive measures are necessary to prevent unthinking or wilful behaviour [3] from undermining the labour I and we have done and want to be doing.

To this end I took a stab at drafting a Code of Conduct (CoC), one that I'll adopt for my own repositories and in cases where I am sole or lead maintainer with authority to make that change. In the text, I try to make clear the human values motivating what I do, which should also motivate anyone who I'd be happy to collaborate with. Refusal of LLM usage and users then comes as a direct and simple consequence of these values. I like this ordering because it starts with principles that should be stable, and then interprets how these apply to the current malaise, which may (one hopes) dissipate, but may also metastatize, or linger. [4] The values can remain stable even if the context does not. The list of references includes examples from other projects that were inspiring.

I'm mulling further steps, like moving more fully to Codeberg, Sourcehut, or self-hosting of code and infrastructure. Creating this CoC was a more basic step, and can help signal the ‘why’ and guide the ‘what’ and ‘how’ of the next ones.

I'll insist that contributors to my projects read it, but would also be grateful to anyone else who may want to share constructive comments or ideas.

[1]	This post isn't about the broader phenomenon, but you might check out Dan McQuillan's 2022 book “Resisting AI: An anti-fascist approach to artificial intelligence” (yes, that's pre-ChatGPT; it holds up) or this essay by S.K. Winnicki titled “I would be so ashamed to use generative AI, here's why”.

[2]	Software Carpentry is an organization whose name made this association explicit back in 1998.

[3]	Bad, even rancid, vibes, if you will.

[4]	The same folks who pushed crypto and NFTs before moving on to ‘AI’ will, unless stopped, certainly find another mechanism for their aims of extraction and amassing power.

Tutorial: Moderation, facilitation, and public speaking

2026-08-11T00:00:00+02:00

At the request of the IIASA Early Career Researchers (ECR) group and Capacity Development and Academic Training (CDAT) unit, I prepared and gave a 90 minute tutorial on “Moderation, facilitation, and public speaking”.

About 20 people attended.

LaTeX source for the slides is in my doc repository, here. I will update this post to link to a PDF shortly.

“…for all!”

2025-07-20T00:00:00+02:00

Last year I was fortunate to get to work with a new team of co-authors on a paper titled “Quantifying minimum mobility needs: the Who, the Where, and the Why.” The project afforded a little space to think about the concept of wellbeing, in particular how it relates to mobility, and to engage with some fascinating early literature on fundamental human needs.

This is a new kind of post for me, in which I'll share some commentary or spare thoughts on this paper. These are links and connections to other topics, authors, and ideas that didn't fit into the paper itself, yet were in my mind during and after the writing process and a source of motivation. To be clear, these are entirely my own thoughts; please don't attach them to my co-authors, or think that they've been through peer review.

A thought experiment

Suppose we could ask every person in the world a single, simple question: “Do you have wellbeing?” (or “Do you consider yourself to be well?”) and get from each a ‘yes’ or ‘no’ answer. Let's call this question Q1. Their answers would be Boolean (1 or 0, true or false) values that we could label x₁ ∈ {1, 0} for the first person we ask, x₂ for the second person, and so on to x_8000000000 and eventually x_N, where N > 8×10⁹ is the number of people on Earth. We can write X to denote a vector including all of these values or data points.

Next, we compute the function or statistic:

W¹(X) = x₁∧x₂∧…∧x_N

This is the logical conjunction of every x_i, i ∈ (1, N). It is a very simple function that has the value ‘yes’/1/true if—and only if!—every x_i is ‘yes’; in other words, if every person in the world says, “Yes—I have wellbeing.” If even one person says, “No—I do not have wellbeing,” then W¹(X) = 0.

I want to set up a few straw-man claims around this thought experiment, question, and function. To be clear, these are only sketches; I do not aim to give a full defense or discuss all the implications. The hope is rather to invite some responses and pointers: Is there already good writing on any of these ideas, or research that uses similar framing? If so, where?

Briefly:

W¹(X) is the most parsimonious and direct representation of the background notions and widely used language that both express and inform our shared understanding of “universal wellbeing.”
X and thus W¹ would be very hard to measure directly.
We can imagine alternatives to W¹(X), which we can label W²(…), W³(…), etc. These are different functions, that may be computed on the same data (x_i) or on different data (labeled y_i, z_i, etc.) whose values might approximate or proxy for values of X or W¹ that we do not observe directly. These alternate measures inevitably involve value judgements that replace the subjectivity of individuals with those of (the) researcher(s).
However convenient or useful, the alternate data or functions in (3) are “wellbeing indicators” only to the extent they (a) have precise definitions and (b) clear, empirical relationships with X/W¹.
Tension exists between fidelity to X/W¹ and ease of operationalization. Researchers face incentives to choose alternate data that seem more accessible, and to pick alternate measures W² etc. that can be computed on such data. Following these incentives blindly would tend to worsen the divergence from W¹.

These overlap, but I'll try to treat each in a separate section.

I also want to emphasize at the outset that, although the thought experiment may sound vaguely utilitarian (“the greatest good for the greatest number”), I am very much opposed to the so-called ‘TESCREAL’ bundle of ideologies and the way they are deployed in public discourse and research. This essay is in fact motivated by my worry that there is a risk of normalizing these ideologies through incautious choices (5).

1. Universal wellbeing

Many well-known aspirational declarations, statements, targets, goals, and initiatives use universal language, either directly or by implying universality or totality. One example is the Universal Declaration of Human Rights:

Article 3

Everyone has the right to life, liberty, and security of the person.

Others include many of the Sustainable Development Goals (SDGs), for instance:

Goal 2: Zero hunger

End hunger, achieve food security and improved nutrition and promote sustainble agriculture

or:

Goal 5: Gender equality

Acheive gender equality and empower all women and girls.

…and the names and goals of initiatives like:

It is worthwhile to take these at face value. In other words, I set aside the question of whether any one or all of these are merely aspirational, were made insincerely, and/or are promoted cynically: whether the proponents (signatories, member states, secretariats, philanthropies) don't actually mean that ‘everyone’, ‘all’ etc. should enjoy the unimpaired rights, material conditions, or capabilities described—merely that most people should, or perhaps more than enjoy them today. If we take these statements as written, function W¹(X) is clearly their most direct representation. If even one person lacks the thing in question (“security of the person”, “sustainable energy”, etc.), then x_i = 0 for some i, thus W¹(X) = 0, and the stated, universal goal or target is not met: not everyone has the thing. For instance, if one woman or girl is not empowered, then the goal to “empower all women and girls” is not achieved.

The case of a single exception sounds extreme, but is itself a well-known thought experiment. In the classic short story The Ones Who Walk Away From Omelas by Ursula K. LeGuin (which won Locus and Hugo awards in 1974) and Isabel J. Kim's Why Don't We Just Kill The Kid In The Omelas Hole (Nebula 2024, Locus 2025, Hugo nominee 2025), the “Omelas child” is a person for whom x_{Omelas child} = 0 —in a very stark and tragic sense. Many positive things are said about the quality of life for everyone else in the city of Omelas, yet W¹(X) = 0 for Omelas in particular, and for the world in which it exists. In pop philosophy the so-called trolley problem and other devices are sometimes used to frame similiar discussions: some frivolous, some useful.

It's not my aim here to discuss all these. It's only to observe that a statement like “Everyone except for the kid in the Omelas hole has the right to liberty,” is not what was endorsed by the signatories to the UDHR. On the other hand, if we say that a variable y_i is 1 if and only if (‘iff’) a person enjoys their right to liberty, then W¹(y_i) = 1 is unambiguously consistent with “universally enjoyed human rights.” W¹(y_i) = 0 just as clearly indicates that those rights are not universally enjoyed: they may be ‘widely’ enjoyed, or enjoyed by a lucky few, but not by ‘all’.

2. Practical realities, the ‘no’ answer, and Q2

If we tried to carry out the thought experiment, we would immediately run into difficulties. Some include:

It is not easy to translate Q1 from English into the native language of each person in the world. A word with the same denotation and connotation as ‘wellbeing’ may not exist (more on this shortly).
‘Yes’ and ‘no’ responses may not be very natural in each language.
The questioner and respondent inevitably stand in some social relationship to one another. Social desirability, power dynamics, and other well-known forms of response bias would interfere in obtaining a genuine answer from each person.
It would be very expensive to ask every person directly and collate the data. I'll come back to this in section 5, below.
Even if we did collect all x₁…x_N, this would be only a snapshot at a certain point in time; and we would not have information on changes to each individual x_i.

Another problem we would quickly meet is that many people would answer Q1 with a ‘no’, and that a ‘no’ answer, on its own, is not readily actionable. Surely we also want to know: what it is that prevents a person from feeling that they have wellbeing? Are they not empowered? Do they not have food, water, health, sanitation, mobility, or the enjoyment of certain rights? This supports our intention (surely virtuous) to help them address those barriers, and in so doing enable them, and eventually all, to have wellbeing.

To get this information we add a second question, Q2: “Why not?”

3. Subjectivity and objectivity

Q2 leads directly into a vast and murky swamp where things get very complicated. Q1 is constructed to, as far as possible, get a Boolean answer. In contrast, valid answers to Q2 must include the entire scope of human experience. Consider a very short selection of possible answers (for an exercise, write 10 or 100 more of your own):

No—I do not have wellbeing, because I am hungry and thirsty.
… I am cold.
… I am sick and can't get health care.
… my child is sick and can't get health care.
… my neighbour's child is sick and can't get health care.
… I hate my neighbour and wish to kill him, but the law forbids me and he remains alive.
… I want to own a sports car, but I don't.
… I want to own a private jet, but I don't.
… the slender-billed curlew is extinct, and I am inconsolably sad about this.

The core idea here is that every person has a subjective notion of their own ‘wellbeing’. When we ask Q1 to measure x_i and compute W¹(X), this is what we measure: whether every person has what they consider to be ‘wellbeing’.

Here's a passage from Max Horkheimer in a “Seminar on Needs” in 1942, translated by James Crane:

Thesis I. The juxtaposition of material and ideal needs proves untenable upon closer inspection. The unchanging adherence to such cissions [Scheidungen] leads to serious theoretical and political errors.

[…]

Thesis II. To speak generally, the ideal needs one might strive to fulfill are nothing other than the social form, the manner and mode, in which material needs are to be satisfied. When the demand for a pint of milk is raised, even from the mouth of a government official, it contains a number of “formal” elements, which are not expressly stated: that the milk is delivered in a clean container, that it contains no dangerous bacteria, that it has a certain fat content, etc. If one stuck strictly to the wording, the demand could be fulfilled; nevertheless, the child would be cheated. Dialectics recognizes that it is not only [elements such as] the nutritional value, the kind of container, and so forth, which play a role in whether the child is cheated. It is also crucial, for instance, that the father and mother do not suffer under the burden of senseless labor, and the child under the fear of losing them to it; that the child lives in an orderly house, that they have a good family doctor, that there is no exploitative [and terroristic] domination—which would necessarily be reflected in the very faces and being of the parents, and throughout the child’s whole environment, and which, in the long run, would spoil the milk so much more than a dirty container ever could. The social order is as much a part of the milk as its fat content.

In the drafting of our paper up through December 2024 we discussed for many hours very similar questions. This translation was published later, in March 2025. Our focus was on the needs-and-satisfiers frameworks of Max-Neef, Doyal & Gough, and others from the 1970s and 1980s. It seems clear to me that these authors were influenced (directly or indirectly) by, and attempting to elaborate, the earlier work of Horkheimer and his colleagues in the Frankfurt School.

The researcher/questioner in our thought experiment might face the temptation to depart from X and W¹ when they hear a Q1 ‘no’ and Q2 “…because my milk was not delivered in a clean container.” They might wish to respond: “Well, this matter of the cleanliness of milk containers is too complicated; I'm mainly trying to gather Q1 data and that's hard enough already. I will put you down as ‘yes’ on Q1, and I'll make a little asterisk here and a note: ‘adequate nutrition, but doesn't like the smudges on the bottle’.” In this case, the researcher has not measured x_i. They have chosen to substitute something else that we can call z_i: “wellbeing—notwithstanding food container cleanliness.” They use this to approximate x_i. In many cases z_i and x_i may have the same value, but not always.

I'll come back to alternates and approximations in the next section. For now, let's focus on what the researcher has done. Lists of fundamental human needs or rights often include ‘autonomy’ or related terms and concepts. Surely one essential aspect of autonomy is the autonomy to choose what matters to us; to construct meaning, including the meaning of ‘wellbeing’. People who lack the capability or freedom to do this —who are told by powerful people to not to complain, even though they do not have wellbeing— would surely answer Q1 with ‘no’, and might say to Q2 “…because I am denied the right to my own subjectivity and expression of what is essential to my wellbeing.”

This also is why we pose Q1 and Q2 to every person: if we asked a dictator to give us data x_i for each of his subjects, he could give ‘yes’ for every one without even consulting them. If asked directly, many of them would no doubt answer Q1 with ‘no’ and Q2 “…because I live under a dictator!”

Every possible answer to Q2 falls on an ethical continuum from unobjectionable to unconscionable. From the list of 10 answers above, few would object to (1), especially since the stated unmet needs align with some of the widely (not to say universally!) agreed SDGs. A researcher who says “I judge you to be well (z_i = 1) even though you say you do not have enough food to eat” would need to give a very strong justification for this choice. At the far extreme, accepting (6) would lead to a world of unpunished murder and assault in which the victims would certainly not have wellbeing. In this case, hopefully few would object to the researcher/questioner overruling the respondent. In the middle, (7) might trigger debate: do we accept that a person who has everything except a sports car can not be well? Do we psychoanalyze them and say, “What you actually lack is self-esteem; we can give you another way to achieve that, one that's less destructive. If that's your only complaint, we judge you to be otherwise well.”

My claim 3 is simply that reckoning with this spectrum is unavoidable. No matter how ‘objective’ or morally ‘neutral’ an approximation z_i is claimed to be, it encodes value judgements on the part of the researcher; ones that data subjects and readers are asked to accept. At the very least, I hope, we can do better to acknowledge, name, enumerate, and debate these judgements. To paraphrase another recent paper, “[acknowledging] subjectivity is a feature, not a flaw.”

4. Approximations and usefulness

Let's imagine a couple more kinds of alternates and approximations. One is:

W²(X) = N^− 1⋅∑_i ∈ Nx_i

…that is, the share of people in the world for whom x_i = 1. This is a different function from W¹, computed on the same data, but with a continuous value in the range (0, 1).

A second kind of approximation is to replace the infinite space of Q2 answers with a small, finite set of variables that express necessary conditions of wellbeing. (This is the link to the literature on fundamental/universal human needs, which tries to enumerate these, or at least give a finite number of categories.) For instance, suppose:

b_i = 1 if a person has adequate nutrition (even milk from a clean bottle!)
c_i = 1 if a person has access to health care.
d_i = 1 if a person has access to clean water.

Then define another variable a_i = b_i∧c_i∧d_i. We can either compute W¹(A), which is 1 if and only if all b_i = c_i = d_i = 1, or W²(A), the share of people for whom a_i = 1.

These approximations can certainly be more convenient and useful than x and W¹. For instance, W¹ will remain 0 until universal wellbeing is achieved; when the last person (the Omelas child) finally has wellbeing, W¹ will suddenly flip to 1. This makes it not much help as an ‘indicator’ or ‘metric’ for measuring progress, or to examine claims like “Action P will do more towards W¹ than action Q.” In contrast, it is much more helpful and tractable to be able to say: “Currently, W²(A) = 0.456. With Action P, W²(A) could increase to 0.6 in 10 years. With Action Q, W²(A) could increase to 0.7 in 20 years.” For this reason it is valid and valuable to establish, measure, and compute these alternate measures.

However, can be W²(X), W¹(A), or W²(A) be a “measure of [universal] wellbeing”? For W²(X), trivially yes: this function has the value 1.0 iff every x_i = 1, which then directly implies W¹(X) = 1. But suppose every a_i = 1, such that every person has water, health care, and calories, and thus W¹(A) = 1 and W²(A) = 1.0. Is universal wellbeing necessarily achieved? Just as trivially, no: every human in a pod in the world of The Matrix has water, health care, and calories, but that is a dystopia, not a world of universal human wellbeing.

To avoid confusing readers and one another, here are some simple practices that researchers can adopt:

If the topic of research is ‘[universal] wellbeing’ but X and W¹ are not used, define clearly the measures (data Y, Z, … and/or functions W³, W⁴, …) used instead.
Cite or provide evidence about how the chosen measures relate to X and W¹. If possible, give quantitative relationship(s) with specific parameters.
If such evidence does not exist or cannot be obtained:
- Don't refer to the alternate measures as measures of ‘wellbeing’. Choose a descriptive name that does not create ambiguity.
- At least give some qualitative discussion: In what ways might the measures depart from X and W¹?
- What real or imaginable conditions might exist such that, for instance, W²(X) is low, but the chosen alternate W³(Y) is high?
Acknowledge the subjective judgements encoded in researchers' choice of alternates. What is omitted or excluded? Is it proper for the researchers to make such exclusions?
Discuss other possible choices, and if possible test robustness of conclusions against these.

5. Convenient data and lock-in

In section (2) I noted that N > 8×10⁹ is a large number. Even for subpopulations, like smaller countries or cities, it would be difficult to talk to every person in order to collect all x_i and compute W¹ for that population. In section (4) I noted that it is valuable, even necessary, to seek approximations. However, this doesn't mean that any chosen approximation is valid or helpful. It's entirely possible for such choices to be bad.

At one end of a spectrum of resolution, aggregate economic statistics such as GDP have been taken as measures related to wellbeing, directly or via functions with similarly coarse resolution. As we noted in our paper, the early literature on fundamental human needs, nearly 50 years ago, already pointed out the inadequacy of this approach.

At the far extreme of resolution, ‘big data’ have gained popularity in recent years because of their convenience: they afford to researchers the possibility of getting a large number of data points at a relatively low cost (to the researcher). Particularly, access to such data seems to remove any need for researchers to have direct contact with “data subjects.”

Anyone who has worked with such data can attest that there is a trade-off between the number of data points and fitness for whatever purpose(s) a researcher has in mind (here, measuring individual and collective wellbeing). The data have usually been amassed through a system, constructed and controlled by some other entity (often a large, for-profit company) that has a purpose different from the researchers. For example, the goal of Alphabet/Google in collecting map data and users' location data is ultimately to make a profit by selling advertisements, for instance to businesses in the same area. They collect data that can be used to this end, or to attendant ends like drawing in ad-viewers with free services. In some cases, researchers can overcome this divergence in purpose with methodological creativity, deriving measures for quantities of interest in ways that can be validated and tested. In other cases, researchers abandon their original goals and questions, and instead devise new ones that are answerable with the data offered to or obtained by them. For instance, Q1/Q2 above might get replaced with “Has this user visited a McDonald's in the past N days?” Sometimes these choices are later rationalized, more or less weakly: “visiting McDonald's might mean eating; eating is part of getting adequate nutrition; and this is a fundamental human need and a component of wellbeing.”

Even if (a big if!) valid and empirically grounded of measures of wellbeing can be constructed from such data, there is substantial risk of lock-in. If wellbeing is chiefly measured through the particular form of location data collected and provided by Alphabet (or whomever), and methods built on those data, then it is constructed as a thing that both (a) is not measurable without Alphabet's cooperation and system of data collection, and (b) can be known without ever asking any person Q1 directly. Both of these seem to be immense flaws: (a) because it creates total dependency on the data-gathering apparatus and the people who control it; and (b) because the subjectivity of “data subjects” is entirely alienated. [1] Researchers risk becoming cheerleaders for total surveillance and its practitioners, even if—like the dictator in section (3) above—the very existence and harms of such systems would be cited by many as the reason for a lack of wellbeing.

[1]	At some point I'll write more on these two very different uses of ‘subject’.

Please don't feed me slop

2025-02-18T00:00:00+01:00

A parable

Imagine you make a new acquaintance through friends, and through a brief conversation learn that the other person shares your love of food and cooking. They invite you to come over one evening for a “home cooked meal,” and you gladly accept!

Once you arrive and sit down for dinner, they hand you a plate with some…shapes on it. These shapes look like food, more or less: one seems potato-shaped, another is shaped like a chicken wing.

“Er, thanks,” you stammer. “You, um, made this?”

“Yes!” your host beams.

Too polite to say anything else, you take a few bites. The ‘food’—well, it seems to be food, it's kind of hard to say what it tastes like, but at least nothing bad—has a sort of strange texture that's more or less the same for the ‘potato’ and the ‘chicken wing’, and again hard to place.

Your host is eating with gusto, but increasingly you feel uneasy about what, exactly, you're eating. Finally you ask, “Sorry, but I'm a little curious—how did you make this?”

“Oh, I used this amazing new ‘generative cooking’ service that just popped up in this neighbourhood. It's free and easy to use: you just put some ingredients into it—and I shop at a high-end grocer, so I've got only the finest produce, meat, spices, and such in my fridge—and out pops a cooked and plated meal!”

“…”

“Sometimes there are bones or it tastes a little off, but you just feed it back into the hopper a few times and eventually it gets it right—mostly. It's such a life-saver; I was so busy today and thought I wouldn't have time to prepare the meal, yet here we are!”

What exactly has happened here? You took time to visit someone's home based on what you believed was a shared understanding of what “home cooked” food (per their verbal invitation) was. Instead, you were fed some kind of slop or spam.

Your host didn't ‘prepare’ it in the sense of cooking a meal themself, but rather used some machine—new and unknown to you, created or operated by some other person that you don't know—to extrude something that only superficially resembles food that might be prepared by a real person.

They didn't tell you that they would or did do this, but allowed you to believe it was their “cooking,” in the end forcing you to raise the topic and discover the truth.

Why?

I'm writing this because, with increasing frequency, I encounter people and try to interact with them as if they were fellow scholars, researchers, or scientists. But, instead, I am sent slop that has been extruded by “generative artificial intelligence (genAI)” tools [1] —often without mention that this is what the other person has done. Other times, I begin to work with someone and invest my effort on my parts of the work, then later realize that one or more of my collaborators have been pasting genAI output into a shared document, instead of their own writing.

I recognize that this is a contested area. For a contrasting example, consider the long-established norms on plagiarism and citation in academic work. These norms may not be uniform, or universally and consistently obeyed, but nonetheless they cohere and can be explained and learned. Most importantly, when we encounter other scholars, we can reasonably expect that they've learned and adhere to some kind of norms against plagiarism, or for citation. We may have to fish a little to understand precisely what they believe; if they are a student, they may need some coaching and reminders on what passes for normal behaviour in our shared fields.

Because ‘genAI’ is new, none of this is the case; norms are still being formed. So this post is not an attempt to speak for anyone beyond myself. It is slightly normative in that I do hope that other researchers, especially those I work with, will find this a valid and compelling perspective and approach. But I have only limited ability to affect that; so this is mostly descriptive of what I, myself, will and won't do, and why.

[1]	usually based on large language models (LLMs) or other types of machine learning (ML).

tl;dr

Even if you don't read the rest of this post, here are a few simple rules:

Please, if you send me something—text of any kind, code, data, images, etc.—prepared using ‘AI’, tell me up-front (a) that you've done this and (b) precisely how.
If you plan to do #1 in the course of a research project, collaboration, editorial process, etc., warn me in advance.
Understand and respect that it is my prerogative to not engage or work with you because you have (or have not) done #1 or #2, or because of how you've done them.

The title of this post may be easier to remember: please don't feed me slop.

A few more points

There's a lot to be said about ‘genAI’ and the people creating and promoting it—too much to write here.

Thinking together

To me, the core issue is the one illustrated by the parable above. I became and remain a researcher because I enjoy thinking (about certain topics, in certain ways). Research collaboration is enjoyable because the other humans whom I prefer to work with have interesting thoughts. It's exciting and helpful for me to think together with them: I enjoy when I can make them understand an idea I've had, or when they show me a new way of thinking about a problem or phenomenon, a new way of doing something, etc.

When I'm handed slop, I am deprived of the chance to do these things. Eating slop means I am spending my time, instead, looking at a sequence of words or pixels that, although they may statistically resemble text written by a person, do not capture any thinking on the far side. My thoughts and ideas are not being stimulated by someone's genuine effort to communicate their ideas to me, but by the mental equivalent of junk food. Eating slop also means I have to grapple with the awareness that the person who has sent the slop does not respect me enough to do the work of sharing their thoughts with me: that they think I'm not worth that effort. This makes it impossible to build the kind of collegial relationship that, in the best case, exists between fellow researchers: why should I invest in trusting someone whose actions communicate that they don't trust me?

Again, I understand that this is a novel area for many people. A person may not intend to or be aware that sending me slop communicates a lack of trust. [2] But the impact is what matters, not the intent.

Systemic discrimination and exclusion

I have worked with and know many excellent researchers from non-English backgrounds. I know that it is a difficult language to learn and master (especially academic English); this is an obstacle unjustly faced by some researchers and not others merely by accident of where they were born. Even after immense and hard work they may invest to learn a second/third/etc. language, people still face unfair discrimination for ‘non-native’ proficiency, or ignorance/lack of appreciation of that investment.

However, using genAI tools to ‘fake’ such proficiency is not and can never be a real solution to these forms of systemic discrimination and disadvantage. Systemic problems need systemic reform. Worse: it actively gets in the way of the practice and effort necessary to improve one's own real skills. It does not reclaim power for the disempowered, but rather transfers it (and much wealth) to the people who make and promote the use of ‘AI’ tools.

The analogy of plagiarism to doping in sport has been made many times, but fits even better the use of ‘AI’: if scholarship and academic systems reward and select for people who can exploit ‘AI’ best, not only will actual research skills be devalued, but people who already have power, wealth, and other social advantages will find it easier to dope and to get away with doping.

Mentorship and training

I choose to spend some of my time mentoring students so that those students can learn and develop their own skills. I am especially excited if I can help them learn certain kinds of research thinking that I enjoy and believe should be more widely practiced, or help them to overcome discrimination based on gender, language, race, and other characteristics. For this reason, I think I would be a poor mentor if I encouraged or permitted students to use ‘genAI’ tools—except in narrow, deliberative ways.

For instance, there is a particular skill to closely read many papers from the literature, deeply understand what the authors are trying to say, and write a concise review/synthesis. A student who only uses ‘genAI’ tools to produce ‘summaries’ is missing an important opportunity to learn and refine this skill. In turn, that undermines all the other academic skills built on top of it. A mentor who permits or encourages a student to do this is sending the signal that what matters is the ‘content’, output, or text—when in fact what matters is the student's ability to do the thinking that precedes any text.

What do you think?

This is written off-the-cuff and to avoid repeating the same arguments in more e-mails. I may come back to expand this text or add citations to more in-depth work and writing by others. But—what do you think? Are you aware of other good examples (or counter-examples) of stated practice in research and scholarly behaviour that I can learn from? If so, please do get in touch to share.

[2]

In particular, some people view research not as I describe here, but as a process of producing products—articles, reports, data sets, etc. In this view, it doesn't matter whether the products are good in any sense—for instance whether they contain ideas or express thinking that are sound an interesting—only that they appear to. This is in tension with my view of scholarship-as-thinking; it depresses me that people think this way, and if they do I would rather not work with them.

Effective strategies for multi-sectoral research using large-scale models

2021-06-23T00:00:00+02:00

A talk given at the 2021 meeting of the International Symposium for Sustainble Systems and Technology.

Slides (PDF, 436 kB) at IIASA PURE
Recording on YouTube
TeX source and BibTeX citation on GitHub

Abstract

Large-scale integrated assessment models (IAMs) have become critical knowledge objects and tools for global-scope simulation of energy, economic, engineering, and environmental systems. IAMs are widely used in assessment of climate change mitigation (for instance, within the IPCC) and other Sustainable Development Goals (SDGs). In order to sharpen the relevance of insights from large-scale modeling, researchers often link them into multi-model frameworks together with detailed sectoral (sub-)models of, for instance, transport and mobility; the building stock; critical materials; or water use—or with models of narrower scope (e.g. national or sub-national) but finer resolution. These links capture feedbacks and interactions that may strongly shape transitions to comprehensive sustainability.

This presentation begins with current expectations that guide IAM-based research. In particular, it is no longer satisfactory that individual models and 1-to-1 frameworks can analyse, for instance, (a) possible recoveries from the COVID-19 pandemic; (b) the long-term evolution of transport and mobility; and (c) the energy and climate impacts of changing materials flows. Increasingly, stakeholders require assessments that are both integrated and highly detailed in multiple sectors/areas such as these. Teams are challenged to produce this knowledge while also progressing in openness, transparency, reproducibility, and validity of research.

I argue that meeting these challenges requires systems researchers and modelers to acknowledge that they are engaged in processes of collaborative software development: models are, in an important sense, also complex, long-lived, and evolving pieces of software. This perspective motivates the use of strategies that are common in professional software development, yet woefully underutilized in academia and research: standardization, testing, modularity and reuse, an emphasis on documentation, and iterative workflows with short cycle times.

Using the example of the MESSAGEix-GLOBIOM family of models developed by the IIASA Energy, Climate, and Environment (ECE) Program, I demonstrate how adopting best practices of development translates to better science that uses people and resources more efficiently. For instance, the practice of unit-testing code is also a scientific strategy for ensuring internal validity: when code implements research methods, then automated tests ensure that those methods are correct representations of the phenomena represented. This in turn avoids exhausting researchers' time in performing manual validity checks. Next, the practice of modularity entails clearly-defined interfaces: in multi-sectoral or cross-domain integrated assessment frameworks, this is achieved through clear definitions of the background concepts, measures, scales, and system boundaries. Making these items explicit helps researchers see quickly and precisely what translation is required to make (sub-)models interoperable with one another.

Finally, sustainability requires the very research processes that support the transition to be equitable and inclusive. I explain how the practices of making software free and open source, writing complete documentation, and continuous development lower barriers to understanding and participating in IAM-based research, especially for those not privileged to work at the few institutions that have the resources to maintain large-scale models. As well, a broad user base translates to a flow of contributions, improved model quality, and ultimately improved perceptions of legitimacy for modeling work.

Structuring data with SDMX

2021-02-01T00:00:00+01:00

This post expands on some text from the README of iam-units, in order to illustrate some improved ways to structure data and metadata. These are especially helpful in systems research, where data from multiple disciplines/domains/contexts are often combined.

iam-units is a thin wrapper around the very useful pint, that I wrote with some colleagues to handle unit conversions for data from integrated assessment models (IAMs) of energy and climate, including global warming potential (GWP) conversions between greenhouse gas (GHG) species:

In [1]: from iam_units import registry, convert_gwp

# Use a pint.UnitRegistry to convert from one unit to another
In [2]: qty = registry('3500 t').to('Mt')

# The result has the expected magnitude: 3500 t = 3.5 kt = 0.035 Mt
In [3]: qty
Out[3]: <Quantity(0.0035, 'megametric_ton')>

# Convert from mass of N₂O to GWP-equivalent mass of CO₂,
# using the metric from the IPCC Fifth Assessment Report (AR5)
In [4]: convert_gwp('AR5GWP100', qty, 'N2O', 'CO2')
Out[4]: <Quantity(0.9275, 'megametric_ton')>

Contents

Concept, observation, quantity, magnitude, unit
- Measurement and nominal properties
Common ways to handle GHGs and GWP-equivalents
Using SDMX to be explicit
Take-aways
- Further topics

Here's the text I'd like to expand on, with emphasis added:

convert_gwp() converts from from mass (or mass-related units) of one specific greenhouse gas (GHG) species to an equivalent quantity of second species, based on GWP metrics.

The function also accepts input with the commonly-used combination of mass (or related) units and the identity of a particular GHG species:

Strictly, the original species is not a unit but a “nominal property”; see the International Vocabulary of Metrology (VIM) [1] used in the SI. To avoid ambiguity, code handling GHG quantities should also track and output these nominal properties, including:

Original species.

Species in which GWP-equivalents are expressed (e.g. CO₂ or C)

GWP metric used to convert (1) to (2).

This is one of many cases where a little up-front effort to be precise—as opposed to loose and casual—about measurement can help us write code and produce data that is as interoperable as possible. The investment pays dividends by reducing repeated work down the road in handling imprecise data.

Concept, observation, quantity, magnitude, unit

Before returning to GHGs, here's a second example: in transport research we often want to discuss the following concept:

total distance traveled by a person (or group of people)

For instance, if I walk to the corner store, ride my bike to a restaurant, and then take the train to visit a friend, I might travel in total 0.5 + 4 + 10 = 14.5 kilometres. This is a quantity that expresses one observation of the above concept. The observation was, hypothetically, obtained by a process of measurement (more on that shortly). The quantity consists of the magnitude “14.5” and unit reference “kilometre”.

We might also say:

In [5]: registry("14.5 km").to("mile")
Out[5]: <Quantity(9.00988229, 'mile')>

This is the very same concept, observation, and quantity, but expressed in a different unit and thus having a different magnitude. [2]

Measurement and nominal properties

Something is still missing in order to be unambiguous about the observation “the travel distance is 14.5 kilometres.” We might ask:

Is this the actual distance traveled in a specific period of time?
- What period? A specific day? [3]
- Or, as in this case, a hypothetical, counterfactual, etc.?
Is it a computed statistic? For instance:
- The mean or average travel distance across 2+ periods, for just one person (me)?
- The sum/collective travel distance across 2+ people, but in the same period?
- Something else?

The VIM calls these nominal properties.

In systems research, it is common to combine data and knowledge from different streams of research that take place in different contexts, with different scope and resolution. Within any particular context, there can be certain natural choices for concepts, measurement process(es), and thus certain nominal properties of the data created/handled. These will be understood implicitly by both author and audience as the background consensus, and don't vary within that context. To list them explicitly doesn't achieve much, and might even be a distraction and barrier to clear communication; noise that buries the signal.

However: when combining data from different contexts, problems can arise when we fail to notice that the concepts, measurement processes, and nominal properties differ. A burden thus falls on the researcher to:

Make explicit the implicit features of measurement in the different domains supplying data that she wishes to combine,
Identify any differences,
Choose methods to adjust for (2), and
Correctly implement (3).

These tasks consume resources and create opportunities for errors that could undermine the internal validity of research. But they're also routine, so we can use some judicious automation to reduce the work involved while getting equally- or more-valid results.

Common ways to handle GHGs and GWP-equivalents

Suppose we have this data:

In [6]: import pandas as pd

In [7]: species = ["N2O", "CH4", "CO2"]

In [8]: data_a = pd.DataFrame(
   ...:     [
   ...:         ["Emissions, N2O", 1.1, "kt"],
   ...:         ["Emissions, CH4", 5.2, "kt"],
   ...:         ["Emissions, CO2", 100.3, "kt"],
   ...:     ],
   ...:     columns=["variable", "value", "unit"],
   ...: )
   ...: 

In [9]: data_b = pd.DataFrame(
   ...:     [
   ...:         ["Emissions, N2O", 291.5, "kt"],
   ...:         ["Emissions, CH4", 146.5, "kt"],
   ...:         ["Emissions, CO2", 100.3, "kt"],
   ...:     ],
   ...:     columns=["variable", "value", "unit"],
   ...: )
   ...:

Let's be very precise about what we have:

Each observation in data_a expresses a measured mass of emissions.
Each observation in data_b expresses a mass of CO₂ that, using the AR5 100-year metric, has the potential to contribute the same amount of global warming as the corresponding mass in data_a.
The ‘value’ column contains magnitudes; actual quantities are given by the ‘value’ and ‘unit’ columns together.
The ‘variable’ column mixes concepts: the thing measured is the [mass] emitted and is the same for all observations; the species emitted varies.

Clearly, it's wrong to do the following:

In [10]: data_a["value"] + data_b["value"]
Out[10]: 
0    292.6
1    151.7
2    200.6
Name: value, dtype: float64

These magnitudes, as bare numbers, can of course be added togther. But the results are scientifically meaningless, since the operands are conceptually incoherent: their units are the same, but they measure different things.

There are some common ways to store information that is intended to help avoid errors like this. Strategy A is to use a unit-like expression that combines the actual unit with a nominal property, i.e. the species:

In [11]: data_a.assign(unit=[f"kt {s}" for s in species])
Out[11]: 
         variable  value    unit
0  Emissions, N2O    1.1  kt N2O
1  Emissions, CH4    5.2  kt CH4
2  Emissions, CO2  100.3  kt CO2

In [12]: data_b.assign(unit="kt CO2-eq")
Out[12]: 
         variable  value       unit
0  Emissions, N2O  291.5  kt CO2-eq
1  Emissions, CH4  146.5  kt CO2-eq
2  Emissions, CO2  100.3  kt CO2-eq

These expressions are a common prose shorthand or abbreviation, but are not standard. For instance, ‘-e’/‘e’, ‘-eq’/‘eq’, ‘-equiv’, and other symbols are all in use in various contexts.

Strategy B is to mash even more concepts into a column named something like ‘variable’, adding (3) and (4) to (1) and (2) here:

The property that is measured, i.e. mass.
The species emitted.
The species in which a GWP-equivalent is expressed.
The GWP metric used.

In [13]: data_a
Out[13]: 
         variable  value unit
0  Emissions, N2O    1.1   kt
1  Emissions, CH4    5.2   kt
2  Emissions, CO2  100.3   kt

In [14]: data_b.assign(
   ....:     variable=data_b.variable + " (CO₂ equivalent, AR5GWP100)"
   ....: )
   ....: 
Out[14]: 
                                     variable  value unit
0  Emissions, N2O (CO₂ equivalent, AR5GWP100)  291.5   kt
1  Emissions, CH4 (CO₂ equivalent, AR5GWP100)  146.5   kt
2  Emissions, CO2 (CO₂ equivalent, AR5GWP100)  100.3   kt

Both of these strategies have the same basic flaw: they combine instead of distinguishing different aspects of measurement. Researchers might make choices that feel ‘natural’ in specific contexts, yet which differ from equally natural choices made by others. This creates a proliferation of idiosyncratic formats, and entails further work in parsing and harmonizing.

Using SDMX to be explicit

I maintain sdmx1, a Python package that implements the SDMX Information Model, or ISO 17369:2013. An “information model” (IM) is a model (a set of concepts and their relationships) for talking about information (data and metadata) and its representation. (The documentation for the package links to some learning resources for SDMX; the details aren't repeated here.)

Because it is carefully developed, the SDMX IM allows us to precisely capture the concepts and relationships in our example data, including our choices in measurement and of units.

The rest of this post gives a minimal demonstration.

Specify the concepts and data structure

We start by defining each of the distinct concepts that occur in our data:

In [15]: import sdmx

In [16]: import sdmx.model.v21 as model

In [17]: emission = model.Concept(
   ....:     id="EMISSION",
   ....:     name="Mass of greenhouse gas emitted",
   ....: )
   ....: 

In [18]: species_concept = model.Concept(
   ....:     id="SPECIES",
   ....:     name="Chemical species or substance",
   ....: )
   ....: 

In [19]: gwp_metric = model.Concept(
   ....:     id="GWP_METRIC",
   ....:     name="Set of GWPs used to convert species",
   ....: )
   ....: 

# “UNIT_MEASURE” is commonly used in SDMX applications
In [20]: unit_concept = model.Concept(
   ....:     id="UNIT_MEASURE",
   ....:     name="Unit of measurement",
   ....: )
   ....:

Next, we define the structure of our data. We start with the primary measure, the concept that is measured:

In [21]: dsd = model.DataStructureDefinition(id="GHG_DATA")

# - Refer to the concept
# - Use concept's ID for the primary measure as well
In [22]: pm = model.PrimaryMeasure(
   ....:     concept_identity=emission,
   ....:     id=emission.id,
   ....: )
   ....: 

# Store in the DSD
In [23]: dsd.measures.append(pm)

Next, we specify that values for the gwp_metric and unit concepts are stored as attributes. SDMX allows several options for where we attach these attributes. Here, we specify that the attributes are attached to entire data sets. This means that, in a particular data set, only one GWP metric can be used, and one unit: [4]

# 1. Define the data attribute
#    - Refer to the concept
#    - Use concept's ID for the attribute as well
#    - NoSpecifiedRelationship = attached to data set
# 2. Store in the DSD
In [24]: for concept in (gwp_metric, unit_concept):
   ....:     da = model.DataAttribute(
   ....:         concept_identity=concept,
   ....:         id=concept.id,
   ....:         related_to=model.NoSpecifiedRelationship,
   ....:     )
   ....:     dsd.attributes.append(da)
   ....:

Finally, we specify that our data has two dimensions. Every observation in a data set must have a unique Key with values for these dimensions.

Both dimensions refer to the same concept (species), but we give them different IDs and names to explain what these signify.

In [25]: for order, (id, name) in enumerate((
   ....:     ("SPECIES", "Original species emitted"),
   ....:     (
   ....:         "SPECIES_GWP",
   ....:         "Species in which GWP equivalent is expressed",
   ....:     ),
   ....: )):
   ....:     dim = model.Dimension(
   ....:         concept_identity=species_concept,
   ....:         id=id,
   ....:         order=order,
   ....:     )
   ....:     dsd.dimensions.append(dim)
   ....:

We now have a complete description of our data structure:

In [26]: dsd.measures
Out[26]: <MeasureDescriptor: <PrimaryMeasure EMISSION>>

In [27]: dsd.attributes
Out[27]: <AttributeDescriptor: DataAttribute(annotations=[], id='GWP_METRIC', uri=None, urn=None, concept_identity=<Concept GWP_METRIC: Set of GWPs used to convert species>, local_representation=None, related_to=<class 'sdmx.model.v21.NoSpecifiedRelationship'>, usage_status=None, concept_role=None); DataAttribute(annotations=[], id='UNIT_MEASURE', uri=None, urn=None, concept_identity=<Concept UNIT_MEASURE: Unit of measurement>, local_representation=None, related_to=<class 'sdmx.model.v21.NoSpecifiedRelationship'>, usage_status=None, concept_role=None)>

In [28]: dsd.dimensions
Out[28]: DimensionDescriptor(annotations=[], id='', uri=None, urn=None, components=[<Dimension SPECIES>, <Dimension SPECIES_GWP>])

Use the definitions to structure the data

Now we can create a data set that is structured by this definition:

In [29]: ds_a = model.DataSet(structured_by=dsd)

We store the values of attributes attached to the data set:

# Define a function to create attribute values and store them.
# The `value_for` property links each value to the definition
# of the attribute in the DSD, and thus to a concept.
In [30]: def store_attributes(ds, **values):
   ....:     for concept_id, value in values.items():
   ....:         av = model.AttributeValue(
   ....:             value=value,
   ....:             value_for=dsd.attributes.get(concept_id),
   ....:         )
   ....:         ds.attrib[concept_id] = av
   ....: 

In [31]: store_attributes(
   ....:     ds_a,
   ....:     GWP_METRIC="(None)",
   ....:     UNIT_MEASURE="kt",
   ....: )
   ....:

Finally we store the individual observations. In the case of data_a, the labels for the SPECIES and SPECIES_GWP dimensions are the same:

# 1. Discard redundant portion of the ‘variable’ column.
# 2. Create a key object from labels for each dimension.
# 3. Create the observation.
#    - The value is ‘for’ the primary measure, i.e. emissions.
# 4. Store in the data set.
In [32]: for _, row in data_a.iterrows():
   ....:     s = row["variable"].split("Emissions, ")[-1]
   ....:     dims = dict(SPECIES=s, SPECIES_GWP=s)
   ....:     key = dsd.make_key(model.Key, dims)
   ....:     obs = model.Observation(
   ....:         dimension=key, value=row["value"], value_for=pm
   ....:     )
   ....:     ds_a.obs.append(obs)
   ....:

We now have a complete data set. sdmx1 provides features for converting to other data structures and file formats:

In [33]: ds_a
Out[33]: DataSet(annotations=[], action=None, valid_from=None, described_by=None, structured_by=<DataStructureDefinition GHG_DATA>, obs=[Observation(attached_attribute={}, series_key=None, dimension=<Key: SPECIES=N2O, SPECIES_GWP=N2O>, value=1.1, group_keys=set(), value_for=<PrimaryMeasure EMISSION>), Observation(attached_attribute={}, series_key=None, dimension=<Key: SPECIES=CH4, SPECIES_GWP=CH4>, value=5.2, group_keys=set(), value_for=<PrimaryMeasure EMISSION>), Observation(attached_attribute={}, series_key=None, dimension=<Key: SPECIES=CO2, SPECIES_GWP=CO2>, value=100.3, group_keys=set(), value_for=<PrimaryMeasure EMISSION>)], series={}, group={}, attrib={'GWP_METRIC': <AttributeValue: GWP_METRIC=(None)>, 'UNIT_MEASURE': <AttributeValue: UNIT_MEASURE=kt>})

# pandas.DataFrame
In [34]: sdmx.to_pandas(ds_a, attributes="od")
Out[34]: 
SPECIES  SPECIES_GWP
N2O      N2O              1.1
CH4      CH4              5.2
CO2      CO2            100.3
Name: value, dtype: float64

# Standardized SDMX-ML format
In [35]: sdmx.to_xml(ds_a, pretty_print=True)
Out[35]: b'<?xml version=\'1.0\' encoding=\'utf-8\'?>\n<mes:DataSet xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:com="http://www.sdmx.org/resources/sdmxml/schemas/v2_1/common" xmlns:data="http://www.sdmx.org/resources/sdmxml/schemas/v2_1/data/structurespecific" xmlns:footer="http://www.sdmx.org/resources/sdmxml/schemas/v2_1/message/footer" xmlns:gen="http://www.sdmx.org/resources/sdmxml/schemas/v2_1/data/generic" xmlns:md_ss="http://www.sdmx.org/resources/sdmxml/schemas/v2_1/metadata/structurespecific" xmlns:md="http://www.sdmx.org/resources/sdmxml/schemas/v2_1/metadata/generic" xmlns:mes="http://www.sdmx.org/resources/sdmxml/schemas/v2_1/message" xmlns:reg="http://www.sdmx.org/resources/sdmxml/schemas/v2_1/registry" xmlns:str="http://www.sdmx.org/resources/sdmxml/schemas/v2_1/structure" structureRef="GHG_DATA">\n  <gen:Attributes>\n    <gen:Value id="GWP_METRIC" value="(None)"/>\n    <gen:Value id="UNIT_MEASURE" value="kt"/>\n  </gen:Attributes>\n  <gen:Obs>\n    <gen:ObsKey>\n      <gen:Value id="SPECIES" value="N2O"/>\n      <gen:Value id="SPECIES_GWP" value="N2O"/>\n    </gen:ObsKey>\n    <gen:ObsValue value="1.1"/>\n  </gen:Obs>\n  <gen:Obs>\n    <gen:ObsKey>\n      <gen:Value id="SPECIES" value="CH4"/>\n      <gen:Value id="SPECIES_GWP" value="CH4"/>\n    </gen:ObsKey>\n    <gen:ObsValue value="5.2"/>\n  </gen:Obs>\n  <gen:Obs>\n    <gen:ObsKey>\n      <gen:Value id="SPECIES" value="CO2"/>\n      <gen:Value id="SPECIES_GWP" value="CO2"/>\n    </gen:ObsKey>\n    <gen:ObsValue value="100.3"/>\n  </gen:Obs>\n</mes:DataSet>\n'

Convert carefully

Finally, we can convert ds_a using iam-units while maintaining an explicit and unambiguous data structure.

We create a second data set using the same data structure definition:

In [36]: ds_b = model.DataSet(structured_by=dsd)

# Store attributes:
# GWP metric name to use in conversion
In [37]: metric = "AR5GWP100"

# Unit used in both data sets
In [38]: unit = ds_a.attrib["UNIT_MEASURE"].value

In [39]: store_attributes(
   ....:     ds_b, GWP_METRIC=metric, UNIT_MEASURE=unit
   ....: )
   ....:

For each observation, we convert its magnitude, and change only the “SPECIES_GWP” key value:

# Target species for conversion
In [40]: target_species = "CO2"

# 1. Store the original species.
# 2. Create a new key with SPECIES_GWP set to `target_species`.
# 3. Convert the magnitude using the metric and iam-units.
# 4. Create a new observation and store in `ds_b`.
In [41]: for obs in ds_a.obs:
   ....:     species = obs.dimension["SPECIES"].value
   ....:     key = dsd.make_key(
   ....:         model.Key,
   ....:         dict(SPECIES=species, SPECIES_GWP=target_species),
   ....:     )
   ....:     value = convert_gwp(
   ....:         metric,
   ....:         registry.Quantity(obs.value, unit),
   ....:         species,
   ....:         target_species,
   ....:     ).magnitude
   ....:     ds_b.obs.append(
   ....:         model.Observation(
   ....:             dimension=key, value=value, value_for=pm
   ....:         )
   ....:     )
   ....:

The resulting data set has the same format as ds_a:

In [42]: ds_b
Out[42]: DataSet(annotations=[], action=None, valid_from=None, described_by=None, structured_by=<DataStructureDefinition GHG_DATA>, obs=[Observation(attached_attribute={}, series_key=None, dimension=<Key: SPECIES=N2O, SPECIES_GWP=CO2>, value=291.5, group_keys=set(), value_for=<PrimaryMeasure EMISSION>), Observation(attached_attribute={}, series_key=None, dimension=<Key: SPECIES=CH4, SPECIES_GWP=CO2>, value=145.6, group_keys=set(), value_for=<PrimaryMeasure EMISSION>), Observation(attached_attribute={}, series_key=None, dimension=<Key: SPECIES=CO2, SPECIES_GWP=CO2>, value=100.3, group_keys=set(), value_for=<PrimaryMeasure EMISSION>)], series={}, group={}, attrib={'GWP_METRIC': <AttributeValue: GWP_METRIC=AR5GWP100>, 'UNIT_MEASURE': <AttributeValue: UNIT_MEASURE=kt>})

In [43]: sdmx.to_pandas(ds_b, attributes="do")
Out[43]: 
SPECIES  SPECIES_GWP
N2O      CO2            291.5
CH4      CO2            145.6
CO2      CO2            100.3
Name: value, dtype: float64

Take-aways

To review, by applying the SDMX Information Model, we were able to:

Define exactly the concepts relevant to our data.
Use these to create a clear and unambigous structure, in which concepts were used for the primary measure, as attributes, or dimensions of multi-dimensional data.
Unpack a ‘variable’ column into its constituent concepts, and avoid overloading it further with additional concepts.
Store simple or bare SI units, parseable by pint, for the “UNIT_MEASURE” attribute, and avoid overloading this with unrelated concepts.
Access structured metadata and use it in the process of converting data.

Further topics

The amount of code used to handle only 3 observations might seem excessive. The up-front investment, however, unlocks further improvements in handling data and metadata. As a sketch of these:

Applications can additionally specify a representation for any concept used for a measure, attribute, or dimension.

For instance, we could specify that the “SPECIES” dimension represents the concept of species using only codes from a certain list of species understood to be GHGs: CH4, CO2, N2O, and so on. The code list is a mechanism for communicating about the data:
- “This data contains codes that are invalid, not in the specified list” can flag errors in data preparation.
- A data provider can specify a subset of the codes that will appear in their published data sets or data flows. Users then understand not to expect values outside this subset.
The concepts and other structures can be shared and reused. For instance, as described in footnote [4], we could construct a different data structure definition using the same concepts, as required for a different application.

The re-use of the same concepts tells users about links between multiple data sets and flows.
Published structures allow multiple data providers to prepare data that is guaranteed to be interoperable.

Footnotes

[1]	The VIM is good reading and food for thought on these topics; more giant shoulders that we stand on, even if it seems as pedestrian as a dictionary. I encourage everyone to skim it!

[2]

It's very common to conflate concepts and units. Do not do this.

For instance, “passenger/person distance traveled” (PDT) is often called “PKT” (meaning “passenger kilometres travelled”) or “PMT” (“person-miles traveled”). This conflates units (kilometres, miles) with the quantity (distance) measured. Two data sets with observations labelled “PKT” and “PMT” might measure the same concept—that is, PDT—in the same way with the same nominal properties, but merely express the resulting quantities in different units.

Always label dimensions or observations with the concept measured, not the units of particular measurements.

[3]	…or, during this pandemic, month or year? 😭️

[4]

(1, 2)

This is simply for brevity, not a limitation of SDMX.

We could equally, for instance, specify that gwp_metric is attached to series keys or individual observations. This would allow a single data set to contain the same measurements with magnitudes expressed in multiple ways via multiple GWP metrics.

Handling country codes

2021-01-28T00:00:00+01:00

In research with global scope and country- or country-group resolution, it's common to handle data with one or more [1] dimension(s) identifying a country (countries) for each observation. Problems can arise when inconsistent identifiers—“United States” vs. “United States of America”—are used to label this dimension, either across different data sets, or within one data set.

The best precaution against these problems is to convert idiosyncratic identifiers to short, standard ones, as soon as possible. ISO 3166 alpha-2 or alpha-3 codes (CA or CAN for Canada) are a natural choice for standard identifiers. [2]

In this post, I show a way to do this in a few lines of performant Python code, using some common packages and tools. The sections are titled with some general points of advice that also apply to other programming tasks.

1. Find and use well-tested tools
2. Understand the standard library
- dict.get()
- Decorate with functools.lru_cache()
3. Find and use optimized code
Wrapping up
- Concluding thoughts

1. Find and use well-tested tools

In this example, we'll want to use pycountry, a package that has existed since 2008 and, per its documentation:

…provides the ISO databases for the standards:

3166 Countries

The package includes a copy from Debian’s pkg-isocodes and makes the data accessible through a Python API.

It's easy to use and fast:

In [1]: from pycountry import countries

# Get a country by its code
In [2]: countries.get(alpha_2="CA")
Out[2]: Country(alpha_2='CA', alpha_3='CAN', flag='🇨🇦', name='Canada', numeric='124')

# Lookup on any field: alpha_2, alpha_3, or name:
In [3]: countries.lookup("Canada")
Out[3]: Country(alpha_2='CA', alpha_3='CAN', flag='🇨🇦', name='Canada', numeric='124')

# Fuzzy search returns a list() of results
In [4]: countries.search_fuzzy("Korea")
Out[4]: 
[Country(alpha_2='KP', alpha_3='PRK', common_name='North Korea', flag='🇰🇵', name="Korea, Democratic People's Republic of", numeric='408', official_name="Democratic People's Republic of Korea"),
 Country(alpha_2='KR', alpha_3='KOR', common_name='South Korea', flag='🇰🇷', name='Korea, Republic of', numeric='410')]

pycountry is downloaded about 56,000 times every day:

As with pandas, below, heavy usage is both an indicator of and contributor to quality. Hypothetically, we could copy the ISO 3166 table from Wikipedia into a CSV file and write some code to query it. But there's no point in doing this. The result will certainly be slower, more likely to contain bugs, and have fewer features than pycountry.

2. Understand the standard library

Some example data:

In [5]: import pandas as pd

In [6]: data = pd.DataFrame([
   ...:     ["Austria", 2021, 1.1],
   ...:     ["Bosnia", 2021, 2.2],
   ...:     ["Canada", 2021, 3.3],
   ...:     ["UK", 2021, 4.4],
   ...:     ["UK", 2022, 5.5],
   ...: ], columns=["country", "year", "value"])
   ...: 

In [7]: data
Out[7]: 
   country  year  value
0  Austria  2021    1.1
1   Bosnia  2021    2.2
2   Canada  2021    3.3
3       UK  2021    4.4
4       UK  2022    5.5

What is in the "country" column/dimension?

“Canada” and “Austria” are direct matches for the ‘name’ field of the ISO 3166-1 database.
“Bosnia” is only a partial match for the name “Bosnia and Herzegovina”.
“UK” is an idiosyncratic identifier: the ISO 3166-1 codes for the United Kingdom are GB and GBR.

We create a mapping with the idiosyncrasies of this data set:

In [8]: country_map = {
   ...:     "Bosnia": "Bosnia and Herzegovina",
   ...:     "UK": "United Kingdom",
   ...: }
   ...:

This allows us to look up a correct value for an incorrect one:

In [9]: country_map["UK"]
Out[9]: 'United Kingdom'

`dict.get()`

Do we need to include “Austria” and “Canada” in this dictionary? No. The standard dict.get() method allows a default argument:

In [10]: for name in data["country"]:
   ....:     print(country_map.get(name, name))
   ....: 
Austria
Bosnia and Herzegovina
Canada
United Kingdom
United Kingdom

When name is “Canada”, the lookup fails; “Canada” is not a key in the dictionary. The default argument is returned: “Canada”. This is a no-op or pass-through; it does nothing. Code that passes through some values while altering others will always perform better than code that does comparisons (if name == "UK": …).

Undersetanding that get() takes a default argument allows us to make country_map parsimonious and easy to read. It includes only important information (the incorrect labels appearing in this data set) and does not obscure them with unnecessary information.

Decorate with `functools.lru_cache()`

A real data set, unlike our example data, will contain many rows, sometimes with the same incorrect identifiers repeated many times. To speed up any operation we want to do with this data, we can use lru_cache(), [3] a function from the functools module of Python's standard library.

Go read the documentation! I'll wait.

We use this to decorate a function. It matches return values to input, and avoids running the (potentially slow) function when it sees a value for which a result has already been computed:

In [11]: from functools import lru_cache

In [12]: @lru_cache()
   ....: def fix_name(value):
   ....:     return country_map.get(value, value)
   ....: 

In [13]: for name in data["country"]:
   ....:     print(fix_name(name))
   ....: 
Austria
Bosnia and Herzegovina
Canada
United Kingdom
United Kingdom

We can inspect the cache that is created as fix_name() is called multiple times:

In [14]: fix_name.cache_info()
Out[14]: CacheInfo(hits=1, misses=4, maxsize=128, currsize=4)

currsize=4 tells us that 4 values have been cached over 5 calls. hits=1 tells us that the second occurrence of “UK” was handled by returning a cached value, instead of running the body of fix_name() again with the same input. [4]

3. Find and use optimized code

Our data is a pandas data structure. Pandas is a very widely used library with many users and contributors. [5] For these reasons, it is internally very sophisticated; many common operations—indeed, almost all operations that most of us will perform in daily use—have been optimized, some using low-level C code, for speed and memory performance.

The simple upshot is that it is almost never necessary to write Python loops (for …: and while …:) when using pandas. If you do find yourself writing loops, it is likely that you can instead find and use existing, optimized functionality in pandas.

I strongly recommend doing this: your code will be both simpler and more performant.

Above, we looped over the values in the "country" column of data. (Remember: each column of a pandas.DataFrame is a pandas.Series.) The feature we should use instead is pandas.Series.apply(). (Again: go read the documentation, all of it.)

This looks like:

In [15]: data["country"].apply(fix_name)
Out[15]: 
0                   Austria
1    Bosnia and Herzegovina
2                    Canada
3            United Kingdom
4            United Kingdom
Name: country, dtype: object

Pandas takes care of calling fix_name() many times, once for each value in this column, and assembling the result into a new series. It internally speeds up and, where possible, parallelizes these calls: the point is we don't need to think about how it does this.

Also, because we've memoized with lru_cache(), after a certain point each call becomes as quick as a dictionary lookup, no matter how expensive fix_name() is:

In [16]: fix_name.cache_info()
Out[16]: CacheInfo(hits=6, misses=4, maxsize=128, currsize=4)

More cache hits have occurred.

Wrapping up

Now we finally bring in pycountry:

In [17]: @lru_cache()
   ....: def code_for_name(value):
   ....:     return countries.get(name=country_map.get(value, value)).alpha_3
   ....:

This function first uses country_map to correct data set idiosyncrasies, then uses pycountry.get() to look up a record using the ‘name’ field. Finally, it returns the ‘alpha_3’ code from the record.

We apply() this new function to the ‘country’ column:

In [18]: data["country"].apply(code_for_name)
Out[18]: 
0    AUT
1    BIH
2    CAN
3    GBR
4    GBR
Name: country, dtype: object

In [19]: code_for_name.cache_info()
Out[19]: CacheInfo(hits=1, misses=4, maxsize=128, currsize=4)

And we can even update the data, discarding [6] the full names:

In [20]: data.assign(country=data["country"].apply(code_for_name))
Out[20]: 
  country  year  value
0     AUT  2021    1.1
1     BIH  2021    2.2
2     CAN  2021    3.3
3     GBR  2021    4.4
4     GBR  2022    5.5

Concluding thoughts

The three points of advice here:

Find and use well-tested tools.
Understand the standard library.
Find and use optimized code.

…fit two themes.

One is that time spent developing fluency with basic tasks pays dividends. For instance, we practice taking derivatives and performing integrals over and over, so that we can do them automatically and combine steps in the course of tackling more complex mathematical problems. Writing code for research is no different: we want to minimize the space and attention taken up by routine tasks, so that the real content—the methods and theory we are trying to implement—stands out prominently.

The second is that we follow paths blazed and walked by others. While our codes may investigate a new question in a novel way, the elemental building blocks of that code are shared with many others. Almost always, someone has put in work to create an elegant and performant way to do these atomic tasks. We ought to discover, understand, and use the tools they provide us.

Footnotes

[1]	Trade data, for instance, can have two country dimensions: origin and destination.

[2]

These are sometimes called “ISO codes.” Do not do this.

The ISO publishes (and pycountry supports) standard code lists for languages, currencies, and many other concepts. As soon as your software needs to handle data with both country and ≥1 of these other concepts—for instance, measures of economic activity denoted in local currency—the dimension label “ISO code” becomes ambiguous.

Label dimensions with the concept represented, not the kind of representation.

As well, do not invent new codes.

[3]	cache() is also available from Python 3.9.

[4]	The code examples in this post are all fairly fast to begin with, so the gain from using `lru_cache()` is not very large. However, this is a good pattern to learn and apply when the repeated function (here `country_code`) has some slow steps, or the data is big.

[5]	There have been over 25,000 commits modifying the `pandas` code!

[6]

Exercise: with what we've covered here, write a simple function that restores ‘country’ to the ‘name’ field of each record.

Again following the principle of parsimony, it is better to keep only the short, ISO 3166 alpha codes in ‘internal’ data throughout most of a program. Restore the ‘country’ dimension to the full name(s) only if and when necessary, e.g. to make output more intelligible to a user.

Paul Natsuo Kishimoto - article

Codes of conduct

Tutorial: Moderation, facilitation, and public speaking

“…for all!”

A thought experiment

1. Universal wellbeing

2. Practical realities, the ‘no’ answer, and Q2

3. Subjectivity and objectivity

4. Approximations and usefulness

5. Convenient data and lock-in

Please don't feed me slop

A parable

Why?

tl;dr

A few more points

Thinking together

Systemic discrimination and exclusion

Mentorship and training

What do you think?

Effective strategies for multi-sectoral research using large-scale models

Abstract

Structuring data with SDMX

Concept, observation, quantity, magnitude, unit

Measurement and nominal properties

Common ways to handle GHGs and GWP-equivalents

Using SDMX to be explicit

Specify the concepts and data structure

Use the definitions to structure the data

Convert carefully

Take-aways

Further topics

Handling country codes

1. Find and use well-tested tools

2. Understand the standard library

dict.get()

Decorate with functools.lru_cache()

3. Find and use optimized code

Wrapping up

Concluding thoughts

`dict.get()`

Decorate with `functools.lru_cache()`