epiforecasts manual

We are a group of researchers at LSHTM with a focus on real-time infectious disease modelling. We develop, use and critically evaluate computational, statistical and mathematical techniques to improve our understanding of infectious disease outbreaks in real time, often in collaboration with public-health decision makers.

This document is a point of reference for current and future team members, not a fixed set of rules. Suggestions for changes via Pull Requests are welcome from any group member at any time.

Group principles

We value openness and collaborative development. We share work early rather than waiting until it feels ready. Incomplete drafts, failed approaches and dead ends are all worth sharing so that others can help. Our work lives in public GitHub repositories, and we often collaborate through issues and pull requests.

We aim to develop general and reusable tools, particularly software packages in widely used, freely and openly available languages, rather than single-use computer code. We value software and tools as research outputs alongside papers, and when writing code for a project, consider whether it could become a reusable package rather than a one-off script.

Expectations from members

Everyone:

Support the work of other group members and offer help where you can.
Contribute to group meetings and other group events.
Share your work openly and early, in meetings, on GitHub, on Slack.
When someone asks for feedback or help, respond within a few days, even if just to say you can’t help right now.
When giving feedback, be constructive and focus on the work.

Supervisors: All of the above and

Support group members scientifically, emotionally and financially.
Be available both in person and via electronic communication, including regular meetings to discuss work and anything else group members would like to discuss.
Provide a broad perspective on work within the context of the group and the general direction of science.
Provide timely feedback on drafts of manuscripts, talks, grant proposals, etc.
Help identify next career steps, whether inside or outside academia, and provide support towards them.
Identify training opportunities and conferences and support group members in making the most of them.
Point out grant and fellowship opportunities and support applications to appropriate ones.
Care for group members’ mental and physical well-being, and prioritise it above anything else.
When changing priorities, communicate this to others whose work is affected.
Model the group’s values: share problems and incomplete work openly, ask for help, and show that this is how we work at all levels.

Publications

Choice of journal

We post preprints of all work before or at the time of journal submission. We prefer journals that support open and transparent peer review, are non-profit or alternative-profit, and allow first submission in any format. We don’t chase high-impact journals, but recognise that individuals may sometimes want to make different choices. If so, discuss it with your supervisor.

Examples of journals that we like are:

Authorship

We broadly follow University of Cambridge Guidelines on Authorship. Specifically an author is an individual “judged to have made a substantial intellectual or practical contribution to a publication and who agrees to be accountable for that contribution”. This usually reflects:

Making a significant contribution to the conception or design of the project or the acquisition, analysis, or interpretation of data for the work; AND/OR
Drafting the work or reviewing/revising it critically for important intellectual content.

We err on the side of inclusion when not sure if someone’s contributions warrant authorship, but don’t award authorship based on friendship, reciprocity or seniority. While authorship does not require writing any of the paper, we will share drafts and submitted version with all coauthors and give opportunities for critical input. If in doubt, we give more time.

For any group publication, group authorship should be agreed based on the value and volume of each person’s contribution, with more supervisory roles towards the end. Where an order between co-authors cannot clearly be resolved we will randomise the order. Everyone should feel encouraged to raise any questions or misgivings they have about authorship on any particular paper.

Collaborative writing

A paper starts with an outline (e.g., 1 sentence per paragraph) following broadly the structure suggested in Writing for Impact: How to Prepare a Journal Article, that is shared with key collaborators for feedback before engaging in the writing. If writing collaboratively, paragraphs can then be assigned to co-authors. Any finalised paper should be shared with all co-authors at least a week before preprint publication or submission to a journal.

Code

We use GitHub extensively. Any on-going work should be in an open github repository, unless restrictions on data sharing prevent us from doing so. Collaboration on code should proceed via GitHub Issues or discussions and, upon agreement on the way forward to address the issue, Pull Request (with pushing to main branches directly discouraged unless for very minor commits), which in general should be reviewed by at least one other team member. Review your own code before asking others to review it.

The group’s GitHub organisation is https://github.com/epiforecasts. Any group member can create repositories there for work related to the group. Early-stage work can also live in personal repositories if preferred. Projects that involve multiple repositories and/or include core developers from outside the group can live within separate organisations and mention the affiliation to the group in some other way.

