Customize your instance

Most of the data used by the application is retrieved remotely at startup and subsequently updated on a monthly basis.

To prevent data from being loaded on startup and/or recurrently, set the following parameter in the application.properties file:

rdp.settings.cache.enabled=false

You should deploy your RDP instance at least once to have initial data before setting this property and whenever you update the software.

Gene information and GO terms

By default, RDP will retrieve the latest gene information from NCBI, and GO terms from Ontobee. Users genes and GO terms will be updated after a successful update.

Gene information are obtained from NCBI Gene FTP server with URLs stored in the database. You can retrieve these with the following query:

select taxon_id, scientific_name, gene_url from taxon;

For example, the gene_url column for Homo sapiens would contain ftp://ftp.ncbi.nlm.nih.gov/gene/DATA/GENE_INFO/Mammalia/Homo_sapiens.gene_info.gz

Genes' GO term annotations are also obtained from NCBI:

rdp.settings.cache.annotation-file=ftp://ftp.ncbi.nlm.nih.gov/gene/DATA/gene2go.gz

GO terms, on the other hand, are obtained from Ontobee:

rdp.settings.cache.term-file=http://purl.obolibrary.org/obo/go.obo

Taxon

The taxon table is pre-populated during the very first installation of the software, at which time only Human taxon is activated. To enable other taxon, set their active column to 1 in the database.

For example, the following will activate the mouse taxon:

update taxon set active = 1 where taxon_id = 10090;

Every time the new model organisms are added to the application, they will have to be activated in this manner.

Ortholog mapping

There is an ortholog mapping file that is included with the application and will automatically populate the database on startup. The ortholog mappings are based on DIOPT.

The default value points to a classpath resource included within RDP archive:

rdp.settings.cache.ortholog-file=classpath:cache/DIOPT_filtered_data_May2021.gz

It would also be possible to use another ortholog resource, as long as it has the same format. For example, to use the NCBI gene orthologs:

rdp.settings.cache.orthologs-file=ftp://ftp.ncbi.nlm.nih.gov/gene/DATA/gene_orthologs.gz

As with other remotely downloaded files, this would be updated monthly.

Organ systems

Organ systems ontology is based on Uberon multi-species anatomy ontology and updated monthly.

rdp.settings.cache.organ-file=http://purl.obolibrary.org/obo/uberon.obo

Only a select few organ systems are active by default. You can activate more by running the following SQL command with an Uberon identifier of your choice:

update organ_info
set active = true
where uberon_id = '<uberon_id>';

If you activate a non-default organ system, consider adding an icon for it by following the instructions in the Style and static resources section below.

To disable organ systems altogether, set the following in your configuration:

rdp.settings.organs.enabled=false

Loading data from disk

It's also possible to store all the above mentioned info locally, instead of fetching it remotely. The following settings will retrieve all the necessary files relative to the working directory of the Web application:

#this setting relates only to gene info files. Files for all taxons will be stord under gene/
rdp.settings.cache.load-from-disk=true
rdp.settings.cache.gene-files-location=file:genes/

#file for GO ontology
rdp.settings.cache.term-file=file:go.obo
#file for gene GO annotation
rdp.settings.cache.annotation-file=file:gene2go.gz
#file for Uberon anatomy ontology
rdp.settings.cache.organ-file=file:uberon.obo
#location of the provided ortholog file which is stored locally by default
rdp.settings.cache.ortholog-file=file:DIOPT_filtered_data_March2020.txt

With rdp.settings.load-from-disk enabled, the basename from the gene_url (mentioned above) will be used in conjunction with rdp.settings.gene-files-location. For example Homo sapiens taxon would be retrieved from genes/Homo_sapiens.gene_info.gz

International data

In order to access the RDMM shared data system (via the international search), your application must use HTTPS. If you do not have HTTPS setup for you domain, you can consult the following guides on how to set it up:

Registries can access each other public data by enabling rdp.settings.isearch.enabled and setting up the rdp.settings.isearch.apis in the application.properties file to contain a comma-delimited list of partner registry URLs.

rdp.settings.isearch.enabled=true
rdp.settings.isearch.apis=https://register.rare-diseases-catalyst-network.ca/

A secure communication between different instances is achieved using a special search token which gets appended to remote queries. Currently, there is one token that is used by all partner registries.

The token can be generated using OpenSSL: openssl rand -base64 24 and it would look something like this: hrol3Y4z2OE0ayK227i8oHTLDjPtRfb4 (this is just an example). Once generated, this token is shared securely with partner registries.

The token is added to the application.properties file in the following way:

rdp.settings.isearch.search-token=hrol3Y4z2OE0ayK227i8oHTLDjPtRfb4

On the receiving side, the partner registry must create a user that is used to perform privileged searches.

This is usually done by creating a remote administrative account:

insert into user ( email, enabled, password, privacy_level, description, last_name, name, shared, hide_genelist, contact_email_verified)
values(concat(rand(),'@rdmm.com'), 0, md5(rand()), 0, 'remote admin profile', '', '', false, false, false);
insert into user_role (user_id,role_id) values ((select max(user_id) from user), 1);
insert into user_role (user_id,role_id) values ((select max(user_id) from user), 2);
select max(user_id) from user;

