Customize your instance

This section contains instruction to customize your RDP registry.

Allowed email providers (new in 1.5.8)

You may restrict which email providers can be used for creating new accounts by specifying a list or a file containing allowed domains. Matches are performed in a case-insensitive manner. Only printable ASCII characters are allowed.

rdp.settings.allowed-email-domains=example.com
rdp.settings.allowed-email-domains-file=file:swot.txt
rdp.settings.allowed-email-domains-file-refresh-delay=3600

The default refresh delay is set to one hour. Disable it by setting it to an empty value. A value of 0 will cause a refresh on every validation.

This feature is disabled by default.

Internationalized domain names

To use internationalized domain names in email addresses, add their Punycode to the list or file and set the following setting:

rdp.settings.allow-internationalized-email-domains=true

For example, to allow users from universität.example.com to register, add xn--universitt-y5a.example.com to the file.

reCAPTCHA (new in 1.5.8)

RDP supports reCAPTCHA v2 to mitigate the registration of accounts by bots. To enable it, add the reCAPTCHA token and secret to your configuration.

rdp.site.recaptcha-token=mytoken
rdp.site.recaptcha-secret=mysecret

This feature is disabled by default.

Cached data

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.

The following sections will cover in details individual data sources that can be imported in your registry.

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

gene2go associations will only be populated for active taxa (new in 1.5.8).

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

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 new model systems are added to the application, they will have to be activated in this manner.

GO term recommendation

Users can receive recommended terms based on the TIER1 and TIER2 genes they have added to their profiles.

The recommendation algorithm works as follows:

  1. Retrieve GO terms associated to all TIER1 and TIER2 genes
  2. Retrieve all the descendants of these terms
  3. For each term, compute how many TIER1 or TIER2 genes they are associated either directly or indirectly via their descendants
  4. Keep terms that are not already on the user profile and that mention at least 2 TIER1 or TIER2 genes
  5. Exclude terms with more than 50 associated genes
  6. Retain terms that have at least one novel gene that is not on the user's profile
  7. Retain most specific terms if a given term and its descendant is recommended

You can adjust the number of overlapping TIER1 or TIER2 genes and the maximum size of a GO term by setting the following:

rdp.settings.go-term-min-overlap=2 # new in 1.5.8
rdp.settings.go-term-size-limit=50

Customizing taxon appearance (new in 1.5.5)

By default, taxon are rendered using the common name in title case. The only exception is for Homo sapiens which renders as "Human / Other". You may override this by setting the following entries in the messages.properties file, replacing {taxonId} by the taxon ID of your choice:

rdp.taxa.{taxonId}.title=

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

If you change the source, you should also adjust the text that appears in the user documentation in your messages.properties file.

rdp.cache.ortholog-source-description=The ortholog mapping is based on <a href="https://www.flyrnai.org/cgi-bin/DRSC_orthologs_v09.pl" target="_blank" rel="noopener">DIOPT version 9</a> \
results, filtered for score >5, either best forward or reverse match and Rank = "high" or Rank = "moderate".

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

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.

Profile categories

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.

Human organ systems

Note

As of 1.5.0, we recommend that you use an additional profile category to add Human organ systems to the user profile.

The Human 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 enable human organ systems, set the following in your configuration:

rdp.settings.organs.enabled=true

Additional profile categories

Support for additional profile categories, including ontologies based on the OBO format, was introduced in the 1.5 series as a way to make the software more flexible and customizable.

Most of the administration of profile categories can be done under the /admin/ontologies endpoint, i.e. Manage Profile Categories page.

To disable this feature altogether, set the following in your application.properties:

rdp.settings.ontologies.enabled=false

Create a simple category

On the Manage Profile Categories page, you may create a simple category. You must provide a name and at most 20 terms. Each term should have a unique name.

Interface for creating a simple category.

The terms can be organized in groups using grouping terms ("is grouping?"). Simple categories support only one grouping level. Terms are grouped under the closest preceding grouping term. Groups must not be empty. Grouping terms will not be used for searching the registry.

Example of a simple category with grouping terms.

If no grouping is used, terms are displayed in a linear fashion.

Example of a simple category displayed in a linear fashion.

A term can also be associated with an icon. If a category has a mixture of terms with and without icons, those without will use a SVG textual icon fallback.

Example of a category with a mixture of terms with and without icons.

Custom icons

To use custom icons, you must first enable custom style and static resources by expanding the search path for static assets. Then, icons can be deposited under static/images/ontologies/{ontologyName}/{termName}.svg.

Only SVG is supported at this time.

Create an ontology category

More complex categories are created using ontologies. The ontologies need to be in an OBO format. There are two ways of importing an ontology: using an URL or a file.

Interfae for importing an ontology in OBO format.

Once imported, you can either activate all ontology terms or a subset of terms by activating a subtree. Note that obsolete terms are never activated automatically.

Managing profile categories

Once created, a new profile category will be listed in the table at the bottom of the Manage Profile Categories page. The table uses badges to display if the category is active or not, the number of active terms and if the category is used as a filter for Gene Search.

The order of categories, as they are displayed on the Profile and Search pages, can be modified using the arrows next to the category name.

Table of available profile categories.

Managing a specific profile category

A specific profile category can be managed on its Manage Profile Category page, which is accessed by clicking on the "Manage" button in the table shown above.

The page lists some basic stats at the very top and provides few action buttons:

Actions available for simple categories.

  • "Deactivate" (or "Deactivate All Terms" in the case of an ontology category): this will remove the category from the Profile and Search pages. This action is reversible, as the category can be easily re-activated. This action is recommended in cases where a category cannot be deleted because it has already been used by some users.

  • Update from "source": Update the ontology category using the original URL (if available)

  • Download as OBO: Download the category as an OBO file