Any publication should be accompanied by a github repository with a README file that allows full reproducibility of the results, reviewed by at least one other team member. Code may either be licensed to the group or licensed to the authors and contributors of that work. We suggest the use of the MIT licence as a default.

Projects

Projects are collaborative by default. Each project has a lead who coordinates the work, with decisions made collaboratively. Group packages have a named maintainer who is responsible for technical decisions about design, API and releases.

We aim to build on each other’s work. When starting something new, look at what already exists in the group and talk to the people involved — there may be opportunities to collaborate or extend existing tools rather than starting from scratch.

Meetings

Our meeting structure involves:

Group meetings (weekly, ~90 minutes)

Weekly group meetings are for sharing work and helping each other. Participation is expected of all group members — if you can’t make it, send advance notice.

Every group meeting has a rotating chair. The chair is responsible for conducting the meeting in an inclusive manner that gives everyone the chance to contribute.

Structure

The meeting starts with the chair sharing something not directly related to their own research — something from their life, something they found interesting, or anything else. Each person then briefly says what they’re focusing on.

The main part of the meeting consists of three presentation slots of around 20 minutes each:

10 minutes: Presentation — cover your current work, what you’re stuck on or have questions about, and how others can help or get involved.
5 minutes: Clarifying questions
5 minutes: Silent written feedback in a shared Google Doc (named, to allow follow-up)
Brief summary by presenter and follow-up on any points of particular interest

Other meeting types

At longer intervals we use group meetings to:

Formulate and review broad goals, aims and progress
Run post-mortems on past projects (what went well, what didn’t)
Update this manual
Practice talks ahead of conferences — everyone who presents work from the group should have the opportunity to present it to group members for feedback

Journal club (monthly)

A monthly session to discuss papers, methods or broader topics relevant to the group’s work.

Coffee walks (monthly)

A monthly walk to a coffee shop or similar, replacing a regular meeting. These encourage smaller 2-3 person conversations that don’t happen easily in a full group.

Individual meetings with your supervisor (at least one hour per week)

Each group member has at least one dedicated hour per week of their supervisor’s time. The default is a meeting, but you can use this however is most useful — a code review, written feedback on a draft, or skipping it entirely if you don’t need it that week. These meetings are also the place to discuss career development, training, and any institutional or personal matters. If you want feedback on something specific, share it at least a day before the meeting.

We maintain a Google Doc (or similar) for ongoing notes — updated every meeting with a short summary of discussion and action points.

Subproject meetings (project-dependent frequency)

Where people collaborate on subprojects they are encouraged to agree on a separate meeting schedule to coordinate and update each other on progress. If you want feedback on something specific, share it at least a day before the meeting.

Practicalities

Communication

We use Slack for most communication within the group. The @epiforecasts channel is for group-internal communication. We acknowledge the potential impact of push notifications on productivity and mental health. Everybody is strongly encouraged to turn off all notifications outside of standard working hours (9am-5pm), and is welcome to regularly check into communication channels rather than being alerted by them when within these hours. Generally, the expectation is that team-internal questions put via Slack are answered within 24 hours. After that, it is not considered impolite to send a reminder.

Onboarding

When someone new joins the group, their supervisor introduces them to current projects, tools and communication channels. The group’s projects page provides an overview of current work with links to repositories.

Web site

The group’s web site is at https://epiforecasts.io/. Content can be edited via the github page at https://github.com/epiforecasts/epiforecasts.github.io (choose a .md file and edit, or clone the github repo and do it on your own computer). An interesting and up-to-date web site that showcases good work done in the group is of benefit to everyone, but should not take too much of everyone’s time. It is everyone’s responsibility to contribute to this.

Working hours

One of the benefits of a career in academic research is that it is typically more flexible than other kinds of jobs. However, it is still a job. LSHTM employs people for 35 hours a week, typically expected to happen in 8 hours per weekday with a mandatory 1-hour break. Everybody is strongly encouraged to not work in excess of these hours.