Expanding Tripal 4 Fields documentation

[laceysanderson]

This issue is a place for everyone working on fields to drop tips, tricks and bits of documentation that we can later incorporate into the official docs at https://tripaldoc.readthedocs.io/en/latest/.

[laceysanderson]

Note: You can get the mapping of terms to chado columns in your site by navigating to http://localhost:9000/admin/tripal/storage/chado/terms or Admin > Tripal > Data Storage > Chado > Chado Term Mapping

This is good for looking up terms you want to use in your field when referring to specific columns. You can also look this up programatically but I can't remember the code off the top of my head. @spficklin can you add that here?

[srobb1]

Just in case, here is query to list all cvterms, their cv name, and accession

SELECT cv.name, dbx.accession, cvt.name  
FROM cvterm cvt, cv, dbxref dbx 
WHERE cvt.cv_id = cv.cv_id and cvt.dbxref_id = dbx.dbxref_id ;

example output:

name	accession	name
null	local:null	null
chado_properties	chado_properties:version	version
germplasm_ontology	0000044	accession
germplasm_ontology	0000255	generated germplasm
germplasm_ontology	0000029	cultivar

[dsenalik]

Extend the example defaultFieldSettings() to include a CV term to show how that is done for a field that has a constant term, e.g.

  /**
   * {@inheritdoc}
   */
  public static function defaultFieldSettings() {
    $settings = parent::defaultFieldSettings();
    $settings['termIdSpace'] = 'local';
    $settings['termAccession'] = 'contact';
    return $settings;
  }

oops, to match the example style, it should be

    $settings = [];
    $settings['termIdSpace'] = 'local';
    $settings['termAccession'] = 'contact';
    return $settings + parent::defaultFieldSettings();

[dsenalik]

Formatter Token Strings (After PR tripal/tripal#1697 )

For fields that may want to present more than one column from a table, you can easily implement a token string in the formatter settings. A form element and validation can be provided automatically just by including a valid_tokens annotation at the top of your formatter. For example:

/**
 * Plugin implementation of default Tripal contact formatter.
 *
 * @FieldFormatter(
 *   id = "chado_contact_formatter_default",
 *   label = @Translation("Chado contact formatter"),
 *   description = @Translation("A chado contact formatter"),
 *   field_types = {
 *     "chado_contact_default"
 *   },
 *   valid_tokens = {
 *     "[name]",
 *     "[description]",
 *     "[type]",
 *   },
 * )
 */

You would then implement code in your formatter similar to this

    $list = [];
    $token_string = $this->getSetting('token_string');

    foreach ($items as $delta => $item) {
      $values = [
        'name' => $item->get('contact_name')->getString(),
        'description' => $item->get('contact_description')->getString(),
        'type' => $item->get('contact_type')->getString(),
      ];

      // Substitute values in token string to generate displayed string.
      $displayed_string = $token_string;
      foreach ($values as $key => $value) {
        $displayed_string = preg_replace("/\[$key\]/", $value, $displayed_string);
      }
      $list[$delta] = $displayed_string;
    }

[dsenalik]

Content types currently present by default in Tripal 4

Group	Content Type	Base Table	CV Term	Term name
General	Analysis	analysis	operation:2945	Analysis
General	Contact	contact	NCIT:C47954	Communication Contact
General	Organism	organism	OBI:0100026	organism
General	Project	project	NCIT:C47885	Project
General	Protocol	protocol	sep:00101	Protocol
General	Publication	pub	TPUB:0000002	Publication
General	Study	study	SIO:001066	study
Expression	Biological Sample	biomaterial	sep:00195	biological sample
Expression	Assay	assay	OBI:0000070	assay
Expression	Array Design	arraydesign	EFO:0000269	Assay Design
Genetic	Genetic Map	featuremap	data:1278	Genetic map
Genetic	QTL	feature	SO:0000771	QTL
Genetic	Sequence Variant	feature	SO:0001060	sequence_variant
Genetic	Genetic Marker	feature	SO:0001645	genetic_marker
Genetic	Heritable Phenotypic Marker	feature	SO:0001500	heritable_phenotypic_marker
Genomic	Gene	feature	SO:0000704	gene
Genomic	mRNA	feature	SO:0000234	mRNA
Genomic	Phylogenetic Tree	phylotree	data:0872	Phylogenetic tree
Genomic	Physical Map	featuremap	data:1280	Physical Map
Genomic	DNA Library	library	NCIT:C16223	DNA Library
Genomic	Genome Assembly	analysis	operation:0525	Genome assembly
Genomic	Genome Annotation	analysis	operation:0362	Genome annotation
Genomic	Genome Project	project	local:Genome Project	Genome Project
Germplasm	Germplasm Accession	stock	CO_010:0000044	accession
Germplasm	Breeding Cross	stock	CO_010:0000255	generated germplasm
Germplasm	Germplasm Variety	stock	CO_010:0000029	cultivar
Germplasm	Recombinant Inbred Line	stock	CO_010:0000162	414 inbred line

Tables with more than one content type

Table	Number
analysis	3
feature	6
featuremap	2
project	2
stock	4

[dsenalik]

Matrix of all potential links between content types.
Arrows ↗ or ↙ indicate when the subject table has a column that directly references the object table as a foreign key.
🔺 indicates a not null constraint.
🔗 indicates bidirectional links made through linker tables present in core tripal.

TABLE	analysis	arraydesign	assay	biomaterial	contact	feature	featuremap	library	organism	phylotree	project	protocol	pub	stock	study
analysis (×3)						🔗*			🔗	↙	🔗*		🔗
arraydesign			↙🔺		↗🔺§							↗
assay		↗ 🔺		🔗*	↗🔺§						🔗	↗			🔗
biomaterial			🔗*		↗§				↗§
contact		↙🔺§	↙🔺§	↙§		🔗		🔗			🔗				↙🔺
feature (×6)	🔗*				🔗			🔗	↗🔺		🔗		🔗	🔗*
featuremap													🔗	🔗*
library					🔗	🔗			↗🔺				🔗	🔗
organism	🔗			↙§		↙🔺		↙🔺					🔗	↙
phylotree	↗												🔗
project	🔗*		🔗		🔗	🔗							🔗	🔗
protocol		↙	↙										↗
pub	🔗					🔗	🔗	🔗	🔗	🔗	🔗	↙		🔗	↙
stock (×4)						🔗*	🔗*	🔗	↗		🔗		🔗
study			🔗		↗🔺								↗

*These linker tables have additional columns.

Table	Column	Nullable	Default Value
analysisfeature	rawscore	yes
	normscore	yes
	significance	yes
	identity	yes
assay_biomaterial	channel_id	yes
	rank	not null	0
project_analysis	rank	yes
stock_feature	type_id	not null
	rank	not null	0
stock_featuremap	type_id	yes

§Foreign key names are different than the object table primary key.

arraydesign FOREIGN KEY (manufacturer_id) REFERENCES contact(contact_id)
assay FOREIGN KEY (operator_id) REFERENCES contact(contact_id)
biomaterial FOREIGN KEY (biosourceprovider_id) REFERENCES contact(contact_id)
biomaterial FOREIGN KEY (taxon_id) REFERENCES organism(organism_id)