The number of used terms indicate how many terms in the ontology have been associated with associated with users.

In the Edit window on the Manage Profile Category page, you can add a definition/description of the category, which is used in a tooltip on the Profile Page. You can also specify if this category will be used as a filter on the Gene Search page. While all active categories will be available on the Researcher Search page, only categories that have " Available for gene search?" checked will be displayed on the Gene Search page.

Interface for editing the properties of an ontology.

The name and source URL are not modifiable from the admin section, but can be edited directly in the database if needed.

Activating a subtree

Ontologies often contain a large number of terms and some of these terms might not be relevant to the users of your registry. You can chose which parts of an ontology will be used in the registry by activating specific subtrees. Subtrees can be activated once the ontology is imported, but can also be activated or deactivated later using the Manage Profile Category pages.

To activate a subtree, enter its root term (or use autocomplete) in the Activate Subtree window.

Example of use of the term autocomplete feature to find a subtree to activate.

If all possible subtrees are already active, a warning will be displayed instead.

Warning displayed when all subtrees are already active.

Once activated, the term will then appear in the list of active subtrees:

Interface for displaying active subtrees.

You may deactivate subtree from the table of active subtrees by clicking on "Deactivate".

The active subtrees get a special treatment when the ontology is updated to ensure that newly added sub-terms are always active.

Deleting a category

Deleting a category is irreversible and is only possible if it is not being used (there are no users that are associated with any of the category terms). If your ontology is being used, consider deactivating it instead.

Interface for deleting an ontology.

If an ontology has at least one user, the following message will be displayed instead:

Custom titles and definitions

The content of messages.properties has precedence over the values stored in the database for titles and definitions of categories and terms. This allows you to override values that are imported from an OBO source as you see fit.

rdp.ontologies.{ontologyName}.title=
rdp.ontologies.{ontologyName}.definition=
rdp.ontologies.{ontologyName}.terms.{termName}.title=
rdp.ontologies.{ontologyName}.terms.{termName}.definition=

If your ontology/category is based on a PURL source, its name will be rendered un uppercase. For example, "uberon" from http://purl.obolibrary.org/obo/uberon.obo will be displayed as "UBERON". You may override this by setting a custom title as described above.

Note that we provide defaults for Reactome in the JAR package, so you must use custom messages for overriding those values. A warning will be displayed in the admin section if this is the case.

Example of a category whose definition cannot be edited from the admin section.

Read more about configuring messages in Customizing the application messages section of this page.

Resolving external URLs

By default, ontologies and terms are resolved from OLS. Reactome pathways get a special treatment with the ReactomeResolver. You may override this for a different resolver such as Ontobee.

rdp.settings.ontology.default-resolver=ubc.pavlab.rdp.ontology.resolvers.OntobeeResolver

If you want to use a different source, you can provide a custom implementation of the OntologyResolver interface or ask us by opening an issue on the RDP GitHub repository.

Reactome Pathways

Reactome Pathways are treated in a slightly different way when it comes to loading and updating terms.

Under /admin/ontologies, you can import the Reactome Pathways category with a single click. The initial import will download pathways and update term definitions.

Interface for importing Reactome Pathways.

The Reactome Pathways category has two additional actions for updating its terms and definitions.

Actions exclusive to the Reactome Pathways category.

By default, Reactome Pathways use reactome as ontology name. This can be adjusted by setting rdp.settings.ontologies.reactome-ontology-name in your configuration.

The various Reactome-related configuration should be left largely untouched. You can use static files by downloading them and changing the URL scheme to file:.

rdp.settings.ontology.reactome-pathways-file=file:ReactomePathways.txt
rdp.settings.ontology.reactome-pathways-hierarchy-file=file:ReactomePathwaysRelation.txt
rdp.settings.ontology.reactome-stable-identifiers-file=file:reactome_stable_ids.txt

Reactome Pathways are updated at the same frequency as ontology terms. The update is performed in two stages: first the pathways are updated and then definitions are retrieved from the Reactome Content Service API.

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

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.

With an administrator account, you can refresh messages from the main menu without restarting the registry.

Menu used to refresh the messages.

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.keys=<q_key>
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.

Ordering FAQ entries

Note

New in 1.5.4

he rdp.faq.keys FAQ setting can be used to customize the ordering and appearance of FAQ entries. If the setting is left unset, the default will be to arrange FAQ questions in alphabetic order of their keys.

Translating FAQ entries

Note

New in 1.5.4

The FAQ messages can now be translated by reusing the rdp.faq.questions.<q_key> and rdp.faq.answers.<q_key> as codes for the messages.properties file.

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

Theme color

To use a custom theme color, set the following property in your configuration:

rdp.site.theme-color=#ffffff

The theme color is used to recolor certain browsers and provide a more unified user experience.

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/
    images/
        organs/
            <uberon_id>.svg
        researcher-categories/
            <researcher_category_id>.svg
        ontologies/
            {ontologyName}/
                {termName}.svg
        brand.png
        favicon-16x16.png
        favicon-32x32.png
        header.jpg

To customize static CSS and JavaScript assets, you have to build from sources.

Building from source

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

To build from sources, you will need a working version of Node.js installed as well as a Java 8+ JDK.

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

The new build will be available in the target directory.

Editing assets

CSS and JavaScript assets are bundled with Webpack. You may edit the files found under src/main/resources/css and src/main/resources/js and then issue a ./mvnw package command to rebuild the JAR archive.

Alternatively, you can run npm directly:

cd src/main/resources
npm run build # or 'watch' to build continuously