Guidelines for authors

This page provides a step-by-step guide for authors to accompany them for formatting and submitting their paper to Computo.

1 A step-by-step guide to submitting a paper to Computo

Submissions to Computo require both scientific content (typically equations, codes and figures, data) and a proof that this content is reproducible. This is achieved by means of i) a notebook system, ii) a virtual environment freezing the dependencies and iii) continuous integration (plus, if needed, an external website to store large data files such a Zenodo or OSF).

A Computo submission is thus a Git(Hub) repository containing:

• the source files of the notebook (a quarto .qmd file + a BibTeX .bib file + some statics files, e.g. figures or small .csv data tables);
• configuration files to set up the dependencies in a virtual environment;
• configuration files to set up the continuous integration rendering the final documents.

The Computo organization provides template repositories for R, Python and Julia contributors. In the following sections, we detail step-by-step what authors have to do in order to format their paper for submission to Computo.

1.1 Setup a git repository

Setup a new github repository by going on the URL of either the R or Python or Julia template repository and clicking on the “use this template” button on the top of the page, as illustrated in Figure 1.

Figure 1: Screenshot of the R Computo template GitHub page.

Branches

When you fork a GitHub repository, be it classic or template, GitHub asks if you want to fork all branches (there is a box called Include all branches). You only need to fork the main branch so you do not have to check that box.

Public repository

The paper will be automatically published online using GitHub pages. This is possible only with public repositories. Hence, when you initialize your repository from the template, make sure that the Public box is checked (the default) and not the Private one.

In summary, before clicking on Create repository, you should have the options documented in Figure 2.

Figure 2: Forking a GitHub template.

Using Gitlab

You can use Gitlab for submitting to Computo. We will be giving more detailed support for this in the future.

1.2 Setup Quarto and Computo extension on your system

You need quarto installed on your computer, as well as the Computo extension to prepare your document.

To install Quarto, you should refer to the instructions here: https://quarto.org/docs/get-started/.

Once Quarto is properly installed locally on your computer, you can install the Computo Quarto extension from a terminal window with the following command line:

# Install computo quarto extension
quarto add computorg/computo-quarto-extension

Multiple collaborators

If you are collaborating with others when writing your contributions, each collaborator needs to:

• clone the repository,
• install Quarto,
• install the Computo Quarto extension by executing the above command.

1.3 Write your contribution

In the forked template, there are mainly two files you are expected to modify for writing your contribution: template-computo-LANG.qmd (where LANG is to be replaced with either R, python or julia) and _quarto.yml.

1.3.1 Main content of your contribution

The main body of your paper (starting with the Introduction section) should be written in the template-computo-LANG.qmd following the formatting suggestions therein.

Local compilation

Make sure that you are able to build your manuscript as a standard notebook on your system before proceeding to the next step.

To build your document (both in PDF and HTML by default), you can run the command quarto render, e.g. for the template:

# will render both to html and PDF
quarto render template-computo-{R,python,julia}.qmd

1.3.2 Metadata of your contribution

To customise title, authors, date, abstract and so on, you should modify the _quarto.yml file. By default, it looks like this:

project:
  title: "template-computo-R"

title: "Template for contribution to Computo"
subtitle: "Example dedicated to `R` users"
author:
  - name: Jane Doe
    corresponding: true
    email: janedoe@nowhere.moon
    url: https://janedoe.someplace.themoon.org
    orcid: 0000-0000-0000-0000
    affiliations:
      - name: Name of Affiliation one
        department: Statistics
        url: https://someplace.themoon.org
  - name: John Doe
    email: johndoe@nowhere.moon
    url: https://johndoe.someplace.themoon.org
    orcid: 0000-0000-0000-0000
    affiliations:
      - name: Name of Afficiliation two
        department: Computer Science
        url: https://someplace.themoon.org
