# Creating an Executable Research Article for "epitopepredict: A tool for integrated MHC binding prediction"

This document describes the steps taken to create an Executable Research Article (ERA) for the GigaByte article "epitopepredict: A tool for integrated MHC binding prediction" by Damien Farrell. It was used as a test of several aspects of Stencila including:

- converting the supplied Open Office file to a Markdown file,

- using Stencila's Markdown extensions for enriching the article with code chunks,

- creating and specifying a custom Docker image for the project,

- integration with River Valley's publishing platform.

## Converting the article from Open Office to Markdown

The author supplied the article as an Open Office file (`gigabyte_revised.odt`). We wanted to convert the article to Markdown (`md`) so that we could replace some of the static figures with code. We could have converted the article to a Jupyter Notebook instead, but find it easier to add the figure captions and labels using a text editor and writing Markdown.

Stencila's conversion software, Encoda, can convert from `odt` to `md` but does not support semantic inference for `odt` (e.g. inferring headings from paragraph styles). So as a first step we converted `gigabyte_revised.odt` to Microsoft Word `gigabyte_revised.docx` (using Open Office's "Save As...").

When converting between formats Encoda will examine the document and "reshape" it based on semantic inference. For example, it will look for a heading called "References" or "Bibliography" and convert each of the subsequent paragraphs into a structured reference. Some of this reshaping of the article's structure could also be done by hand by editing the Markdown in the subsequent step. But we wanted to see how far we could get in creating structured Markdown by cleaning up the Word document first. So, in the `docx` file we,

1. Applied the `Title` style to the article title

2. Removed the corresponding author section and instead, added the authors email to the author name paragraph i.e. `Damien Farrell <farrell.damien@gmail.com>1`

3. Made the keyords paragraph a single line i.e. `Keywords:  MHC-binding;...`

4. Removed the `Short title` paragraph.

5. Applied the `Heading 1` and `Heading 2` paragraph styles to level one and two heaindgs respectively.

6. Removed direct formatting on some paragraphs.

7. Moved figure captions to near where they were first mentioned and added placeholder images (this produces a convenient Markdown syntax for enriching with code as described later).

8. For the code sample, created a new paragraph style called `Code` and applied it (this allows the lines in the code sample to be merged together into a code block)

Then we generated the Markdown using the Encoda command line tool:

```sh
encoda convert gigabyte_revised.docx article.md
```

This generated two files `article.md` and `article.references.bib` (containing the BibTeX formatted references).

## Enriching the Markdown with code

The generated Markdown had four static figures indicated using the block extension syntax:

````markdown
figure: Figure 1
:::
![](article.md.media/image1.png)

Performance of the basicmhc1 predictor compared to netMHCpan and MHCflurry for 40 human alleles. (a) Mean Pearson r and (b) mean AUC scores over all alleles. Only alleles with evaluation data for over more than 200 peptides were used. This test dataset used 9-mer peptides only.
:::
````

The file `image1.png` was the placeholder image that we inserted into the Word document and the caption was drawn from the paragraph below it.

To turn these from a static figures to a dynamic, code-drive figures we changed the block extension from `figure` to `chunk`, removed the image and added a python code chunk. We also added added id to the code chunk so that it could be lined to from elsewhere in the document.

````markdown
chunk: Figure 1
:::

Performance of the basicmhc1 predictor compared to netMHCpan and MHCflurry for 40 human alleles. (a) Mean Pearson r and (b) mean AUC scores over all alleles. Only alleles with evaluation data for over more than 200 peptides were used. This test dataset used 9-mer peptides only.

```python
# Placeholder for Python code to be inserted
```

:::
{#fig1}
````