Are you looking for a data science sensei?

Maybe you’re a junior data scientist, maybe you’re a software developer who wants to go into data science, or perhaps you’ve dabbled in data for years in Excel but are ready to take the next step.

If so, this post is all about you, and an opportunity I offer every year.

You see, life has been very good to me in terms of training as a data scientist. I have been spoiled, really – I had the chance to learn from some of the best data scientists, work with some exceptional epidemiologists, experience some unusual challenges and face many of the day-to-day hurdles of working in data analytics. I’ve had the fortune to see this profession in all its contexts, from small enterprises to multi-million dollar FTSE100 companies, from well-run agile start-ups to large and sometimes pretty slow dinosaurs, from government through the private sector to NGOs: I’ve seen it all. I’ve done some great things. And I’ve made some superbly dumb mistakes.

And so, at the start of every year, I have opened applications for young, start-of-career data scientists looking for their Mr. Miyagi. Don’t worry: no car waxing involved. I will be choosing a single promising young data scientist and pass on as much as I can of my so-called wisdom. At the end, your skills will shine like Mr. Miyagi’s 1947 Ford Deluxe Convertible. There’s no catch, no hidden trap, no fees or charges involved (except the one mentioned below).

Eligibility criteria

To be eligible, you must be:

  • 18 or above if you are taking a gap year or not attending a university/college.
  • You do not have to have a formal degree in data science or a relevant subject, but you must have completed it if you do. In other words: if you’re in your 3rd year of an English Lit degree, you’re welcome to apply, but if you’re in the middle of your CS degree, you have to wait until you’re finished – sorry. The same goes if you intend to go straight on to a data science-related postgrad within the year.
  • Have a solid basis in mathematics: decent statistics, combinatorics, linear algebra and some high school calculus are the very minimum.
  • You must be familiar with Python (3.5 and above), and either familiar with the scientific Python stack (SciPy, NumPy, Pandas, matplotlib) or willing to pick up a lot on the go.
  • Be willing to put in the work: we’ll be convening about once every week to ten days by Skype for an hour, and you’ll probably be doing 6-10 hours’ worth of reading and work for the rest of the week. Please be realistic if you can sustain this.
  • If, as recommended, you are working on an AWS EC2 instance, be aware this might cost money and make sure you can cover the costs. In practice, these are negligible.
  • You must understand that this is a physically and intellectually strenuous endeavor, and it is your responsibility to know whether you’re physically and mentally up for the job. However, no physical or mental disabilities are regarded as automatically excluding you of consideration.
  • You must not live in, reside in or be a citizen of any of the countries listed in CFR Title 22 Part 126, §126.1(d)(1) and (2).
  • You must not have been convicted of a felony anywhere. This includes ‘spent’ UK criminal convictions.

Sounds good? Apply here.

Preferred applicants

When assessing applications, the following groups are given preference:

  • Persons with mental or physical disabilities whose disability precludes them from finding conventional employment – please outline this situation on the application form.
  • Honourably discharged (or equivalent) veterans of NATO forces and the IDF – please include member 4 copy of DD-214, Wehrdienstzeitbescheinigung or equivalent document that lists type of discharge.

What we’ll be up to

Don’t worry. None of this car waxing crap.

Over the 42 weeks to follow, you will be undergoing a rigorous and structured semi-self-directed training process. This will take your background, interests and future ambitions into account, but at the core, you will:

  • master Python’s data processing stack,
  • learn how to visualize data in Python,
  • work with networks and graph databases, including Neo4j,
  • acquire the correct way of presenting results in data science to stakeholders,
  • delve into cutting-edge methods of machine learning, such as deep learning using keras,
  • work on problems in computer vision and get familiar with the Python bindings of OpenCV,
  • scrape data from social networks, and
  • learn convenient ways of representing, summarizing and distributing our results.

The programme is divided into three ‘terms’ of 14 weeks each, which each consist of 9 weeks of directed study, 4 weeks of self-directed project work and one week of R&R.

What you’ll be getting out of this

Since the introduction of Docker, tolerance for wanton destruction as part of coursework has increased, but still won’t earn you a passing grade by itself.

In the past years, mentees have noted the unusual breadth of knowledge they have acquired about data science, as well as the diversity of practical topics and the realistic question settings, with an emphasis on practical applications of data science such as presenting data products. I hope that this year, too, I’ll be able to convey the same important topics. Every year is a little different as I try to adjust the course to meet the individual participant’s needs.

The programme is not, of course, accredited by any accreditation body, but a certificate of completion will be issued to any participant who wishes so.

Application process

Simply fill in the form below and send it off by 14 January 2018. The top contenders will be contacted by e-mail or telephone for a brief conversation thereafter. Finally, a lucky winner will be picked by the 21st January 2018. Easy peasy!



Q: What does ‘semi-self-directed’ mean? Is there a fixed curriculum?

A: No. There are some basic topics (see list above) that I think are quite likely to come up, but ultimately, this is about making you the data scientist you want to be. For this reason, we’ll begin by planning out where you want to improve – kinda like a PT gives you a training plan before you start out at their gym. We will then adjust as needed. This is not an exam prep, it’s a learning experience, and for that reason, we can focus on delving deeper and getting the fundaments right over other cramming in a particular curriculum.

Q: Can I bring your own data?

A: Sure. In general, we’ll be using standard data sets, because they’re well-known and high-quality data. But if you have a dataset you collected or are otherwise entitled to use that would do equally well, there’s no reason why we couldn’t use it! Note that you must have the right to use and share the data set, meaning it’s unlikely you’re able to use data sets from your day job.

Q: Will this give me an employment advantage?

A: I don’t quite know – it’s impossible to predict. The field of data science degrees is something of a Wild West still, and while some reputable degrees have emerged, others are dubious. Employers still don’t know what to go by. However, you will most definitely be better prepared for an employment interview in data science!

Q: Why are you so keen on presenting data the right way?

A: Because as data scientists, we’re expected to not merely understand the data and draw the right conclusions, but also to convey them to stakeholders at various levels, from plant management to C-suite, in a way that gets the right message across at the first go.

Q: You’re a computational epidemiologist. Can I apply even if my work doesn’t really involve healthcare?

A: Sure. The principles are the same, and we’re largely focusing on generic topics. You might be exposed to bits and pieces of epidemiology, but I can guarantee it won’t hurt.

Q: Why do you only take on one mentee?

A: To begin with, my life is pretty busy – I have a demanding job, a family and – shock horror! – I even need to sleep every once in a while. More importantly, I want to devote my undivided attention to a worthy candidate.

Q: How come I’ve never heard of this before?

A: Until now, I’ve largely gotten mentees by word of mouth. I am concerned that this is keeping some talented people out and limiting the pool of people we should have in. That’s why this year, I have tried to make this process much more transparent.

