tutorial.md

layout	tutorial_hands_on
title	Text-Mining articles with GROBID
level	Introductory
questions	What is GROBID? How to get started with GROBID in Galaxy?
objectives	Log in to Galaxy Upload files to the platform Use GROBID to extract information from publications
time_estimation	1H
key_points	You can use GROBID from within Galaxy to mine text.
tags	text mining
contributions	authorship funding Sch-Da deKCD mwk deNBI

This tutorial shows you how you can use GROBID on Galaxy. The first couple of steps derive from [A short introduction to Galaxy]({% link topics/introduction/tutorials/galaxy-intro-short/tutorial.html %}).

In this tutorial, we will cover:

1. TOC {:toc}

{: .agenda}

What is GROBID?

GROBID stands for GeneRation Of BIbliographic Data. It is a text mining library for large-scale extraction of bibliographical metadata and now available on Galaxy.

Why use GROBID in Galaxy?

Galaxy is an open-source data analysis platform. Using GROBID on Galaxy gives you access to 4000+ tools to work with - all without programming skills. Moreover, Galaxy allows you to leverage high-performance computing (HPC) resources from within your browser. This is particularly useful, if you are working on large amounts of texts.

If your texts are not machine-readable, you could use Tesseract directly from within Galaxy or perform further text-mining tasks or visualise your results after having run GROBID. All directly in Galaxy. You can chain different tools into workflows that you can easily rerun, allowing you to easily automate your analysis steps and make your tasks sharable.

Additionally, FAIR and reproducible research are at the core of what we do. Galaxy supports best practices in Research Data Management through all steps of the research data life-cycle and makes reproducibility a built-in default to support your research.

Get started in Galaxy

Create an account on Galaxy

To use Galaxy's full potential, you must register and create an account. You can skip this step if you already have a Galaxy account.

{% snippet faqs/galaxy/account_create.md %}

Alternatively, you can access Galaxy using a single sign-on of your choice, for example, from IAM4NFDI on Galaxy Europe. The interface could look like this:

Log in to Galaxy

Log in to Galaxy

1. Open your favourite browser (Chrome, Safari, Edge or Firefox as your browser, not Internet Explorer!)
2. Browse to your Galaxy instance, for example Galaxy Europe
3. Log in with your credentials

Different Galaxy servers This is an image of Galaxy Europe, located at usegalaxy.eu

The particular Galaxy server you are using may look slightly different and have a different web address.

You can also find more possible Galaxy servers at the top of this tutorial in Available on these Galaxies {: .comment} {: .hands_on}

The Galaxy homepage is divided into four sections (panels):

• The Activity Bar on the left: This is where you will navigate to the resources in Galaxy (Tools {% icon tool %}, Workflows {% icon galaxy-workflows-activity %}, Histories {% icon galaxy-history-storage-choice %}, etc.)
• Currently active "Activity Panel" on the left: By default, the {% icon tool %} Tools activity will be active and its panel will be expanded
• Viewing panel in the middle: The main area for context for your analysis
• History of analysis and files on the right: Shows your "current" history; i.e.: Where any new files for your analysis will be stored


The first time you use Galaxy, your history panel is empty.

Name your current history

Your "History" is on the panel on the right. It is a record of the actions you have taken.

Name history

1. Go to the History panel (on the right)

2. Click {% icon galaxy-pencil %} (Edit) next to the history name (which by default is "Unnamed history")

   {:width="250px"}

   In some previous versions of Galaxy, you will need to click the history name to rename it as shown here: {:width="320px"} {: .comment}

3. Type in a new name, for example, "Testing GROBID"

4. Click Save

Renaming not an option? If renaming does not work, you may not be logged in, so try logging in to Galaxy first. Anonymous users can only have one history, and they cannot rename it. {: .comment}

{: .hands_on}

Upload a file to Galaxy

There are many different ways of getting data to Galaxy. The "Activity Bar" is located on the leftmost part of the interface. It shows you various options.

For this tutorial, we suggest you use a scientific article of your choice. Make sure that the article provider allows text mining before you take the next steps.

Upload a file

1. At the top of the Activity Bar, click the {% icon galaxy-upload %} Upload activity

   

   This brings up a box:

   

