Installation of the R package

The package can be installed with the remotes library:

remotes::install_github("arsenij-ust/cbpManager")

cbpManager will use the validateData.py script from cBioPortal for Cancer Genomics inside of the application, which allows the user to validate the created files. Therefore, a conda environment will be installed. To prevent long loading times during the application usage, we can setup the conda environment with the function cbpManager::setupConda_cbpManager() before launch.

After successful installation, the application is started with the following command (a browser window/ RStudio viewer with the application should open):

cbpManager::cbpManager()

The installation was successful if the application starts working.

A study to be loaded in cBioPortal can basically consist of a directory where all the data files are located (see here). It is common to store the single study directories in one directory called e.g. “study”. If you already have a cBioPortal instance installed and such a folder containing study subfolders, you should provide the path when starting the application:

cbpManager::cbpManager(
  studyDir="path/to/study", 
  logDir="path/to/logingDirectory"
)

Now you can select your already existing studies in the dropdown menu.

Optionally, you can provide further parameters to cbpManager::cbpManager() function that are used by shiny::runApp, e.g. host or port.

Attention: If you do not pass a path to the application before starting it, the “study” directory in the installed R package will be used by default. If the package is reinstalled at a later time, all studies and files in the folder will be lost. Thus it is advisable to always pass a path (e.g. of the working directory).

Docker deployment

The advantage of running cbpManager as a Docker container is the system integration in a larger context and allows the access for multiple users. In addition, you can integrate authentication with ShinyProxy. More information about installing cbpManager using Docker can be found on this page LINK.

File naming convention

If cbpManager should recognize files of a study, the files should be named as following:

• data_clinical_patient.txt (Clinical Data)

• data_clinical_sample.txt (Clinical Data)

• data_mutations_extended.txt (Mutation Data)

• meta_study.txt (Cancer Study)

• meta_clinical_patient.txt (Clinical Data)

• meta_clinical_sample.txt (Clinical Data)

• meta_mutations_extended.txt (Mutation Data)

Optional files:

• data_timeline_surgery.txt / meta_timeline_surgery.txt
• data_timeline_status.txt / meta_timeline_status.txt
• data_timeline_treatment.txt / meta_timeline_treatment.txt

Further custom timeline tracks should be named:

e.g. data_timeline_<custom>.txt / meta_timeline_<custom>.txt

For further details see File Formats and the ‘testpatient’ study in this package under ‘inst/study/’.

Editing studies:

On the “Study Metadata” page, new studies can be created and existing studies can be loaded.

Editing patient data:

The “Patient” page is used to edit clinical patient data. In the upper area, it has a “Description” box containing important information on filling in the patient data as well as instructions for handling, and a “Sample from cBioPortal” box with an exemplary representation of the patient data in cBioPortal (both boxes are collapsed in the following image for better clarity). The “Patient manager” area contains several function buttons and a central table with the patient information. The first three light blue lines must contain a short, long name and the data type of a column. Each additional line defines a patient.

Editing sample data:

The table of sampled data on the “Sample” page is similar to the table of patient data. However, here the columns PATIENT_ID and SAMPLE_ID are mandatory. The operation of editing the table is also analogous to that of patients.

Warning: To create a sample (row) and assign it to a patient, patients must be created first.

Mutation data (MAF):

The “Mutations” page offers the user the possibility to upload mutation annotation format (MAF) files. If the study already contains mutation data, the content of the uploaded MAF file will be concatenated to the already existing data by clicking on the Add uploaded data to existing mutation data button. Columns of the uploaded file, that are new and not present in the existing data, will be added. Columns with similar names between the uploaded file and the already existing mutation data will be merged together. The MAF file must meet certain requirements, i.e. contain specific columns (see link). Similarly to the previous tabs, the user can add, edit, and delete single mutations, and add or delete columns of the table at the bottom of the page. As always, saving is required to make the changes permanent.

Editing timelines:

The “Timelines” page offers the possibility to edit the timeline tracks “Treatment”, “Surgery” and “Status”. Furthermore, it is possible to create and edit user-defined timeline tracks.

Since cBioPortal uses the number of days since the initial diagnosis instead of a specific date for the start or end of a timeline event, one would have to specify the initial diagnosis date for each event as well. This is repetitive and time-consuming in total, which is why we decided to create a patient first diagnosis date table as an intermediate step. So before you can add timeline events to a timeline track, you have to assign a diagnosis date to the patient. This is done in the box Add date of the first diagnosis to a Patient ID. In the timeline tracks you only have to select the patient ID to which this event belongs and the cbpManager calculates the number of days until the given date automatically.

The three timeline tracks “Treatment”, “Surgery” and “Status” are shown in the tabs:

To create custom timeline tracks, you must first specify the name of the timeline track and define whether the event has a time span (timeline) or is a point event (timepoint). This is relevant because timeline events have a start and stop date and timepoint events only need to have a start date. To edit a timeline track, you should select it from the drop-down menu and click Edit track to confirm the selection. The data of the timeline track will be displayed in the table below. Again, each change must be saved with Save to make it persistent.

Manage resources data:

In the “Resources” tab, you can add additional resources to patients, samples and studies. It generates in cBioPortal a hyperlink and a tab containing the web based resource, e.g. another webpage. With this principle you can add pdf, txt, png resources or webpages to your study.

At first, we need to define a resource before adding a URL to a specific sample or patient. The first table creates the necessary resource definition file. The resource definition file should follow this format, it has three required columns:

• RESOURCE_ID: a unique resource ID. This field allows only numbers, letters, points, underscores and hyphens.
• DISPLAY_NAME: a display name for resources.
• RESOURCE_TYPE: resource type for resources. It describes to which part of the study this resource is to be assigned and must be ‘SAMPLE’, ‘PATIENT’ or ‘STUDY’.

After we defined a resource, we can add a URL link to the study, a specific patient, or a specific sample. E.g. we defined a resource with the RESOURCE_ID ‘test_resource’ and the RESOURCE_TYPE ‘PATIENT’, then we go the the ‘Patients’ tabpanel in this area, click on the ‘Add’ button, select an existing PATIENT_ID, select our recource with the ID ‘test_resource’, and add a URL.

Validating created study

The tab “Validation” allows the user quickly validate the created or modified study files. The validation checks whether the study is suitable for the upload in cBioPortal. In background the cBioPortal validateData.py script is used.

The report generation is triggered by the Validate button. After, the report can be downloaded.