Q: You’re rather fond of General ‘Mad Dog’ Mattis. Will there be yelling?


Q: There seems to be no upper age limit. Is that a mistake?


Q: I have more questions.

A: You can ask them here.

Boyd and Ajax walk into a cubicle farm: a few thoughts about Rebels at Work

I’m gauged to tolerate more or less one management book a year. That’s not because I don’t care (I do) or because I pretend to know everything about leadership (I don’t and I don’t) or because there aren’t enough of them around (there are). Rather, most of them have very little to add to conventional wisdom and an abundance were written from a narrow perspective, and so, precious few have managed to speak to me. In my Grecian snobbery, the only work on leadership and management worth its salt was written by an Athenian general around 5th century BC, and is called Ajax. About which, later.

However, a number of epidemiologists I follow and respect – in particular, @DrBalsamAhmad, @PWGTennant and @statsmethods – have tweeted (twoth?) with approval of Rebels at Work, a book by Lois Kelly @loiskelly and Carmen Medina @milouness published by O’Reilly:

It sparked some very interesting comments, especially about a matter close to my heart: managing ‘moral frustration’ at work:

So I quickly procured a Kindle copy of the book, and devoured it in a single sitting, with copious annotations. That’s always a good sign.

Ms Medina’s name, of course, was immediately familiar[1] – a career intelligence officer with three decades of service under her belt, she has served as the CIA’s DDI in the mid-noughties and finished her career with the Agency as the director of CSI, the Agency’s think tank. Closer to home, I knew her as the lady who took the enormous political risk to be among the first backers of Intellipedia, the US intelligence community’s shared wiki (and, in my humble opinion, one of the best things the US IC has come up with in a long, long time).[2] Lois Kelly, meanwhile, has been a corporate consultant throughout most of her career.[3] You couldn’t have picked two authors with more different backgrounds to write a book about prevailing with new ideas in rigid systems, yet their experiences coincide in the fulcrum of their book, Rebels at Work: both faced the tough challenge of bringing new ideas into bureaucratically petrified, change-resistant organisations. Their book is a culmination of their experiences, written for ‘Rebels at Work’: a field manual, so to speak, for waging maneuver warfare (or sometimes even guerrila warfare) against a larger, better equipped and solidly entrenched corporate infrastructure. The result is a book that has some great lessons despite ample space for criticism,[4] and one that I kept mulling over long after devouring it in a single sitting. Instead of a review (there are plenty of those around and I’m not a great book reviewer), I’d prefer to focus on three points that, in my view, are missing from Ms Medina and Ms Kelly’s book.

40 Second Boyd’s Rebel Alliance

Col. John Boyd, USAF (1927-1997): the biggest damn hero you’ve never heard of, and an object lesson in the cost of rebellion.

If there has ever been a rebel in a stolid, unbending institutional structure who paid a high price for being right the wrong way, it was Colonel John Boyd, affectionately known as the Mad Major, the Ghetto Colonel (he spent most of his money on books and the care of his son Stephen, who suffered from polio as a child) and 40 Second Boyd (for a standing bet that he could defeat any fighter pilot in simulated 1v1 air combat within forty seconds – a bet he never lost). There is much more to be told about Boyd than would fit into several blog posts, and fortunately, a better writer has taken it upon himself to write the seminal biography of the man who changed not just the art of air combat but of how we think about strategy.[5] Boyd was a synthetic genius, one of the few people endowed with the talent to draw on fields as disparate as thermodynamics, genetics, the then-still-nascent field of neuroscience (he commented on neuronal plasticity in an 1987 presentation, despite having no formal education in the life sciences!), psychology and anthropology – and find connections that pass most of us by.[6] His work on energy-maneuverability (E-M) theory informs fighter design to this day, and he made significant contributions to the development of the ‘left hook’ of Operation Desert Storm that left the Iraqi army demoralized, scattered and in vulnerable disarray.

And he was also what Scotsmen call crabbit. Boyd was devoted to flying, but not to the chain of command. His insubordinations are as legendary as his accomplishments. When his superiors refused to grant him the computer time he would require to prove by simulations his E-M theory, he and a civilian mathematician, Thomas Christie, ‘stole’ computer time on the Eglin AFB mainframe to build the models and prove that US fighter aircraft were inferior designs to Soviet aircraft. His reward for what would have saved thousands of pilots’ lives in the case of an actual air war between the superpowers was an investigation by the Inspector General.[7] Boyd was irreverent, once referring to the Thunderbirds (the USAF’s demonstration squad) as ‘trained monkeys’, and was fiercely politically incorrect before political correctness was a thing.

At the same time, he had a fierce loyalty towards the men who served with him. Alongside Christie, he had his own ‘rebel alliance’, jocularly dubbed the Fighter Mafia by Italian-American test pilot Col. Everest Riccioni. And he knew very well the cost of being part of the rebel alliance: this we know from a speech he often gave to young officers he thought about inviting into his alliance. It is, at this point, worth repeating.[8]

[O]ne day you will come to a fork in the road,” [Boyd] said. “And you’re going to have to make a decision about which direction you want to go.” He raised his hand and pointed. “If you go that way you can be somebody. You will have to make compromises and you will have to turn your back on your friends. But you will be a member of the club and you will get promoted and you will get good assignments.” Then Boyd raised his other hand and pointed another direction. “Or you can go that way and you can do something – something for your country and for your Air Force and for yourself. If you decide you want to do something, you may not get promoted and you may not get the good assignments and you certainly will not be a favorite of your superiors. But you won’t have to compromise yourself. You will be true to your friends and to yourself. And your work might make a difference.” He paused and stared into the officer’s eyes and heart. “To be somebody or to do something. In life there is often a roll call. That’s when you will have to make a decision. To be or to do. Which way will you go?

The fact is that while we’d all like to be the rebels that eventually prevail, there’s no such guarantee. There most definitely is no guarantee that being a rebel, however well one plays the game, will be easy. A Rebel at Work is, quintessentially, an insurgent. Even a good, successful insurgency is a pain to carry out well. And that is provided you’re one of the few insurgencies that win.

And so, perhaps the idea of this ‘rebel alliance'[9] lies uneasy with me because if things don’t turn out well – and however closely Ms Medina and Ms Kelly’s guidance is followed, success is never guaranteed! -, there’s more than one’s own welfare at stake. And like Boyd did, the honourable thing is to make sure that they know what the likely consequences of failure are.

Because not every rebellion wins. And if you’re drawing others into your rebellion, you’ll have to be able to live with what happens to them, too.

