|
1 | 1 | --- |
2 | 2 | title: Guidelines for authors |
3 | | -description: This are the guidelines |
| 3 | +description: | |
| 4 | + This page provides a step-by-step guide for authors to accompany them for formatting and submitting their paper to Computo. |
4 | 5 | format: |
5 | | - html: {} |
| 6 | + html: |
| 7 | + toc: true |
| 8 | + number-sections: true |
| 9 | + fig-align: "center" |
6 | 10 | page-layout: article |
| 11 | +bibliography: ../publications/published.bib |
7 | 12 | --- |
8 | 13 |
|
| 14 | +## Submitting a paper to Computo |
| 15 | + |
| 16 | +Submissions to [Computo](https://computorg.github.io) 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](https://zenodo.org/) or [OSF](https://osf.io/) ). |
| 17 | + |
| 18 | +A Computo submission is thus a git(hub) repository containing: |
| 19 | + |
| 20 | +- 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); |
| 21 | +- configuration files to set up the dependencies in a virtual environment; |
| 22 | +- configuration files to set up the continuous integration rendering the final documents. |
| 23 | + |
| 24 | +The [Computo](https://github.com/computorg) organization provides template repositories for [R](https://github.com/computorg/template-computo-R), [Python](https://github.com/computorg/template-computo-python) and [Julia](https://github.com/computorg/template-computo-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. |
| 25 | + |
| 26 | +### Setup a git repository |
| 27 | + |
| 28 | +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 @fig-template. |
| 29 | + |
| 30 | +{#fig-template width="100%"} |
| 31 | + |
| 32 | +::: {.callout-note title="Using Gitlab"} |
| 33 | +You can use Gitlab for submitting to Computo. We will be giving more detailed support for this in the future. |
| 34 | +::: |
| 35 | + |
| 36 | +### Setup Quarto and Computo extension on your system |
| 37 | + |
| 38 | +You need [quarto](https://quarto.org/) installed on your computer, as well as the [Computo extension](https://github.com/computorg/computo-quarto-extension) to prepare your document. The latter can be installed from a terminal window with the following command line: |
| 39 | + |
| 40 | +```bash |
| 41 | +# Install computo quarto extension |
| 42 | +quarto add computorg/computo-quarto-extension |
| 43 | +``` |
| 44 | + |
| 45 | +### Write your contribution |
| 46 | + |
| 47 | +Write your paper in the `template-computo-LANG.qmd` following the formatting suggestions therein. |
| 48 | + |
| 49 | +::: {.callout-note title="Local compilation"} |
| 50 | +Make sure that you are able to build your manuscript as a standard notebook on your system before proceeding to the next step. |
| 51 | +::: |
| 52 | + |
| 53 | +To build your document (both in PDF and HTML by default), you can run the command `quarto render`, e.g. for the template: |
| 54 | + |
| 55 | +```bash |
| 56 | +# will render both to html and PDF |
| 57 | +quarto render template-computo-{R,python,julia}.qmd |
| 58 | +``` |
| 59 | + |
| 60 | +### Setup dependencies |
| 61 | + |
| 62 | +The next step is to inform Computo of the other packages or tools 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. |
| 63 | + |
| 64 | +#### R users |
| 65 | + |
| 66 | +For the R community, Computo relies on the [**renv**](https://rstudio.github.io/renv/articles/renv.html) package manager to setup a reproducible environment that handles `R` dependencies. Setting up **renv** for use within your repository requires the following steps. First, |
| 67 | + |
| 68 | +```{r} |
| 69 | +#| eval: false |
| 70 | +# Initialize your repo to work with renv |
| 71 | +renv::init() |
| 72 | +``` |
| 73 | + |
| 74 | +will set up your repository for using **renv**. Then, install the required dependencies as usual (via `install.packages()` or via the RStudio IDE) or using **renv** built-in `install()` function: |
| 75 | + |
| 76 | +```{r} |
| 77 | +#| eval: false |
| 78 | +# Install packages you need |
| 79 | +renv::install("ggplot2") # or equivalently install.packages("ggplot2") |
| 80 | +``` |
| 81 | + |
| 82 | +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: |
| 83 | + |
| 84 | +```{r} |
| 85 | +#| eval: false |
| 86 | +install.packages("remotes") |
| 87 | +remotes::install_github("rstudio/gt") |
| 88 | +``` |
| 89 | + |
| 90 | +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: |
| 91 | + |
| 92 | +```{r} |
| 93 | +#| eval: false |
| 94 | +# Register environment and package versions |
| 95 | +renv::snapshot() |
| 96 | +``` |
| 97 | + |
| 98 | +::: {.callout-warning title="The `renv.lock` file"} |
| 99 | +The `renv::snapshot()` command produces a file named `renv.lock` which registered the version of R, quarto and R packages that must be used to compile the publication. This file should be versioned with git. Other files that `snapshot()` might produce should be listed under `.gitignore` and therefore not put under versioning. |
| 100 | +::: |
| 101 | + |
| 102 | +More details for using **renv** can be found: |
| 103 | + |
| 104 | +- either on the [**renv**](https://rstudio.github.io/renv/articles/renv.html) package website, |
| 105 | +- or on the Quarto website at this [dedicated page](https://quarto.org/docs/projects/virtual-environments.html#using-renv). |
| 106 | + |
| 107 | +#### Python users |
| 108 | + |
| 109 | +More to come. |
| 110 | + |
| 111 | +#### Julia users |
| 112 | + |
| 113 | +More to come. |
| 114 | + |
| 115 | +### Ensure reproducibility |
| 116 | + |
| 117 | +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. |
| 118 | + |
| 119 | +#### Use Computo's built-in GitHub Action workflow |
| 120 | + |
| 121 | +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: |
| 122 | + |
| 123 | +```yaml |
| 124 | +name: Main Workflows |
| 125 | + |
| 126 | +on: |
| 127 | + push: |
| 128 | + branches: ["main","master"] |
| 129 | + repository_dispatch: |
| 130 | + types: [custom-event] |
| 131 | + workflow_dispatch: |
| 132 | + pull_request: |
| 133 | + branches: ["main","master"] |
| 134 | + |
| 135 | +jobs: |
| 136 | + call_env_workflow: |
| 137 | + uses: computorg/workflows/.github/workflows/global-env.yml@main |
| 138 | + call_quartopublish_workflow: |
| 139 | + uses: computorg/workflows/.github/workflows/publish-render.yml@main |
| 140 | + needs: call_env_workflow |
| 141 | +``` |
| 142 | +
|
| 143 | +::: {.callout-important title="Content of `build.yml`"} |
| 144 | +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 <computo@sfds.asso.fr>. |
| 145 | +::: |
| 146 | + |
| 147 | +Next, as illustrated in @fig-deploy, under `Settings > Pages` on the webpage of your repository, select **GitHub Actions** as the source for building and deploying your website. |
| 148 | + |
| 149 | +{#fig-deploy width="100%"} |
| 150 | + |
| 151 | +Authors can find more detailed about Computo's workflow in @sec-workflow. |
| 152 | + |
| 153 | +::: {.callout-note title="Compatibility with old reproducibility system"} |
| 154 | +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. |
| 155 | +::: |
| 156 | + |
| 157 | +#### Handle external *system* dependencies |
| 158 | + |
| 159 | +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: |
| 160 | + |
| 161 | +- `setup-env-ci.sh` is for setting up the environment and typically adding system dependencies. The virtual machine on github (runner) may need to install some packages with `apt-get` for R or Python packages. Here is an example of such a file taken from @giorgi2024: |
| 162 | + |
| 163 | +```bash |
| 164 | +# The CI runs on Linux Ubuntu, here goes system dependencies |
| 165 | +# needed at environment setup step |
| 166 | +sudo apt-get install -y libcurl4-openssl-dev |
| 167 | +``` |
| 168 | + |
| 169 | +- `setup-render-ci.sh` is for taking care of specific dependencies outside of quarto, related to rendering, like plotting software or running a script to generate data. Here is an example of such a file taken from @giorgi2024: |
| 170 | + |
| 171 | +```bash |
| 172 | +# The CI runs on Linux Ubuntu, here goes system dependencies |
| 173 | +# needed at rendering step |
| 174 | +sudo apt-get install -y libblas-dev liblapack-dev |
| 175 | +``` |
| 176 | + |
| 177 | +### Submit your manuscript |
| 178 | + |
| 179 | +Once step 4 is successful, you should end up with an HTML version published online, as well as a PDF version (see "Other format" at the end of the table of content of the rendered HTML). This PDF version can be submitted to the [OpenReview](https://openreview.net/group?id=Computo) platform. |
| 180 | + |
| 181 | +## Example papers |
| 182 | + |
| 183 | +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: |
| 184 | + |
| 185 | +| [R](https://computo.sfds.asso.fr/template-computo-R/) | [Python](https://computo.sfds.asso.fr/template-computo-python/) | [Julia](https://computo.sfds.asso.fr/template-computo-julia/) | |
| 186 | +|:-:|:------:|:-----:| |
| 187 | +| [](https://computo.sfds.asso.fr/template-computo-R/) | [](https://computo.sfds.asso.fr/template-computo-python/) | [](https://computo.sfds.asso.fr/template-computo-julia/) | |
| 188 | + |
| 189 | +: {tbl-colwidths="[33,33,33]"} |
| 190 | + |
| 191 | +You can click above either on the name of the language or the screenshot 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 @fig-template-source. |
| 192 | + |
| 193 | +{#fig-template-source width="100%"} |
| 194 | + |
| 195 | +The source code of the page then displays as shown in @fig-template-source-display and the user can click on the icon in the upper-right corner to copy the source code for practicing locally. |
| 196 | + |
| 197 | +{#fig-template-source-display width="100%"} |
| 198 | + |
| 199 | +## Computo's publication workflow {#sec-workflow} |
| 200 | + |
| 201 | +The Computo workflows provide a streamlined publishing pipeline for authors to submit and render Quarto articles directly on GitHub Pages without requiring technical expertise. |
| 202 | + |
| 203 | +### Workflow Summary |
| 204 | + |
| 205 | +{#fig-workflow width="100%"} |
| 206 | + |
| 207 | +As illustrated in @fig-workflow, the publication process consists of two main phases: |
| 208 | + |
| 209 | +1. **Environment Setup and Caching** (`global-env.yml`) |
| 210 | + - Detects and installs required dependencies (Python, R) |
| 211 | + - Caches the environment for faster subsequent runs |
| 212 | + - Customizable via `setup-env-ci.sh` |
| 213 | +2. **Rendering and Deployment** (`publish-render.yml`) |
| 214 | + - Renders Quarto documents to HTML |
| 215 | + - Publish the output to GitHub Pages |
| 216 | + - Customizable via `setup-render-ci.sh` |
| 217 | + |
| 218 | +Authors only need to reference the main workflow file (`build.yml`) in their repository, which orchestrates these processes. |
| 219 | + |
| 220 | +### Key Benefits |
| 221 | + |
| 222 | +- **Simplified Process**: Authors need minimal GitHub Actions knowledge |
| 223 | +- **Optimized Performance**: Environment caching for faster builds |
| 224 | +- **Customization Points**: Two script entry points for custom configurations |
| 225 | +- **Automated Deployment**: Direct publishing to GitHub Pages |
| 226 | + |
| 227 | +Authors simply use the `build.yml` workflow in their repository to trigger the complete process from environment setup to final publication. |
| 228 | + |
| 229 | +## Computo's code of ethics |
| 230 | + |
| 231 | +Originality |
| 232 | + |
| 233 | +: - Authors guarantee that their proposed article is original, and that it infringes no moral intellectual property right of any other person or entity. |
| 234 | +- 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. |
| 235 | + |
| 236 | +Conflicts of interest |
| 237 | + |
| 238 | +: - 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. |
| 239 | +- Authors shall declare all sources of funding for the research presented in the article. |
| 240 | + |
| 241 | +Impartiality |
| 242 | + |
| 243 | +: 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). |
| 244 | + |
| 245 | +Funding |
| 246 | + |
| 247 | +: All funding received by the author(s) shall be clearly stated in the article(s). |
| 248 | + |
| 249 | +Defamatory statements |
| 250 | + |
| 251 | +: Authors guarantee that their proposed article contains no matter of a defamatory, hateful, fraudulent or knowingly inexact character. |
| 252 | + |
| 253 | +References |
| 254 | + |
| 255 | +: Authors guarantee that all the publications used in their work have been cited appropriately. |
| 256 | + |
| 257 | +Copyright/author's right/license compliance |
| 258 | + |
| 259 | +: 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. |
| 260 | + |
| 261 | +## References |
0 commit comments