Let's assume that the created user's ID was 522. The partner would then add the token to its rdp.settings.isearch.auth-tokens setting along any existing tokens.

rdp.settings.isearch.user-id=522
rdp.settings.isearch.auth-tokens=jLb22QZzsaT6/w3xwDHBObmZPypJgXfb,hrol3Y4z2OE0ayK227i8oHTLDjPtRfb4

This allows you to query private data from the partner registry when logged in as an administrator on your own registry.

Out of network partners

To share data with partners outside the RDMM network that may use a different search token or no token at all, you may use either the auth or noauth query parameter in the rdp.settings.isearch.apis configuration.

To deal with non-admin partners, specify the noauth query parameter, which will prevent leakage of the remote search token from administrative accounts.

rdp.settings.isearch.apis=https://register.rare-diseases-catalyst-network.ca?noauth

If a partner uses a different search token, you may use the auth query parameter to specify that token.

rdp.settings.isearch.apis=https://register.rare-diseases-catalyst-network.ca?auth=jLb22QZzsaT6/w3xwDHBObmZPypJgXfb

Gene Tiers

Users' genes are categorized in tiers based on their familiarity and experience with the gene. This is explained in detail in the users' documentation and FAQs. Users add TIER1 and TIER2 genes directly, while TIER3 genes are inferred from GO term associations.

To enable only TIER1 and TIER2, and thus disabling GO terms-related features, add the following to your configuration:

rdp.settings.enabled-tiers=TIER1,TIER2

Researcher position

Researcher positions can be enabled or disabled by setting the rdp.settings.profile.enabled-researcher-positions to a list of desired values.

For the moment, only one value is defined PRINCIPAL_INVESTIGATOR.

rdp.settings.profile.enabled-researcher-positions=PRINCIPAL_INVESTIGATOR

To disable this feature, just leave the setting blank.

Researcher categories

Researcher categories can be enabled or disabled by setting the rdp.settings.profile.enabled-researcher-categories to a list of desired values.

rdp.settings.profile.enabled-researcher-categories=IN_SILICO,IN_VIVO

The available values are:

  • IN_VIVO
  • IN_VITRO_BIOCHEMICAL
  • IN_VITRO_CELLS
  • IN_VITRO_STRUCTURAL
  • IN_SILICO
  • OTHER

To disable this feature, just leave the setting blank.

Privacy levels

Privacy levels can be selectively enabled for user profiles and genes.

rdp.settings.privacy.enabled-levels=PUBLIC,SHARED,PRIVATE
rdp.settings.privacy.enabled-gene-levels=PUBLIC,SHARED,PRIVATE

Note that any value enabled for genes that is not also enabled for profiles will be ignored.

To allow user to modify the privacy level of their profile and individual genes, set the following properties:

rdp.settings.privacy.customizable-level=true
rdp.settings.privacy.customizable-gene-level=true

To disable gene-level privacy, set rdp.settings.privacy.customizable-gene-level to false and leave the rdp.settings.privacy.enabled-gene-levels blank.

Anonymized search results

By default, search results that are not accessible to a given user are anonymized. All identifiable information is stripped from the model and numerical identifiers are randomized in such a way that it becomes impossible to relate users or genes from different search.

This feature can be disabled by setting the following configuration key to false:

rdp.settings.privacy.enable-anonymized-search-results=false

Customizing the application's messages

Some text displayed in RDP can be customized and/or internationalized. To do so, copy a provided messages.properties file in the working directory of the Web application and edit it. The file is found in messages.properties

You can use suffixed like messages_en_CA.properties for region-specific customization.

Note that application-prod.properties and login.properties are also used for messages for backward compatibility. New and existing messages should be moved to messages.properties.

FAQ

The FAQs can also be customized in a similar way by editing the provided faq.properties file and setting up the rdp.settings.faq-file parameter:

rdp.settings.faq-file=file:faq.properties

In the file, each entry requires two parts: rdp.faq.questions.<q_key> and rdp.faq.answers.<q_key> which hold the question and the corresponding answer, respectively.

rdp.faq.questions.<q_key>=A relevant question.
rdp.faq.answers.<q_key>=A plausible answer.

The provided default file can be found in faq.properties.

Terms of service and privacy policy

The terms of service and privacy policy can be added to the messages.properties by editing the following entries:

rdp.terms-of-service=Your terms of service
rdp.privacy-policy=Your privacy policy

Style and static resources

Static resources can be selectively replaced by including a search directory for Spring static resources.

spring.resources.static-locations=file:static/,classpath:/static/

Here's the list of paths that can be adjusted using the above setting:

static/
    css/
        common.css # general pages
        login.css  # login-like pages (i.e. registration, reset password, etc.)
    images/
        model-organisms/
            <taxon_id>.svg
        organs/
            <uberon_id>.svg
        researcher-categories/
            <researcher_category_id>.svg
        brand.png
        favicon-16x16.png
        favicon-32x32.png
        header.jpg

We strongly recommend against overriding JavaScript files as it could break functionalities of the website.

Building from source

You can customize RDP by editing the publicly available source code and packaging the JAR archive yourself.

git clone https://github.com/PavlidisLab/rgr.git
cd rgr/
# edit what you want...
./mvnw package

The new build will be available in the target directory.