A few years ago, I had the singular pleasure to discuss Boyd with one of his last living collaborators and a few devotees of “Genghis John”, and one question came up repeatedly: how different would things have been had Boyd had a slightly more subtle sense of social interaction? How different would our world be if Boyd had somehow had Ms Medina and Ms Kelly’s book? As a scientist and an experimentalist, I am somewhat torn. On one hand, many of Boyd’s ideas could have been adopted earlier if he had cultivated a more positive personality. But at the same time, what if much of the substance of his ideas flowed directly from those negative features of his demeanor, the ones that made him a ‘bad rebel’: irascibility, a sizeable ego even for a fighter pilot, prone to outbursts of rage, the kind of obsessiveness that drove him to teach himself entire subjects from whatever books he could scrounge from the base library and, of course, his preternatural talent of alienating people. It is no accident that despite his illustrious track record and lasting developments, he never rose to general officer rank and in a final act of contempt, the DoD sent a single general officer to his funeral, despite his vast contribution to winning the first Gulf War mere six years earlier. Would a nicer Boyd have come up with E-M? Was his obsessiveness, a result of his socially alienating perspective and ensuing solitude, the fulcrum around which his genius leveraged? It is clear to me what Ms Medina and Ms Kelly would say – I’m just not sure as to the evidential basis. ‘Good’ rebels have an easier time (eventually), but I am not as willing to discount the ability of ‘bad rebel’ traits to produce worthwhile, yea crucially important, things as the authors are.

Ajax meets HR

The suicide of Ajax, depicted on a black-figure vase by Exekias, ca. 540 BC. If this sort of stuff goes down in your office, you might be having a leadership problem.

The greatest work on management and leadership was written and first performed at some point around 2,450 years ago. It was written by a general in his late 50s who, besides his military career, had a hold and an understanding of the human psyche few others since then have been able to even approach. It takes place towards the end of the Trojan War, immediately after the death of the Greek hero Achilles at the hands of the Trojan Paris. And over the years, I have often required my reports/subordinates to read it and often implored my superiors and COs, too, to (re)acquaint themselves with it.[10] But what relevance is a two-and-a-half-millennia old play about warriors to modern corporate culture and Rebels at Work?

Early on in the book, Ms Medina and Ms Kelly identify traits of ‘good’ and ‘bad’ rebels at work. In particular, they associate anger, pessimism, obsessiveness and alienating others as traits of ‘bad’ rebels at works. And they’re right. Those traits will not get you particularly far. Nobody listens to angry voices and pessimism. You don’t want to be the departmental obsessive. And you most definitely don’t want to alienate the uncommitted – you’ll need that Rebel Alliance at some point.

But these points have particularly hit home because I’ve seen this tetrad too often, in history and in real life: anger, pessimism, hostility and a near-obsessive adherence to things that make sense to few others. They’re the hallmark symptoms of what psychiatrist Jonathan P. Shay called moral injury.[11]

The archetypal moral injury and betrayal of themis mentioned by Shay: during the Vietnam War, infantry units were often separated and felt alienated from their commanders, who directed them from their airborne command posts, with little awareness of the risks and situation on the ground.

Moral injury is what happens when what Shay referred to as themis is violated. Themis is one of those beautifully untranslatable Greek cultural artifacts – with a meaning of “order”, “moral rightness” and “the way things ought to be”. Or, as he most beautifully put it, it is the “social morality of what’s right”, “the normal adult’s cloak of safety”.[12]

Shay is, of course, speaking in the context of trauma, specifically combat PTSD. It is his thesis that combat PTSD happens when a traumatic experience is accompanied with moral injury. But moral injury doesn’t need a traumatic event to accompany it. It happens every day, in boardrooms, in offices, in cubicle farms, much as it happened on the sands of Troy’s shore, amidst the Greek camp, during the events that inspired Sophocles’ Ajax.

The quintessential moral injury Ajax suffers is betrayal of what he believes is themis. Rightly or wrongly, he believes that as not merely the strongest warrior of the Greeks after Achilles but also the warrior whose acts had a character of self-endangering altruism – he was referred to as the ‘shield’ of the Greeks as he protected other warriors behind him -, he would be due the armour of the fallen Achilles. Nor is he entirely wrong – it is clearly implied that this would have been the ordinary way of doing things. But instead, Odysseus convinces the Greek leadership to award Achilles’s gear based on a competition that clearly favours him, including one in rhetoric – not exactly Ajax’s forte. The tragedy that ensues is nothing short of heartbreaking. The altruistic warrior who sheltered other soldiers with his own body now slaughters the Greeks’ sheep and shepherds – a quintessentially antisocial act, not merely taking lives but also depriving the Greek army of valuable supplies. In the end, Ajax – despite the entreaties of his war-bride Tecmessa – commits suicide: once again an act not merely against himself but also against the Greeks, a final act of vengeance, depriving them of one of their most decorated warriors.

What Ms Medina and Ms Kelly call ‘bad rebels’ might not be ‘bad rebels’ – they might suffer from the moral injury of a chain of command, violating institutional, individual and communal themis. The risk of Ms Medina and Ms Kelly’s identification of bad vs good rebels is twofold: on one hand, it blames the victim of moral injury for its natural effects – on the other, it relieves a deeply flawed chain of command of responsibility. The effects may not be as bloody as Ajax’s end, but they may well be as morally, individually and personally devastating.

To be quite clear: the authors do get it. Or, in the words of Ms Medina:

With their experience, they no doubt are aware that some frustration is endogenous and some frustration is exogenous. My sole apprehension is that there are precious few tools and tactics to differentiate these situations – and this is not the book’s fault, but a consequence of the underlying problem’s sheer complexity. To perfectionists suffering in a work environment pervaded by ‘moral injury’, it may be impossible to consider that the true problem is outside one’s cranium, and having witnessed the torment of the ensuing frustration, it is crucial for rebels to learn when they’re in a situation that defies the normal approach.

Responsible rebellion: put on your oxygen mask first

Perhaps the greatest strength, besides the vastly differing perspectives Ms Medina and Ms Kelly that form a truly unique synthesis of viewpoints, is an inherent understanding throughout that ‘good rebels’ are not self-directed: they’re organizationally directed. Much like Boyd’s promise to his acolytes-to-be, what’s on offer is not glory and immediate satisfaction but hard work and, if all goes well, organizational level success. I’ve touched on the small-scale aspect of this earlier, when I considered that however indispensable a Rebel Alliance is, it also means we’re betting others’ careers, livelihoods and well-being on how we do our job. I’m sure that Ms Medina and Ms Kelly would agree with me: being a rebel at work is an exacting task with very little margin for error. But there’s a different scale of responsibility involved in rebellion: responsibility for self.

