tripal / chado_linker_fields

Tripal fields to display content linked to a different content type through linker tables

Chado Linker Fields Documentation

Tripal fields to display content linked to a different content type through linker tables

This module provides fields for Tripal 7.x-3.10 or later to display linked content. Please be aware that this module will not be compatible with Tripal versions 7.x-3.9 or earlier.

Background

A number of content types have chado linker tables that define relationships between two different content types. For example, in the core Tripal module there is a field named chado_linker__contact that can be used, for example, to add contact information on a feature, such as a gene. The correspondence information is stored in the chado table feature_contact. For example, this table might contain these records:

 feature_contact_id | feature_id | contact_id 
--------------------+------------+------------
                  1 |          1 |          3
                  2 |          2 |          3

And the linked contact could appear on a gene (feature) page as in this example

Fields Provided by This Module

This module provides linker fields for the following content types

Linker Field Name	Controlled Vocabulary Term
chado_linker__analysis	NCIT:C25391 (Analysis)
chado_linker__assay	NCIT:C60819 (Assay)
chado_linker__biomaterial	NCIT:C43376 (Biologically-Derived Material)
chado_linker__contact (existing)	local:contact
chado_linker__feature	NCIT:C73619 (Feature)
chado_linker__featuremap	EDAM data:1274 (map)
chado_linker__organism	NCIT:C14250 (Organism)
chado_linker__project	NCIT:C47885 (Project)
chado_linker__stock	NCIT:C48288 (Stock)
chado_linker__study	NCIT:C63536 (Study)

These fields can be used on any content type, however there must be a corresponding chado linker table, with a name based on the two content types. For example, to link a stock to a project, the table can be named either project_stock or stock_project. If Tripal does not provided a needed linker table, you can create a custom chado table yourself to store the linking information. See the Tripal Documentation for more information on creating custom tables.

How to add a field to a content type

These fields can be added to any content with an appropriate linker table.

On your site's admin menu, navigate to

Structure → Tripal content types

or navigate directly to

/admin/structure/bio_data.

On a content type click on manage fields and then click on + Check for new fields If a suitable linker table exists, a corresponding linker field will be added to the content type. For example, on project content type you should see this result:

You can then select the "MANAGE DISPLAY" tab, enable the fields if they are disabled, and configure where you would like the new fields displayed.

Configuration of Field Settings

On your site's admin menu, navigate to

Tripal → Data Storage → Chado → Field Settings

or navigate directly to

/admin/tripal/storage/chado/field_settings

The configuration form provides two settings:

Maximum records to display

This setting is used to configure when a field converts to a summary view. This is necessary when the number of records to display is too large for your site to handle. For example, a Genome Assembly may be linked to all of the gene predictions in that assembly, which will likely be tens of thousands of genes. Displaying this many records, even if a pager is used, will likely overwhelm any Tripal site. In this case a summary view is returned.

Example of a summary view on an analysis (Gene Prediction) page:

Maximum field height

This setting is used to configure the maximum height of a single record displayed by a field. For example, if linking an analysis to an organism, the analysis record may have an extensive description, and if multiple analyses are linked, the resulting page that is displayed may be unwieldy. When the content exceeds the specified height, a scrollbar will be provided.

Example of an analysis with scroll bar on a project page:

Existing Linker Tables

Core Tripal provides the following linker tables compatible with the fields in this module. Other modules may define additional linker tables. Please note that a linker table must have a primary key to be usable by these fields. For example, the analysis_organism materialized view in core Tripal does not have a primary key, so it will not be recognized by these linker fields. However, the tripal_eutils module does define an organism_analysis custom table, which can be used.

analysis_pub
analysisfeature
assay_biomaterial
assay_project
cell_line_feature
cell_line_library
cell_line_pub
feature_contact
featuremap_contact
featuremap_organism
featuremap_pub
library_contact
library_feature
library_pub
organism_pub
phylotree_pub
project_analysis
project_contact
project_feature
project_pub
project_stock
stock_feature
stock_featuremap
stock_library
stock_pub
stockcollection_stock
study_assay

chado_linker_fields's Issues

chado_linker__organism warnings

There are some bugs in the chado_linker__organism field that look like this showing up in the log

Warning: Undefined variable $abbreviation_name_term in chado_linker__organism->load() (line 218 of .../sites/all/modules/chado_linker_fields/includes/TripalFields/chado_linker__organism/chado_linker__organism.inc).
or
Warning: Undefined array key "local:abbreviation" in chado_linker__organism_formatter->view() (line 67 of .../sites/all/modules/chado_linker_fields/includes/TripalFields/chado_linker__organism/chado_linker__organism_formatter.inc).

These derive from incorrect variables in the load() function.
 
Fix with pull request #3

Update, that PR was entirely wrong 😱. Reverted and made the correct fix with pull request #4

Create module chado_linker_fields

This issue is to document the creation of this module.

This module has been created in response to this issue in the Tripal repository tripal/tripal#1318 and the related pull request tripal/tripal#1319 - and there was an earlier discussion about analysis-project links in tripal/tripal#804

So some background, a fair number of content types have chado linker tables that define relationships between two different content types. For example, in the core Tripal module there is a field named chado_linker__contact that can be used, for example, to add contact information on a feature, such as a gene. The correspondence information is stored in the chado table feature_contact. Well the question was raised as to why aren't there linker fields for all of the major content types. And the answer was basically that no one wanted them enough to take the (significant) amount of time to create them. Well, some people did, but they were implemented in other modules, for example the sep__biological_sample field (Biomaterial Browser) in the tripal_biomaterial module.

Alas, @dsenalik wanted them enough, and began the arduous task.

Complications arose, some modules defined their own linker tables, sure that's great, but they conflicted with core tripal tables. For example, mainlab tripal defines stock_project which is in conflict with the core tripal project_stock table. Nasty special-case code tries to favor the core Tripal tables in these cases.

Another issue that caused chaos was that some of these linker fields made pages unviewable, because there were too many links. For example, if all the genes (features) in a gene prediction analysis are linked to the analysis, you have tens of thousands of links. Any Tripal site is going to roll over and play dead in such a situation. To handle cases of large numbers of links, the fields implement a pager, but when there are just too many records to display without the site timing out, the fields will switch over to a Summary View when the total number of records exceeds a configurable limit, defaulting to 200 at the moment.

And what about a Tripal 4 version? The plan is for these fields to be in core Tripal, or the new genome module, or other module, as appropriate. For now there is tripal/tripal#1381