2. Click Paste/Fetch data

3. Paste in the address of the files you want to upload in here.

4. Click Start

5. Click Close {: .hands_on}

Your uploaded file is now in your current history. When the file has been uploaded to Galaxy, it will turn green.

After this, you will see your first history item (called a "dataset") in Galaxy's right panel. It will go through the grey (preparing/queued) and yellow (running) states to become green (success).

{: .comment}

The contents of the file will be displayed in the central Galaxy panel. If the dataset is large, you will see a warning message which explains that only the first megabyte is shown.

View the text files content

1. Click the {% icon galaxy-eye %} (eye) icon next to the dataset name, to look at the file content.

   

2. Check the datatype - is it PDF? Then you are all set. Otherwise, adapt the datatype.

   {% snippet faqs/galaxy/datasets_change_datatype.md datatype="datatypes" %}

{: .hands_on}

If you want to work with multiple articles at once, we suggest uploading all of them at once and creating a collection out of them.

When does it make sense for you to create a collection?

{% snippet faqs/galaxy/histories_datasets_vs_collections.md %}

How can you create collections from single datasets?

{% snippet faqs/galaxy/collections_autobuild_list.md %}

Your articles are now on Galaxy, great! The next steps now depend on your article: was it born-digital? Then you can jump ahead to using GROBID.

Is it a scanned text? In that case, your text will not be machine-readable or searchable. In this case, you need to first perform optical character recognition (OCR) to properly use GROBID with your article. This is possible in Galaxy in various ways, you could, for example, use {% tool Tesseract %} on Galaxy and make your PDF machine readable.

Once your article is ready, we can run GROBID on it.

Run GROBID on Galaxy

Navigate to the activity bar on the left-hand side and click on {% icon tool %} tools. Enter GROBID in the search bar. Click on the search result {% tool GROBID extract %} (or this link) to see the tool.

Now, you can select how to process your PDF or PDFs.

Processing files with GROBID

1. Click on the dropdown menu to select Scientific article PDF to TEI

2. Scientific article PDF: Select the article or articles you want to process. You can select single datasets, multiple datasets and a Dataset collection. You can use the dropdown menu or drag and drop them from your history on the right-hand side. 

3. Optionally, you can click on Advanced options to further specify your output.

4. Once you are done, click on the {% icon workflow-run %} Run Tool button at the top or bottom of the tool to run it.

{: .hands_on}

The job is now running. It will create a new dataset in your history, on top of your upload. The dataset will go through the grey (preparing/queued) and yellow (running) states to become green (success).

Once it is green, you can click on the {% icon galaxy-eye %} (eye) icon next to the dataset name, to look at the file content. In this example, we chose to convert the article to TEI.

What is TEI? TEI, or the Text Encoding Initiative is an international project to develop guidelines for "machine-actionable cultural heritage texts." For more details and guidelines, visit the TEI website.

{: .comment}

The output of your file is an annotated TEI file.

Should you notice, that you made a mistake, selected the wrong input file or output format, do not worry. It is easy to re-run jobs in Galaxy:

{% snippet faqs/galaxy/tools_rerun.md %}

This allows you to see exactly what oarameters you used when you ran the job before and enables you to adapt those, if needed. Make your changes and click on Run Tool. This creates a new dataset with updated parameters.

In the next step, we want to extract datasets mentioned in the scientific articles. We will use GROBID DataStet to achieve this: Navigate to the activity bar on the left-hand side once more and click on {% icon tool %} tools. Enter GROBID in the search bar. Click on the search result {% tool GROBID DataStet %} (or this link).

Using GROBID DataStet

1. Scientific article PDF or TEI XML: Select the TEI output you created earlier. If you have not renamed it, it will be calles GROBID on dataset or something similar.

2. Output format: Select Enriched TEI XML in the dropdown menu. 

3. Click on the {% icon workflow-run %} Run Tool button at the top or bottom of the tool to run it.

{: .hands_on}

Beware: If you want a JSON output, you need to run it on the whole PDF. In this case, inputting TEI and selecting JSON will run into an error. For more information on this, see the tool help.

{% snippet faqs/galaxy/tools_help.md %}

The job starts running. Once it turns green, it is ready for you to inspect.