Computer-Oriented Geoscience Lab Manual

This document is designed to be a reference for lab members and collaborators as well as part of an induction process when people join the lab. It outlines our practices, core principals, ethics, and expectations.

IMPORTANT: The first thing you should do is familiarize yourself with the lab Code of Conduct, which applies to lab members and collaborators, both within and without the lab.

The manual is a living document: lab members are encouraged to submit fixes and improvements to it.

Tip: Use the table of contents icon next to "README.md" 👆🏽 to quickly navigate this document.

1. Induction

When you first join the lab (ideally within the first few weeks), you will have a meeting with Leo to introduce lab protocols, set expectations, add you to communication channels, etc.

For a preview of the things we will do before, during, and after the meeting, take a look at the induction checklist.

2. Expectations

We intend to foster a collegial lab atmosphere, with opportunities for spontaneous discussions and creative opportunities.

• Lab members are not expected to sacrifice personal or leisure time in service of projects.
• Working long hours without interruption can lead to burnout, exhaustion, and overall impedes the type of atmosphere we are trying to develop.

Lab members should endeavor to be good University of Liverpool "citizens", including:

• Participating in seminars and all-hands meetings.
• Contributing to department projects.
• Collaborating with individuals from other groups around campus.
• Fostering new collaborations both internal and external.

We strive to be a part of the intellectual community at the University of Liverpool.

Note: Human resources guidelines take precedence over this section.

3. Communication

If you wish to contact the group, please email Leo directly.

How we communicate within the lab:

• Slack: Our Slack team is the primary mode of communication for quick messages, announcements, reminders, and organizing meetings. Messages are ephemeral so you cannot count of being able to read messages older than 6 months! Use email if you need a record of the conversation.
• GitHub: Each project is assigned a repository on our GitHub account. Reviews of code, text, etc., will be done through the repository. We'll also use to set goals and tasks.
• Group meetings: We will have short monthly group meetings for quick updates from everyone, general discussion, announcements, interesting papers, and informal chat.
• Individual meetings: We aim to have weekly individual meetings to discuss project status, goals, and work through problems and ideas.
• Group members are also encouraged to have meetings and messages with each other. Don't wait until problems build up to seek guidance.

Using our website:

• Source code used to generate the website: compgeolab/website.
• Members are expected to post short news items when they do things of note (join the group, graduation, publication, conferences, awards, etc), as well as to update project and publication information.
• When joining the group, please submit a pull request adding yourself to the website. You are not required to provide a photo and contact information (but you certainly may if you feel comfortable having this information public on the internet).

Social media:

• In general, social media can be freely used if in line with the University of Liverpool Social Media Policy.
• Lab members are encouraged to be respectful and kind while participating if they are representing themselves as lab members.

4. Practices

We have an open-by-default policy, meaning that we assume that software and data will be made openly available under permissive licenses (CC-BY, BSD, etc.) unless there is a very good reason not to (PII or other restrictions).

General guidelines on openness:

• Work on software should be conducted in public repositories.
• Papers, dissertations, and research projects may be held back as private until time of first submission, when they should be made public for peer-review.
• Because most repositories will be made publicly accessible, including their entire history, lab members are required to behave professionally in them (including commit messages, issues, pull requests, code comments, etc).
• Many journals consider the content of referee reports to be confidential. Unless the report is explicitly open, it should not be added to repositories as text, commit messages, or comments in papers.
• Grant proposals developed internally with no external PIs or Co-PIs should be made available unless there is confidential information.
• Grant proposals developed in collaboration with external PIs or Co-PIs may be kept confidential at the external collaborators discretion, although our preference is for them to be open.

Data and code availability:

• All data and models generated by the lab will be made available in both raw and processed forms under CC0 or CC-BY licenses.
• All software will be made available in source form under permissive, BSD-style licenses, unless constrained by external copyleft licensing.
• Source code will be made publicly available on GitHub (or similar), with additional backups possible.
• Every effort will be made to preserve integrity and accessibility of data.

The above text is based on the GBMF DDD Data Sharing Plan by Matthew Turk.

Reproducibility:

• All necessary components to provide reproducibility of a scholarly work should be provided in a publicly accessible location and as part of the scientific record (e.g., by including DOIs to data archives in papers).
• The only exception is when strongly prohibited by external concerns (private or sensitive data, etc).
• Method development papers must include:
  1. The source code that implements the methodology.
  2. Analysis code that generated plots and results from the paper.
• The additional overhead of making work reproducible should not be onerous compared to the other expectations, and can actually reduce the overall effort of developing papers and workflows.
• We will endeavor to respond to requests to reproduce our results by providing necessary technology and data, allowing for reasonable commitments of time and effort.

5. Authorship

The following guidelines apply to publications involving lab members. If you want to collaborate with the lab, please make sure you understand and agree with them.

• Authorship in publications should be explicitly discussed between everyone involved as early as possible, ideally as soon as a project starts.
• We do not view authorship as a zero-sum game.
• Projects that lab members bring with them do not automatically confer authorship rights to either Leo or other lab members.
• However, if work is conducted on them during the course of being present in the lab, acknowledgments would be appreciated (funding acknowledgments are necessary).
• Projects that are collaborated on between lab members confer authorship to those directly involved, whether that collaboration is intellectual, technical, or data sharing. For example, writing code to support analysis or simulation would confer authorship.
• Sharing information during group meetings does not automatically confer authorship.
• If material intellectual contributions (i.e., new directions, solutions to problems, specific and directed project ideas) are made by lab members, that would confer authorship.