date: last-modified
date-modified: last-modified
description: |
  This document provides a template based on the [`quarto`](https://quarto.org/) system for contributions to Computo, using the [`quarto journal extension`](https://github.com/computorg/computo-quarto-extension), the knitr kernel (R user) and [`renv`](https://rstudio.github.io/renv/articles/renv.html) to set-up the dependencies.
abstract: >+
  Lorem ipsum dolor sit amet, consectetur adipiscing elit. Curabitur posuere vestibulum facilisis. Aenean pretium orci augue, quis lobortis libero accumsan eu. Nam mollis lorem sit amet pellentesque ullamcorper. Curabitur lobortis libero eget malesuada vestibulum. Nam nec nibh massa. Pellentesque porttitor cursus tellus. Mauris urna erat, rhoncus sed faucibus sit amet, venenatis eu ipsum.
keywords: [key1, key2, key3]
bibliography: references.bib
github-user: computorg
repo: "template-computo-r"
draft: true # set to false once the build is running
published: false # will be set to true once accepted
format:
  computo-html: default
  computo-pdf: default

You can customize most of the entries in that file except project:, published: and format:. If your contribution is accepted for publication, the associate editors will modify parts of this file accordingly.

1.4 Setup dependencies

The next step is to inform Computo of the other packages, tools and environment that your paper might depend upon. It is important to freeze their versions to ensure reproducibility. This step is inherently handled differently whether you are an R, Python or Julia user.

R users

For the R community, Computo relies on the renv package manager to setup a reproducible environment that handles R dependencies. Setting up renv for use within your repository requires the following steps. First, you need to initialize your repository to work with renv. This is done by running:

# Initialize your repo to work with renv
renv::init()

The purpose of this function is to create a renv.lock file that registers the version of R and quarto along with all the packages and their versions that renv finds in your notebook.

Upon cloning one of our template however, the renv.lock file already exists. Therefore, when you execute renv::init(), you will be provided with the following choices:

> renv::init()
This project already has a lockfile. What would you like to do? 

1: Restore the project from the lockfile.
2: Discard the lockfile and re-initialize the project.
3: Activate the project without snapshotting or installing any packages.
4: Abort project initialization.

You should choose Option 2, which will extend the message box with:

- Linking packages into the project library ... Done!
- Lockfile written to "~/Projects/computo/my-computo-submission/renv.lock".
- renv activated -- please restart the R session.

prompting you to restart your R session which you should do right away. If you now inspect the existing renv.lock file, you will see the R version you locally run on along with a bunch of packages listed there. This is because template-computo-R.qmd includes the ggplot2 package by default to showcase how you can include plots in your paper. As a result, renv registers ggplot2 along with all its dependencies in the renv.lock file.

Now you can write your contribution, using all the packages you need. Install the required dependencies as usual (via install.packages() or via the RStudio IDE) or using renv built-in install() function:

# Install packages you need
renv::install("ggplot2") # or equivalently install.packages("ggplot2")

Non-CRAN packages (e.g. Github packages) can be used. To install such packages, you need to first install the remotes package. Then, if you want to install the development version of e.g. the gt package hosted by rstudio GitHub account (useful for nicely and easily formatting tables btw), you would do:

install.packages("remotes")
remotes::install_github("rstudio/gt")

Once you are done, you need to freeze the environment and package versions that are going to be used to run the calculations within your paper. This is achieved via:

# Register environment and package versions
renv::snapshot()

The renv.lock file

The renv.lock should be versioned with git. Other files that renv::snapshot() might produce should be listed under .gitignore and therefore not put under versioning.

More details for using renv can be found:

• either on the renv package website,
• or on the Quarto website at this dedicated page.

Python users

If you are writing a contribution that relies on Python code and Python packages, you can locally install and use those packages any way you like.

We then handle your Python package dependencies in our CI/CD scripts using micromamba, which requires that you ship a file called environment.yml that lists your dependencies. This file should be stored at the root of your repository. Here is the typical content of such a file:

name: computo
channels:
  - conda-forge
dependencies:
  - python=3.11
  - jupyter
  - matplotlib
  - pandas
  - scipy
  - seaborn
  - scikit-learn
  - numpy=1.24
  - numba

The name: entry

You can choose a name of your liking. It should be short with no spaces and uniquely refer to the title or content of your contribution.

The channels: entry

In most cases, you should leave it to the value conda-forge. Some advanced configurations for which you might want to reference other channels can be found by browsing our list of published papers here.

The dependencies: entry

This is where you should list all your dependencies. It is good practice to list python itself so you can provide the version you used as done above. Other dependencies written in the outer list will be installed from the listed channel using micromamba. It is recommended to indicate which version was used as done above for numpy for instance. If your work relies on packages that have not been made available as conda packages, you can add a pip entry to the outer list and add those packages under the pip: list as in:

name: clayton
channels:
  - conda-forge
dependencies:
  - jupyter
  - numpy
  - scipy
  - matplotlib
  - pandas
  - seaborn
  - pip:
    - clayton

Automatic registration of packages

Currently and differently from what we provide for R users, we do not have implemented an automatic way of registering environment, packages and their versions. Hence, you are expected to do that manually.

requirements.txt

If your work exclusively depends on packages installed from pip and you are used to listing dependencies in a requirements.txt file, you can ship this file instead of the environment.yml file and our CI/CD scripts should run smoothly.

Julia users

More to come.

1.5 Ensure reproducibility

Now that you have written your contribution in the correct template and set up its dependencies, you need to set up continuous integration via GitHub Actions in order to ensure reproducibility of your work and its publication as a webpage.

1.5.1 Use Computo’s built-in GitHub Action workflow

Computo has a built-in workflow for just that purpose which comes in the form of a YAML file describing a GitHub Action. It should have been automatically added to your repository when you cloned one of our templates. It is located under .github/workflows/build.yml and its content should exactly match the following:

name: Main Workflows

on:
  push:
    branches: ["main","master"]
  repository_dispatch:
    types: [custom-event] 
  workflow_dispatch:
  pull_request:
    branches: ["main","master"]


jobs:
  call_env_workflow:
    uses: computorg/workflows/.github/workflows/global-env.yml@main
  call_quartopublish_workflow:
    permissions:
      id-token: write
      contents: write
      pages: write
    uses: computorg/workflows/.github/workflows/publish-render.yml@main
    needs: call_env_workflow

Content of build.yml

Authors should under no circumstances modify this file. If you encounter a problem (such as the CI not completing successfully), please get in touch with us at contact@computo-journal.org.

Next, as illustrated in Figure 3, under Settings > Pages on the webpage of your repository, select GitHub Actions as the source for building and deploying your website.

Figure 3: Deploy your website with GitHub Actions

Authors can find more detailed about Computo’s workflow in Section 3.

Compatibility with old reproducibility system

You can safely delete the gh-pages branch if you have one, as we don’t need anymore to push the HTML files to the site.

1.5.2 Handle external system dependencies

While you should have by now handled R, Python or Julia package dependencies using appropriate tools that register environments and version numbers, some of the packages your work depend upon might require external system dependencies that must be installed either when setting up the environment in the GitHub runner or when taking care of the paper rendering or in both cases. To take care of that, you can add and customize two scripts at the root of your repository. Specifically:

• setup-env-ci.sh is meant to install system dependencies required to set up the environment in the GitHub runner. Here is an example of such a file taken from Giorgi, Kaakai, and Lemaire (2025):

# The CI runs on Linux Ubuntu, here goes system dependencies
# needed at environment setup step
sudo apt-get install -y libcurl4-openssl-dev

• setup-render-ci.sh is meant to install system dependencies required for rendering the paper, like plotting software or running a script to generate data. Here is an example of such a file taken from Giorgi, Kaakai, and Lemaire (2025):

# The CI runs on Linux Ubuntu, here goes system dependencies
# needed at rendering step
sudo apt-get install -y libblas-dev liblapack-dev

Ubuntu GitHub runner

Remember that the GitHub runner uses Linux Ubuntu and therefore software installation is achieved through apt-get. Furthermore, you should prepend calls to apt-get with the sudo word to specify that you want to execute this command as administrator of the machine.

1.6 Submit your manuscript

Once you are done writing your contribution, recall that you can render it in both HTML and PDF by running quarto render . from a terminal within the folder in which you cloned the Computo template.

If the Quarto rendering is successful locally (hence you get both HTML and PDF files), then, once you push the last modification to your repository on GitHub, the continuous integration and deployment scripts should automatically run and, if successful, the HTML version of your contribution will be published online, as well as a PDF version (see “Other format” at the end of the table of content of the rendered HTML).

The PDF version should then be submitted to the OpenReview platform which will trigger the scientific review of the content of the PDF as well as the technical and reproducibility review from the repository.

You can find more details about the scientific reviewing process in the dedicated page on this website (Reviewers tabs).

1.7 Accepted manuscript

If your submission is accepted for publication, you will be asked to transfer the ownership of the repository that hosts your paper to the Computo GitHub organization. To do that, you must go on the main page of your repository in a web browser and click on the Settings tab as indicated in Figure 4.

Figure 4: Accessing the settings of a GitHub repository.

Once inside the settings of the repository, scroll all the way down to the bottom of the page until you see Danger Zone in red color and click on Transfer as indicated in Figure 5.

Figure 5: Accessing the interface for ownership transfer.

A new page opens where you need to select Specify an organization or username and write computorg (see Figure 6). Then you type what is asked in the blank box and click on I understand, transfer this repository and you’re all set!

Figure 6: The ownership transfer page.

2 Example papers

Authors can find example papers for each language that illustrate the expected content and some key features for formatting contributions as well as reminding some of the guidelines:

R

https://computo-journal.org/template-computo-R/

Python

https://computo-journal.org/template-computo-python/

Julia

https://computo-journal.org/template-computo-julia/

You can click above either on the screenshot or the URL to access the rendered version of each example paper. At any time you can then access the source code by clicking on the </> Source button in the upper-right corner of the page as illustrated in Figure 7.

Figure 7: Accessing sources of the rendered example papers.

The source code of the page then displays as shown in Figure 8 and the user can click on the icon in the upper-right corner to copy the source code for practicing locally.

Figure 8: Copying the sources of the rendered example papers.

3 Computo’s publication workflow

The Computo workflows provide a streamlined publishing pipeline for authors to submit and render Quarto articles directly on GitHub Pages without requiring technical expertise.

3.1 Workflow Summary

Figure 9: Computo Workflow Structure

As illustrated in Figure 9, the publication process consists of two main phases:

1. Environment Setup and Caching (global-env.yml)
   • Detects and installs required dependencies (Python, R)
   • Caches the environment for faster subsequent runs
   • Customizable via setup-env-ci.sh
2. Rendering and Deployment (publish-render.yml)
   • Renders Quarto documents to HTML
   • Publish the output to GitHub Pages
   • Customizable via setup-render-ci.sh

Authors only need to reference the main workflow file (build.yml) in their repository, which orchestrates these processes.

3.2 Key Benefits

• Simplified Process: Authors need minimal GitHub Actions knowledge
• Optimized Performance: Environment caching for faster builds
• Customization Points: Two script entry points for custom configurations
• Automated Deployment: Direct publishing to GitHub Pages

Authors simply use the build.yml workflow in their repository to trigger the complete process from environment setup to final publication.

3.3 Reproducing an existing paper published in Computo

Our publication workflow makes it very easy for anyone to reproduce a given paper. To do that, you can first clone the repository. Then you need to install Quarto and the Computo Quarto extension in the published-202412-giorgi-efficient folder that the cloning step made. Finally, you can render the document. In summary, you do that with the following commands:

git clone https://github.com/computorg/published-202412-giorgi-efficient.git
cd published-202412-giorgi-efficient
quarto add computorg/computo-quarto-extension
quarto render .

4 Computo’s code of ethics

Originality

• Authors guarantee that their proposed article is original, and that it infringes no moral intellectual property right of any other person or entity.
• Authors guarantee that their proposed article has not been published previously, and that they have not submitted the proposed article simultaneously to any other journal.

Conflicts of interest

• Authors shall disclose any potential conflict of interest, whether it is professional, financial or other, to the journal’s Editor, if this conflict could be interpreted as having influenced their work.
• Authors shall declare all sources of funding for the research presented in the article.

Impartiality

All articles are examined impartially, and their merits are assessed regardless of the sex, religion, sexual orientation, nationality, ethnic origin, length of service or institutional affiliation of the author(s).

Funding

All funding received by the author(s) shall be clearly stated in the article(s).

Defamatory statements

Authors guarantee that their proposed article contains no matter of a defamatory, hateful, fraudulent or knowingly inexact character.

References

Authors guarantee that all the publications used in their work have been cited appropriately.

Copyright/author’s right/license compliance

Authors guarantee that they comply with the usage license of any third party contents/works (code, software, data, figures/images, documents, etc.) that were used to produce their work.

5 References

Giorgi, Daphné, Sarah Kaakai, and Vincent Lemaire. 2025. “Efficient Simulation of Individual-Based Population Models.” {Research article}. Computo. https://doi.org/10.57750/sfxn-1t05.