There’s a common concept in modern (post-WW I) military strategy known as Auftragstaktik or mission command in the English sphere of military education.[13] Mission command is similar to what is known in software development as ‘declarative programming’: instead of providing a list of imperatives (orders, instructions), an end result is specified and the unit in question gets to figure out how to best accomplish it. This is often discussed in the context of decentralized command: instead of micromanaging units from a far-off regimental HQ, commanders can issue objectives and lower-level leadership, who are closer to the objective, can make the small-scale decisions with much better and much more accurate information straight from the vicinity of the objective. Instead of regimental HQ specifying from which side to assault a position, the platoon or company actually carrying out the mission can adapt to rapidly changing circumstances right there, on the ground.

The vulnerability of mission command is that if the leadership – or just a crucial element – of a unit gets incapacitated, all hell can break loose. This was witnessed quite often during the Vietnam War, where Viet Cong snipers targeted officers and radio operators to incapacitate command and control.[14] On Twitter, discussing Rebels at Work and the fact that sometimes, cynicism is a legitimate idiom of distress to the kind of moral injury discussed in the previous section, Barney Hammond (@bhammond) hit the nail on its head:

And perhaps as far as being a rebel goes,[15] that is a tough dilemma to resolve: when do we owe it to our Rebel Alliance to put the oxygen mask on ourselves first? Rebels at work, as the authors correctly identify, are organizationally-altruistically minded, sometimes even to the point of self-deprecation and putting themselves last. But it is exactly that attitude that needs to be tempered by what Barney so acutely pointed out: sometimes, we need to put the oxygen mask on first before helping others. To find this sensitive balance is not going to be easy – and I would not be surprised if most rebels at work would, once they have gathered their Rebel Alliance, struggle with finding the right balance between self-care and altruism.

In lieu of a conclusion

Reading Rebels at Work was a pleasant disappointment. It is a practical book, with actionable steps and things to think about – in that sense, it is a book that demands to be worked on. And the discerning reader can take a lot away – especially if years of struggling against corporate rigidity has left them wondering whether they’re even cut out for this role. Learning how to navigate some of the processes the authors describe has taken me long years and some restless nights and – I won’t lie – more than a few tears shed. In reality, Ms Medina and Ms Kelly’s book is not so much a handbook for rebels but a field manual for launching an insurgency – a sort of asymmetric warfare guide for waging 4th generation warfare (4GW) against slow-moving Prussian line infantry armed with muskets but vastly superior in numbers. And that perhaps is the most laudable feature of their book: it’s not about surviving as a NOC[16] rebel in a hostile organisation, but about openly accomplishing ambitious goals by building a network of support (the Rebel Alliance), exploiting critical actors, tending to your assets (see the part about the oxygen mask) and integrating one’s own desired objectives with pre-existing organizational commitments.

It was somewhat surprising to me to see so many epidemiologists discuss this book on Twitter – I mean, surely most of us do not work in a rigid, corporate framework that would necessitate us putting on our Rambo headbands and jungle camo face paint and go full-on tactical. Until, of course, I realized that as public health workers, we’re passionate by nature. Apathy doesn’t sit well with a job that is ultimately intended to save lives. And there aren’t many books that are so even-keeled about keeping a balance between operating within the system while pursuing what is right, even in circumstances where the institutional structures aren’t supportive of those goals. And so, to epidemiologists, public health workers and all those in the wider field working to save lives, this book might just be the best three hours you’ll spend reading during the holidays.

Boyd himself often pointed out that nothing – not even his own presentations – should be taken as gospel truth. To me, Rebels at Work leaves three questions open, and they are indeed quite unsettling.

  1. How do we differentiate between a ‘bad rebel’ (for whom the adequate response is primarily corrective) and a ‘good rebel’ suffering the kind of moral injury Shay discussed in the paper op cit.?
  2. As scientists, we’re bound to ask: what if the features of being a ‘bad rebel’ are necessary for some products of the mind? Consider the example of Boyd.
  3. Finally, how do we know when to prioritize ourselves and when to prioritize our Rebel Alliance?

The collaboration between the authors having been so successful, I would not be surprised if we were to see some answers to these questions in a sequel. I, for one, will definitely be looking forward to it.

An afternote

A mere hour or so after I posted this on my Facebook page, Lois Kelly posted this poignant message and kindly gave permission for me to repeat it here:

Thanks for such a thoughtful analysis and good questions. In my experience and research with Rebels at Work, “bad” rebel behaviors are sometimes necessary and useful. (My outrage and anger has propelled me in such positive ways.) A school superintendent of a big city school system here in the US told me that to cram as much change through the bureaucracy before his contract ended he had to go fast and embrace the “bad” behaviors. He knew he would alienate people and be disliked and he knew the children, teachers and principals would benefit. Playing a short game differs from the long game, which is important to understand. As for prioritizing between ourselves and the cause: we have to always be practicing resiliency (and I do mean practice) to manage our energy, sense making abilities, and relationships. The saddest stories I’ve heard are from people who ruined their marriages and friendships because of their obsession with their work/cause — and then didn’t achieve what they wanted at work anyway. Self-compassion is especially invaluable.

Lois makes two fantastic points here, both worth some thinking. One of these is, of course, that what’s good or bad might be context-dependent, in the example she mentions, conditional on time: or to say it all in warfighteresque, some targets call for a careful, slow approach while others require a degree of violence of action. More important, however, is her point on ‘practicing resiliency’. I know this because I’ve been there myself, so caught up with what my mission was at the moment that I lost track of many other things in life, and I’m quite sure that if my wife weren’t the steadfast angelic presence she is in my life, it could all have ended badly. I have seen way too many people who sacrificed their home base for fleeting objectives that some of them can’t even really remember anymore. I saw a shocking number of these cases when I was briefly working in Big Law. It reinforces another important rule of land warfare: know your stronghold, protect it, defend it and do not risk it for fleeting advantages.

To us in fields where there’s something larger at stake – be it the wellbeing of one’s unit, the fate of a company employing thousands, the health of millions relying on us doing our job well or indeed the very security of our nation -, it’s easy to find a justification for neglecting our stronghold: our friendships, marriage and our relationship with ourselves as expressed through self-compassion. This is a particular risk to altruists, and most epidemiologists do have a core of pure altruistic concern for the well-being of others and for humanity at large. To practice resiliency – or, as @bhammond2011 put it, putting on one’s own oxygen mask first – is particularly important, however counter-intuitive it is to the altruistic instinct to put others first and oneself last. To quote a Regimental Sergeant Major I once knew who was as grizzled as he was wise: “I don’t know what use you’ll ever be to anyone, but I sure do know you ain’t no use to anyone dead.

Kelly, L., Medina, C., & Cameron, D. (2014). Rebels at Work: A Handbook for Leading Change from Within. O’Reilly, $19.04 (Kindle). The authors also have a great website definitely worth checking out.

