Documentation

• 1: Installation
• 2: Quick start
• 3: Components
• 3.1: Projects
• 3.2: Datasets
• 3.3: Vocabularies
• 3.4: Plugins
• 3.5: Data cleaning scripts
• 3.6: Console
• 4: Import data
• 5: Create a project
• 6: Create a plugin
• 6.1: Simple
• 6.2: Advanced
• 7: Explore
• 7.1: Install a component
• 8: Share

1 - Installation

LinkR can be installed and run from RStudio or installed on ShinyProxy.

Installation on RStudio

The remotes library will be required for the installation of LinkR. You can install it with this command:

install.packages("remotes")

Stable version

Install the latest stable version with this command:

remotes::install_gitlab("interhop/linkr/linkr", host = "framagit.org")

Development version

To install the latest development version, add @dev to the end of the git repository link.

remotes::install_gitlab("interhop/linkr/linkr@dev", host = "framagit.org")

Important - shiny.fluent version

You also need to install version 0.3.0 of shiny.fluent.

By default, version 0.4.0 is installed, but it has unresolved bugs.

remotes::install_github('Appsilon/shiny.fluent', ref = 'dd1c956')

Start LinkR

To launch LinkR from RStudio or from an R console, execute the function linkr.

The following arguments need to be specified and are sufficient for simple use of LinkR:

• language: choose the language between “fr” and “en”
• app_folder: choose the folder where the files necessary for the application’s operation will be saved

You can also modify these arguments:

• local: choose TRUE if you want to launch the application locally (without an internet connection), FALSE otherwise
• debug: TRUE if you want log messages to be displayed in the console or in the log file, FALSE otherwise
• log_file: TRUE if you want a log file to be created and the log to be accessible from LinkR, FALSE otherwise

linkr::linkr(language = "fr", app_folder = "/home/user_name")

Installation on ShinyProxy

…

2 - Quick start

Introduction

In this tutorial, we will see how to:

• import data
• import a project
• launch this project

At the end of this tutorial, you will have a dashboard that allows you to visualize data from 100 patients.

No need for advanced programming knowledge to complete this tutorial!

The only line of code you’ll need to run is the one you see below.

However, you will need to install RStudio.

To do this, you can refer to the tutorials on the analyse-R website:

• How to install RStudio
• First contact with RStudio

After installing LinkR, launch the app with this code.

linkr::linkr(language = "fr", app_folder = "/home/user_name")

A tab should open in your browser, showing the LinkR home page.

Go back to the installation page for more information on the arguments that the function can take.

Now, let’s see how to import data.

Import data

We will import data from the content catalog.

From the homepage or the menu at the top of the page, go to the “Content Catalog” page.

Find Saint-Malo on the map and select InterHop.

On the right side of the screen, you will see the homepage of InterHop’s shared content: plugins and datasets are among the offerings.

To access the details of this shared content, click the “Show content” button at the bottom of the page.

We want to download the data for the “MIMIC-IV demo set”.

So, click on the “Datasets” tab at the top right of the screen, then click on the widget corresponding to our dataset.

All that remains is to click on “Install”, and there you have it, the dataset (or at least its code) is installed!

No, no data is downloaded during the installation of a dataset.

Health data, which is sensitive data, must be handled within a specific regulatory framework.

Here, we have downloaded the code that allows access to the data, not the data itself.

In this case, the data is anonymized, and therefore not subject to GDPR. That’s why this code can, without any authentication, download data from the 100-patient MIMIC-IV test database.

You can read this article for more information about the MIMIC database.

Let’s now see how to import a project.

Import a project

We will proceed in the same way to import a project.

Go to the “Content Catalog” page, and this time select the DOMASIA laboratory in Rennes.

Click on “Show content”, you should arrive at the “Projects” tab, and you should see the “Dashboard quality indicators” project.

When I click on the project, I see its description appear: this project creates a dashboard presenting the quality indicators of patient care.

Click on “Install”.

Launch the project

To launch our project, we need to link the project and the dataset.

To do this, go to the “Projects” page, using the first icon from the left at the top of the screen or from the homepage (which you can access by clicking on the LinkR icon at the top left of the screen).

Then click on the “Configure the project” icon, this allows you to configure the project without loading the data and widgets.

Click on the “Dataset” tab, then select the dataset we previously installed: “MIMIC-IV demo set”.

You can now click on one of the data pages (the icons with the characters).

Several things happen.

• The dataset code, being run for the first time, downloads the CSV files from the database, which may take a few minutes. Loading the following times will be faster, as the files will be stored locally and will not need to be downloaded again.

• A subset including all patients will be created.

• The widgets will load and display the data.

Finally, click on the “Aggregated data” icon (the one with multiple characters), and you will see the dashboard appear!

The data in this set (MIMIC-IV) is anonymized, so the dates have been altered (from 2110 to 2202), which is why the admission over time figure, at the top right, does not render correctly.

The table at the bottom right should display the ICD-10 diagnoses. Here it shows numbers because we did not import the ICD-10 terminology: the correspondence with the names corresponding to the ICD-10 codes cannot be made. Go here to learn how to import terminologies!

Conclusion

In this tutorial, we have seen how to import data and import a project from the content catalog.

To import your data, follow this tutorial.

To create a project from scratch, follow this tutorial.