External collaborations:

• Please keep Leo apprised of the broad outlines of your external and internal collaborations.
• You do not have to involve Leo or grant him authorship in your external collaborations (though he will probably be happy to be involved if asked).

Project ownership (from a social, rather than a licensing or intellectual property perspective):

• When a project is developed in the lab primarily by a single participant, that participant is free to continue developing and assuming project leadership once they have departed the lab.
• Developing projects that mature, grow, and may contribute to their future career is a key part of the process of scientific development.
• For projects that are collaboratively developed with multiple roughly equal participants, leadership will be decided on a case-by-case basis. Preference is given to providing intellectual freedom and empowerment to earlier-stage researchers.
• Projects that are part of a strategic lab direction may continue to be developed within the lab following departure of a primary developer. Decisions about "forking" or bifurcating development will be held on a case-by-case basis.

6. Ethics

Our actions should be guided by the ethics of participating in the scientific community. This means:

• Prioritizing our professional obligations over fear of being "scooped." For instance, it is unacceptable to interfere with the peer-review process for a paper out of concern of protecting one's own work (i.e., "sitting" on a review for it, making unreasonable requests to delay publication, and so on.)
• When other researchers request assistance with software developed in the lab, we should attempt to make a best effort to assist them. It is not unreasonable to ask for authorship, particularly if the collaboration is extensive.
• Provide citations to all software that assisted in the development of the scholarly work. In general it is acceptable to cite the layers of software in the analysis stack (e.g., NumPy, Matplotlib, IPython/Jupyter, Fatiando, etc.)
• Citations to data sources (DOIs and publications) should be made wherever possible, and where not possible, should be included as footnotes.
• Plagiarism is unacceptable in any form. This includes "first pass" text included in papers or proposals. If including text from an external source, it must be clearly marked as such to ensure it is not accidentally included in the final product.

7. Coding and software

Strive to follow these standards:

• Code should avoid being "too clever", for example clever abuses of languages and algorithms that cut corners in the interest of marginal time savings.
• Clarity and maintainability take precedence over performance to ensure that the code can remain useful beyond the original scope of the project.
• Tests should be considered mandatory for new functionality and bug fixes. These tests should be part of automated testing suites.
• Use black to automatically format Python code.
• Documentation must be added with any new code and should be accessible to newcomers. Include examples whenever possible.
• Comments (not including markdown cells in notebooks) are encouraged but not necessary. Code should be as self-describing as possible. Where complexity is innevitable, comments should allow anyone to understand the shortcuts and reasoning.
• Include citations to algorithms whenever possible, including links to online resources.
• Docstrings should be added to all functions and classes in Python code.

Licensing:

• We value respect for licensing terms and ensuring that we comply with them at all times.
• All code generated in the lab should be open-source with a permissive (non-copyleft) license (MIT, BSD, etc).
• Our preferred license is BSD 3-clause.
• If contributions to upstream copyleft (GPL, etc) projects are made, those contributions can be licensed in accordance with the upstream project license.
• For further discussion see Stodden (2008).

Languages:

• Use Python for most software.
• Experimenting with Julia and other languages is acceptable and even desirable.
• For code that needs to be optimized, the first preference is (in order): Numba, then Cython, and finally C.

Project leadership:

• When software is developed as a result of funded activity, the leadership directions will be set collaboratively during the proposal writing process and between lab members and Leo.
• For externally developed projects, leadership is as decided by the broader community.
• Decisions regarding strategic direction for software projects (including algorithmic strategies) will be made collaboratively.
• For technical directions on lab-developed software, we operate by "lazy consensus".

External projects:

• We strive to be good "citizens" of the broader open-source community.
• We encourage lab members to contribute upstream to open-source projects.
• Projects developed with external collaborators (e.g., Fatiando a Terra) should have their discussions held openly. This can help discourage the notion that projects developed by lab members are not community projects.
• For more discussion about this topic, see Matt Turk's paper Scaling a Code in the Human Dimension.

8. Health resources at Liverpool

Your first priority should always be your own health, safety, and well-being. No project, paper, grant or collaboration is more important than that.

In particular, time as a graduate students and as a postdoc is known to cause undue stress, resulting in consequences ranging from mild to extremely severe.

The University of Liverpool has a number of resources that may be of assistance:

• Student Services: General information and links to the different types of support offered to university students.
• Mental Health Advisory Service: The service can help you settle into student life and offers advisory on mental health issues. If you feel concerned that you or someone you know may have more complex mental health needs, contact the Mental Health Advisory Service ([email protected] or call 0151 794 3304).
• Counselling Service: The University offers drop-in counselling sessions. This is not an emergency service. In the event of an emergency call 2222 (internal) or 999 (external).
• Self-help Information: There is a lot of information on self-help with tips and information.

License

The manual is available under the Creative Commons Attribution 4.0 International (CC BY 4.0) license.

---

Based on the excellent Lab Carpentry blueprints, with material adapted from the Data Intensive Biology Lab and the Data Exploration Lab.