Reader questions: How did you find Rebels at Work? Do you feel it applies to your position in life and work? I’m particularly interested in epidemiologists, public health workers and researchers who found they got a lot out of the book. Don’t be shy, leave a comment!

References   [ + ]

1. You can take the boy out of the intelligence business, and so on.
2. Whether Intellipedia has lived up to its potential, and what that potential actually is, is a different story. But it takes willful disregard of the facts to ignore just how off the wall the very idea was: to begin with, Intellipedia had to exist on three different communication systems with a highest level of classification each of these could transmit: JWICS for TS, SIPRNet for Secret and Intelink-U for SBU/FOUO. I was in no sense au fait with the top of the US intelligence apparatus around 2005-2007 when Intellipedia was first proposed, but extrapolating from its current state, I would have been surprised if there had been more than one or two people who were willing to stick their neck out for such an idea – and as one of them, Ms Medina has all the right and credibility in the world to speak about being a rebel at a rigid bureaucracy playing a high-stakes game. I may not agree with Ms Medina on many things, but I can’t think of her with anything but the deepest respect.
3. I mean no disrespect by the fact that compared to Ms Medina’s career, I have less to say about Ms Kelly’s – merely that there is less information I could find.
4. I found some parts bordering on pseudoscience, especially the use of MindTime, which is neither sufficiently validated with peer reviewed research nor is its application in the book well executed: we know little about the sample other than the sample size and the fact that there was almost definitely some degree of selection bias. The problem with using pseudoscience at any point is that it casts doubt on the entire corpus at large.
5. Coram, R. (2002). Boyd: The fighter pilot who changed the art of war. Little, Brown.
6. DNI-POGO has all of Boyd’s presentations in original and modernized formats, and you should read them. The deck that best displays his incredible synthetic genius is Strategic Game of ? And ?, available here in its original form.
7. Kane, T. (2012). Bleeding Talent: How the US military mismanages great leaders and why it’s time for a revolution, Macmillan.
8. This version is taken from Coram’s book, op. cit.. Several of Boyd’s acolytes whom he invited on his quest for change confirmed the content of his invitation.
9. I refuse to go along with the ‘Dumbledore’s Army’ analogy many have raised on Twitter. Dumbledore’s Army is an object lesson on how to mount a stupid insurgency that will get you killed.
10. There is a great translation by Bryan Doerries, which you can buy on Amazon together with his translations of Philoctetes, the Trachinae and Aeschylus’ Prometheus Bound. Doerries, like me, believes in the abiding power of the Classics to speak to us today, too, and has held readings of many of these plays in all kinds of venues, from military bases through prisons to hospitals and hospices.
11. Shay, J. (2014). Moral injury. Psychoanalytic Psychology, 31(2), 182. Available online here.
12. Shay, J. (2010). Achilles in Vietnam: Combat trauma and the undoing of character. Simon and Schuster. An excerpt from the book is available here.
13. There are convoluted arguments as to whether the two terms do indeed cover the same ground, but for the present purposes, these are largely irrelevant.
14. In his seminal book on the battle of Ia Drang, then-Col. Hal Moore describes practicing exactly for this scenario by occasionally declaring platoon leaders ‘dead’ during training and have their sergeant take over command of the platoon. This would, as his memoir, We Were Soldiers Once And Young describes, often make all the difference between a decapitated unit being able to continue to operate or fall into disarray.
15. I share many of the traits Ms Medina and Ms Kelly would identify in a rebel, but I am not quite sure if I would neatly fit into that box without reservations. Nor, I’d wager, would most people.
16. Non-official cover.

Peace on Christmas

The ‘war on Christmas’ is a venerable tradition in America. Many blame the incipient atheism and secularism of American society starting with the 20th century, but in fact, 17th century Puritans – whom you can accuse of many things but definitely not of religious pluralism and secularist tendencies! – were all too keen to ban celebrations of Christmas in the New World.[1] And to this day, the ‘war on Christmas’ remains one of those political signal flags, waved with more pride than wisdom, more enthusiasm than meaning.

But I don’t want to talk about the war on Christmas. I want to talk about the peace on Christmas.

Christmas miracles

Like most people who, by addiction or duty, are near constantly connected to the internet, I couldn’t possibly miss astrophysicist popular science narrator Neil deGrasse Tyson’s obligatory tweet to enlighten the masses about the sheer folly and insignificance of Christmas.

Now, if Mr Tyson does not want to find a religious miracle in what transpired two millennia ago somewhere near Bethlehem, that’s his right, and a right I volunteered to bleed and die for. But maybe he’ll have time for a secular miracle.

December, 1914

By Christmas 1914, the Great War has been raging on for less than half a year, but quite definitely longer than what was promised – a quick pacification of the Balkans and resolution of the Austro-Hungarian crisis before the leaves fell. After the initial frantic changes of control that form the first spasms of every armed conflict, the lines of combat solidified, and warfighting went from killing time to, well, just killing time. Nowhere was this more true than the blood-sodden fields of Ypres, where the First Battle of Flanders between late October and late November ended in the kind of frustrating, indecisive result that we now know is psychologically more distressing than combat itself.[2] The troops on the Western Front were tired, bored and immensely fed up with a war during which nothing happened.

Until something happened that no-one would have thought. Something we might with no exaggeration call a miracle.

After five months of war and the attendant emotions – rage, grief, loss, nationalistic fervour and divine self-justification -, the diary for the 16th Queen’s Westminster Infantry Regiment for 25 December 1914 noted only curtly: “no war today”.[3] A Rifleman Graham Williams of the 5th London Rifle Brigade, cited by Neil Hollander,[4] described the situation thus:

Then suddenly lights began to appear along the German parapet, which were evidently make-shift Christmas trees, adorned with lighted candles, which burnt steadily in the frosty air!
First the Germans would sing one of their carols and then we would sing one of ours, until when we started up O Come, All Ye Faithful, the Germans immediately joined in singing the same hymn to the Latin words Adeste Fideles. And I thought, well, this is a most extraordinary thing — two nations singing the same carol in the middle of a war.
I think I have seen one of the most extraordinary sights today that anyone has ever seen. […]

In his letter to his mother, the naturalist and author Henry Williamson, then also with the London Rifle Brigade, wrote an extensive narrative of the Christmas Truce, too long to repeat here but worth excerpting a few parts:

On Xmas eve both armies sang carols and cheered & there was very little firing. The Germans (in some places 80 yds away) called to our men to come and fetch a cigar & our men told them to come to us. This went on for some time, neither fully trusting the other, until, after much promising to ‘play the game’ a bold Tommy crept out & stood between the trenches, & immediately a Saxon came to meet him. They shook hands & laughed & then 16 Germans came out.