3 - Components

LinkR is organized around projects, where datasets are loaded, containing data in the OMOP format and using standard terminologies indexed on Athena.

These data can be enhanced using and sharing data cleaning scripts.

Within these projects, users can visualize and analyze the data using widgets, which are configured plugins.

It is also possible to access an R and Python development environment via the console.

3.1 - Projects

3.2 - Datasets

3.3 - Vocabularies

3.4 - Plugins

3.5 - Data cleaning scripts

3.6 - Console

4 - Import data

Create a dataset

To import data, navigate to the Datasets page from the top menu or from the widget on the home page.

Then, click on the Plus (+) icon on the left side of the screen to create a new dataset.

Choose a name. For this example, we will import the dataset MIMIC-IV demo set.

For more information about the MIMIC database, click here.

Once the set is created, click on the widget corresponding to this set and go to the Code tab on the right side of the screen.

You will see that R code has been automatically generated.

import_dataset function

To import data into LinkR, we use the import_dataset function.

Here are the arguments that this function can take.

Some arguments do not need to be modified, and we will use default values:

• r, d: These are variables used to communicate information within the application; they should be passed as arguments to be available inside the function.
• dataset_id: This is the ID of the current dataset. You can replace this argument with %dataset_id%, which will be substituted by the dataset ID.

You will need to modify these arguments:

• omop_version: This is the version of OMOP for the data you will import. If you specify %omop_version%, the version indicated in the Summary tab will be used.
• data_source: Indicate here where the data comes from, db if the data comes from a database connection, disk if it is stored locally.
• data_folder: If you selected disk for the data_source argument, specify the folder containing the data here.
• con: If you selected db for the data_source argument, specify the database connection variable here.
• load_tables: By default, all OMOP tables will be loaded from the specified source. If you want to load only some of these tables, specify the tables to import here. For example, load_tables = c('person', 'visit_occurrence', 'visit_detail').

Connecting to a database

Connecting and reading data

You can import data as part of a database connection.

First, configure the connection object con using the DBI library, then use the import_dataset function.

To indicate that we are loading a database, the data_source argument must be set to “db”.

The con argument will take our con object as its value.

# Connection object. We'll go into detail below.
con <- DBI::dbConnect(...)

# Function to load data when the project loads
import_dataset(
    r, d, dataset_id = %dataset_id%, omop_version = "5.4",
    data_source = "db", con = con
)

This code will establish a connection to the database when the project loads.

Let’s now see how to configure the database connection.

PostgreSQL

con <- DBI::dbConnect(
    RPostgres::Postgres(),
    host = "localhost",
    port = 5432,
    dbname = "mimic-iv-demo",
    user = "postgres",
    password = "postgres"
)

DuckDB

You can connect to a DuckDB database via the .db file.

con <- DBI::dbConnect(duckdb::duckdb(), dbdir = "/my_db_file.db", read_only = TRUE)

Complete example

# Connecting to the local PostgreSQL database
con <- DBI::dbConnect(
    RPostgres::Postgres(),
    host = "localhost",
    port = 5432,
    dbname = "mimic-iv-demo",
    user = "postgres",
    password = "postgres"
)

# Loading the data when the project starts
import_dataset(
    r, d, dataset_id = %dataset_id%, omop_version = %omop_version%,
    data_source = "db", con = con
)

Importing files

You can also import files without using a database connection.

To do this:

• Specify disk for the data_source argument.
• Specify the location of the files in the data_folder argument.

For example, let’s say the files for my database are in the folder /data/mimic-omop/:

/data/mimic-iv-demo/
--- person.parquet
--- visit_occurrence.parquet
--- visit_detail.parquet
--- measurement.parquet

I load them like this.

import_dataset(
    r, d, dataset_id = %dataset_id%, omop_version = "5.4",
    data_source = "disk", data_folder = "/data/mimic-iv-demo/"
)

Loading specific tables

You can choose to import only certain tables from the database using the load_tables argument.

Simply specify the tables to import in a character vector like this:

# Loading only the person, visit_occurrence, visit_detail, and measurement tables
tables <- c("person", "visit_occurrence", "visit_detail", "measurement")

# Adding the load_tables argument in import_dataset
import_dataset(
    r, d, dataset_id = %dataset_id%, omop_version = "5.4",
    data_source = "db", con = con,
    load_tables = tables
)

From the content catalog

You can also install a dataset from the content library.

This will allow you to download the code needed to load data, but only the code.

The data will not be downloaded: access to health data generally requires authentication.

Find the tutorial here.

5 - Create a project

6 - Create a plugin

6.1 - Simple

6.2 - Advanced

7 - Explore

7.1 - Install a component

To get started, go to the “Content Catalog” page, either from the homepage or from the top menu.

By selecting a point on the map, you will see its description (corresponding to the README.md file from the git repository).

Click on the “Show content” button to access the shared content provided by this team.

You can choose the content category from the tabs at the top right of the screen, among:

• Projects
• Plugins
• Data Cleaning Sets
• Datasets

By clicking on a widget, you will access the description of that content.

You can install or update the item simply by clicking on the “Install” or “Update” button.

Once the item is installed, you can access it locally from the corresponding page (Projects page, Datasets page, etc.).

To return to the map, click on “Git repositories” at the top of the screen.

8 - Share