Thus the ice was broken. Our men are speaking to them now.

They are landsturmers or landwehr,[5] I think, & Saxons & Bavarians (no Prussians).[6] Many are gentle looking men in goatee beards & spectacles, and some are very big and arrogant looking. I have some cigarettes which I shall keep, & a cigar I have smoked.

We had a burial service in the afternoon, over the dead Germans who perished in the ‘last attack that was repulsed’ against us. The Germans put ‘For Fatherland & Freedom’ on the cross.

Other accounts recount spontaneous games of football (remarkably, between the 2nd Battalion Royal Welsh Fusiliers and the Saxon Infantry Corps)[7], exchanges of gifts, joint services and a fervent yet futile attempt by senior leadership on both sides to prevent the truce. But miracles don’t obey orders.

Of course, eventually, war resumed, and after the increasingly inhumane and embittered warfare of 1915, involving in particular widespread use of lethal war gases like chlorine – in an act of sad irony, deployed near Ypres, where one of the first Christmas truces took place – and wide scale deployment of non-lethal lachrymants like xylyl bromide (T-Stoff), whatever residual sympathies could have led to a similar truce have been extinguished. For the rest of the war, Christmas Eve was celebrated by artillery barrages from both sides, so as to preclude any foolhardy attempts by the men in the trenches to find that unity between humankind that war cruelly severed, severs and will sever as long as we have them.

But once, just one brief Christmas Day, “at some disputed barricade”, there was a brief moment in which men who grew up, or at the very least were inculcated, with the superiority of their own nation and the justice of their cause, could set all that aside and realize that what they shared was much more than what divided them.

And that, to me, is as close to a Christmas miracle as it gets.

For reasons complex and convoluted, we don’t know to how many of the men reaching hands across the barbed wire and the barricades were devout Christians, or what the nativity of Christ meant to them, whether they ever celebrated Christmas, or whether they lit the last candle of the Menorah mere three weeks earlier. We do know that those who were Christians came from a range of different branches, some with radically different interpretations of Christmas. We don’t know to how many of them worshipped the nativity of Christ and how many were largely inspired by the secular aspects of Victorian Christmas: carols, Christmas trees and presents.

But what we do know is that on that 25th December 1914, something happened that no-one would have predicted, that someone at one point risked their lives to reach out their hand to their sworn enemy for a single day’s relief from the stalemate, that for one day amidst a senseless bloodshed, Love, Mercy and a notion of a shared humanity prevailed over principalities, powers, rulers of darkness of that world and spiritual and moral wickedness in high places that sought to separate brother from brother.

And if that’s not a miracle, I don’t know what is. You don’t have to believe in any supernatural power to accept it. It’s enough to consider all it takes to overcome the hatred and the chauvinism and the supremacist ideologies and the blind, unquestioning loyalty and the all-ever-blinding propaganda to conclude that whatever happened on that day 103 years ago, it was something very special.

And that’s why it will forever be taboo to speak of the unifying power of this day, between believers and unbelievers, between those who worship Christ and those who worship any other deity or none, between those who were made brothers and sisters equally endowed with a shared humanity but separated by arbitrary divisions.

And that’s why, as long as we wish to heal this broken world, we must think and speak more of the peace on Christmas than whatever war on Christmas, real or imagined.

Personal note: Joyeux Noël, despite the odd historical inaccuracies and somewhat contrived plot, is a beautiful dramatization of this incredible event, and definitely worth watching over Christmastide. Merry Christmas!

References   [ + ]

1. L.C. Scott writes in Christmas – Philosophy for everyone: better than a lump of coal (Wiley, 2002): “Ironically, the earliest Christian settlers on both the [American] mainland and the islands of Hawaii forbade the celebration of Christmas as extra-biblical. […] On the mainland, seventeenth-century Puritan New England had laws forbidding the observance of Christmas. […] Those who still celebrated Christmas, such as Lutherans, Catholics, Dutch Reformed and Anglicans, did so in a ow-key manner, focusing on church or home. Well into the 1800s the celebration of Christmas was a local matter. The first state to make Christmas a legal holiday was Alabama in 1836.”
2. For an argument expounding on this, see the works of Jonathan Shay, who among the moral decay of the war also emphasised the deleterious consequence of ‘killing time, punctuated by killing time’, and the relation of the abrupt changes from one to another to the development of hyperarousal as a pathognomonic symptom of combat trauma.
3. Cited in Blom Crocker, T. (2015). The Christmas Truce: Myth, Memory and the First World War. University of Kentucky Press.
4. Hollander, N. (2013). Elusive Dove: The search for peace during World War I. McFarland.
5. Roughly equivalent to a militia in this context, Landsturm and Landwehr were last-ditch forces conscripted of everyone of military age, hastily trained, badly armed and, effectively, cannon fodder.
6. The importance of this may be that Prussians practiced a much harsher military discipline than central and southern forces.
7. A good summary of the event is in DeGroot, G. (2014). The truth about the Christmas Day football match. The Telegraph, 24 Dec 2014.

A walk in the light haze of Pannonhalma.

A walk in the light haze of Pannonhalma. The Archabbey is beautifully maintained and wonderfully well-kept, as are the grounds. As one of the iconic Benedictine abbeys of Hungary and part of the UNESCO world heritage, it is definitely worth a visit.

Taken on Dec 26, 2017 @ 14:14 near Pannonhalma Archabbey, this photo was originally posted on my Instagram. You can see the original on Instagram by clicking here..

Quantifying herd immunity lower bounds

In my previous article on the seasonal flu vaccine’s effectiveness, I wrote:

For the flu, with an R0 of about 1.5, we would need at least a third of the population vaccinated for herd immunity to be effective, assuming a 100% effective vaccine – knowing that flu vaccines’ VE is less than that, we’re looking at closer to 60% for adequate herd immunity. That means you, too. It is vitally important that everybody does their part, even if they themselves don’t expect, or care about, getting the flu.

Since then, I have been approached by a few people, both here and on Facebook, about the maths underlying it. So since I’m officially spending a mandatorily (read: spousally) enforced weekend off work, I thought I’m going to lay out the reasoning behind the maths.

What is herd immunity?

The idea of herd immunity is that an infectious disease needs a given number of available hosts in order to be ‘sustainable’ (able to continue to infect people) within that population. Typically, for illnesses from which people tend to either die or recover as non-infectious cases, this has to do with something called R_0 (pron. arr-nought) or ‘reproduction number’ of the infectious disease in a population.[1]

R_0 describes, roughly, the number of cases produced by each case. Consider poliomyelitis, which has an R_0 of about 6 (unusually high, given its transmission route).[2] That means that every case produces, on average, six new cases. It is obvious from this that unless the R_0 for an infectious disease is above 1, the infection will not be sustainable in the long run – it will burn through the infected and eventually die out. R_0 is determined empirically, and is specific to a naive population, i.e. one where there is no pre-existing immunity to the disease nor is there any significant infection. It is often enough derived from the average contact rate of the population (the number of times the transmission-relevant contact occurs between people, e.g. the number of sexual contacts per unit time for sexually transmitted infections or the number of sufficient vicinity contacts for droplet/airborne transmitted infections) and the inverse of the infectious period, i.e. the multiple of unit time for which a case remains infectious.

The idea of herd immunity relates to R_0 in a particular way. Consider, once again, polio with its R_0 of 6. Now assume that half of the population is vaccinated, and assume for the time being that the vaccine is 100% effective. In practice, that means that 6 successful transmissions will at best yield 3 new cases (the unvaccinated half), whereas there will be 3 guaranteed resisters (the vaccinated half). In effect, vaccinating n% of the population cuts n% off the theoretical R_0 in a naive population – or, in other words, for a population with \frac{1}{n} vaccinated, the adjusted effective R_0 is

R_{0_{post-vaccination}} = R_{0} (1 - \frac{1}{n})

Recall that we have earlier related R_0, and specific values of it, to the survival of an infectious disease – namely that if R_0 < 1, the disease will eventually die out. The point of herd immunity is to artificially whittle down R_0 to a sub-1 value. If vaccinating \frac{1}{n } of the population reduces effective R_0 to R_0 (1 - \frac{1}{n}), then to reduce R_0 to 1 requires us to vaccinate 1 - \frac{1}{R_0}. Thus for polio, with R_0 = 6, we need to vaccinate

1 - \frac{1}{R_0} = 1 - \frac{1}{6} = \frac{5}{6}

of the population to reach a point where, assuming the vaccine is 100% effective (which it never is – not many things in reality are 100% effective), the disease cannot subsist and spread in the population for long. At that level of vaccination, even unvaccinated people are significantly protected, almost as well as if they were to be vaccinated. In theory, anyway.

Herd immunity in practice

In practice, there are two problems with this. One is that herd immunity doesn’t help you if you, for whatever reason, do things that lead to catching the disease. In other words, it is not a ‘real’ immunity the way getting vaccinated is. It ensures that the likelihood of catching the disease is significantly reduced, and that outbreaks become self-contained, but it doesn’t give you as an unvaccinated individual any immunity per se. The other problem is that herd immunity calculations are premised on 100% vaccine efficacy (which is not the same as efficiency, see the previous post for difference!). The point is that the result of the above calculation is a theoretical minimum, premised on 100% effective vaccines, for herd immunity – reaching it, or even exceeding it, does not yet guarantee herd immunity. And with information about vaccine efficacy not being easy to come by (unlike information about vaccine efficiency, which is available in abundance), it’s hard to determine a correct rate. For these reasons, anyone who could get vaccinated, should get vaccinated.[3] Especially for viral diseases, herd immunity is the best protection for those who genuinely cannot get vaccinated. It’s a goal worth striving for as a population – and it costs nothing to confer herd immunity above and beyond getting immunised, which already confers the benefits of individual immunity.

References   [ + ]

1. The situation is different for illnesses where a recovered case may remain infectious, indefinitely or for a given time, e.g. for Ebola virus disease (EVD), where recovered patients continue to have actively infectious virus in their seminal fluid and vitreous humour for several years. For a case study, consider William A Fischer II et al. Ebola Virus RNA Detection in Semen More than Two Years After Resolution of Acute Ebola Virus Infection. Open Forum Infectious Diseases, 2017. DOI: 10.1093/ofid/ofx155/4004818
2. In general, airborne infectious diseases tend to have a higher R_0 than other methods of transmission, such as those that require sexual contact, blood or, as in the case of polio, fecal-oral transmission to spread.
3. A recent meme is claiming or pretending to have the MTHFR mutation and arguing that this should lead to a medical exemption from vaccinations. Most doctors haven’t heard much of MTHFR, and it sounds scary, and when you google it, most of the documentation is on the extremely rare complete MTHFR deficiency, a very rare and very serious illness that has about 70 documented cases in all of medical history. Meanwhile, some degree of MTHFR mutation is present in a good deal – somewhere between 10 to 35% – of the normal population, and is indeed so frequent without any associated clinical syndrome that it’s seen as a harmless variation in genetics. MTHFR (methylenetetrahydrofolate reductase) is an enzyme that catalyses the reduction of 5,10-methylenetetrahydrofolate to 5-methyltetrahydrofolate, which is involved in the methylation of homocysteine, yielding methionine. There is some evidence, from an NIH study with ridiculously small sample sizes, that certain MTHFR SNPs, particularly rs1801133, are associated with adverse events in smallpox vaccination. There are two problems with this. One, I don’t know of this ever having been replicated with any sample size worthy of being drawn conclusions from. Two, given the frequency of MTHFR deficiency in the population, you would expect vast numbers of ‘vaccine injured’ people, much more than the cases in VAERS and definitely more than those that have a credible claim. It makes no epidemiological sense at all. MTHFR polymorphisms are, as the science stands at the moment, not a good reason not to vaccinate.

Is the flu vaccine really only 10% effective? A sojourn into immunization epidemiology

If you work in IT, you must be familiar with the instances of well-meaning family asking you to fix their computers – even if you develop enterprise Java apps and they have a broken video card, they expect you to be able to do something about it. For epidemiologists, the equivalent is the flu shot. Over the last few weeks, I have been asked by so many of my friends to explain why they should even consider getting the flu shot if it’s, reportedly, only 10% effective. Add to that, of course, the sheer amount of crazy on the internet on the subject (the flu shot will give you cancer/autism/cancertism, here, have these herbs, open your chakras, meditate on these crystals and drink some colloidal silver until you look like Stan Jones).

“I mean, how hard could it be? We have the flu every year,” my friend, a very intelligent and accomplished lady, pointed out to me the other day. “And surely something like the flu is pretty simple, right? You’d think that by now we would have figured out what works and what doesn’t.”

In fact, it’s pretty complicated – and the simplicity of the flu virus makes matters worse, not better.

Read more

On the challenge of building HTTP REST APIs that don’t suck

Here’s a harsh truth: most RESTful HTTP APIs (in the following, APIs) suck, to some degree or another. Including the ones I’ve written.

Now, to an extent, this is not my fault, your fault or indeed anyone’s fault. APIs occupy a strange no man’s land between stuff designed for machines and stuff designed for humans. On one hand, APIs are intended to allow applications and services to communicate with each other. If humans want to interact with some service, they will do so via some wrapper around an API, be it an iOS app, a web application or a desktop client. Indeed, the tools you need to interact with APIs – a HTTP client – are orders of magnitude less well known and less ubiquitous than web browsers. Everybody has a web browser and knows how to use one. Few people have a dedicated desktop HTTP browser like Paw or know how to use something like curl. Quick, how do you do a token auth header in curl?

At the same time, even if the end user of the API is the under-the-hood part of a client rather than a human end user, humans have to deal with the API at some point, when they’re building whatever connects to the API. Tools like Swagger/OpenAPI were intended to somewhat simplify this process, and the idea was good – let’s have APIs generate a schema that they also serve up from which a generic client can then build a specific client. Except that’s not how it ended up working in practice, and in the overwhelming majority of cases, the way an API handler is written involves Dexedrine, coffee and long hours spent poring over the API documentation.

Which is why your API can’t suck completely. There’s no reason why your API can’t be a jumbled mess of methods from the perspective of your end user, who will interact without your API without needing to know what an API even is. That’s the beauty of it all. But if you want people to use your service – which you should very much want! -, you’ll have to have an API that people can get some use out of.

Now, the web is awash with stuff about best practices in developing REST APIs. And, quite frankly, most of these are chock-full of good advice. Yes, use plural nouns. Use HATEOAS. Use the right methods. Don’t create GET methods that can change state. And so on.

But the most important thing to know about rules, as a former CO of mine used to say, is to know when to break them, and what the consequences will be when you do. There’s a philosophy of RESTful API design called pragmatic REST that acknowledges this to an extent, and uses the ideas underlying REST as a guideline, rather than strict, immutable rules. So, the first step of building APIs that don’t suck is knowing the consequences of everything you do. The problem with adhering to doctrine or rules or best practices is that none of that tells you what the consequences of your actions are, whether you follow them or not. That’s especially important when considering the consequences of not following the rules: not pluralizing your nouns and using GET to alter state have vastly different consequences. The former will piss off your colleagues (rightly so), the latter will possibly endanger the safety of your API and lead to what is sometimes referred to in the industry as Some Time Spent Updating Your LinkedIn & Resume.

Secondly, and you can take this from me – no rules are self-explanatory. Even with all the guidance in the world in your hand, there’s a decent chance I’ll have no idea why most of your code is the way it is. The bottom line being: document everything. I’d much rather have an API breaking fifteen rules and giving doctrinaire rule-followers an apoplectic fit but which is well-documented over a super-tidy bit of best practices incarnate (wouldn’t that be incodeate, given that code is not strictly made of meat?) that’s missing any useful documentation, any day of the week. There are several ways to document APIs, and no strictly right one – in fact, I would use several different methods within the same project for different endpoints. So for instance a totally run-of-the-mill DELETE endpoint that takes an object UUID as an argument requires much less documentation than a complex filtering interface that takes fifty different arguments, some of which may be mandatory. A few general principles have served me well in the past when it comes to documenting APIs:

  • Keep as much of the documentation as you can out of the code and in the parts that make it into the documentation. For instance, in Python, this is the docstring.
  • If your documentation allows, put examples into the docstring. An example can easily be drawn from the tests, by the way, which makes it a twofer.
  • Don’t document for documentation’s sake. Document to help people understand. Avoid tedious, wordy explanation for a method that’s blindingly obvious to everyone.
  • Eschew the concept of ‘required’ fields, values, query parameters, and so on. Nothing is ‘required’ – the world will not end if a query parameter is not provided, and you will be able to make the request at the very least. Rather, make it clear what the consequences of not providing the information will be. What happens if you do not enter a ‘required’ parameter? Merely calling it ‘required’ does not really tell me if it will crash, yield a cryptic error message or simply fail silent (which is something you also should try to avoid).
  • Where something must have a particular type of value (e.g. an integer), where a value will have to be provided in a particular way (e.g. a Boolean encoded as o/1 or True/False) or has a limited set of possible values (e.g. in an application tracking high school students, the year query parameter may only take the values ['freshman', 'sophomore', 'junior', 'senior']), make sure this is clearly documented, and make it clear whether the values are case sensitive or not.
  • Only put things into inline comments that would only be required for someone who is reading your code. Anything a user of your methods/endpoints ought to know about them should be in the docstring or otherwise end up in your documentation – your docstring, of course, has the added benefit that it will be visible not only for people reading the documentation but also for whoever is reading your code.
  • If you envisage even the most remote possibility that your API will have to handle Unicode, emojis or other fancy things (basically, anything beyond ASCII), make sure you explain how your API handles such values.

Finally, eat your own dog food. Writing a wrapper for your API is not only a commercially sound idea (it is much more fun for other developers to just grab an API wrapper for their language of choice than having to homebrew one), it’s also a great way to gauge how painful it is to work with your API. Unless it’s anything above a 6 on the 1-10 Visual Equivalent Scale of Painful and Grumpy Faces, you’ll be fine. And if you need to make changes, make any breaking change part of a new version. An API version string doesn’t necessarily mean the API cannot change at all, but it does mean you may not make breaking changes – this means any method, any endpoint and any argument that worked on day 0 of releasing v1 will have to work on v1, forever.

Following these rules won’t ensure your API won’t suck. But they’ll make sucking much more difficult, which is half the victory. A great marksmanship instructor I used to know said that the essence of ‘technique’, be it in handling a weapon or writing an API, is to reduce the opportunity of making avoidable mistakes. Correct running technique will force you to run in a way that doesn’t even let you injure your ankle unless you deviate from the form. Correct shooting technique eliminates the risk of elevation divergences due to discrepancies in how much air remains in the lungs by simply making you squeeze the trigger at the very end of your expiration. Good API development technique keeps you from creating APIs that suck by restricting you to practices that won’t allow you to commit some of the more egregious sins of writing APIs. And the more you can see beyond the rules and synthesise them into a body of technique that keeps you from making mistakes, the better your code will be, without cramping your creativity.

I could tell you…

Courtesy of a buddy in satellite reconnaissance, he sent me a few of these t-shirts of a project so secret, they did not even allow an official mission patch to be designed. The (somewhat clumsy) Latin on the patch translates to “I could tell you… but then I would have to kill you.”

Taken on Dec 08, 2017 @ 13:40 near Budapest II. kerület, this photo was originally posted on my Instagram. You can see the original on Instagram by clicking here..

Epidemiologists, here’s your chance to make your parents proud.

I found this t-shirt as a stocking stuffer for my dad, who still doesn’t really know what I do for a living, other than that it has ‘to do with viruses’ (yeah… almost, Dad.). Epidemiology geeks, there’s hope: here’s your chance to make your parents proud this Christmas!

Taken on Dec 06, 2017 @ 23:26 near Budapest II. kerület, this photo was originally posted on my Instagram. You can see the original on Instagram by clicking here..