Difference between revisions of "Chado Schema Documentation HOWTO"

From GMOD
Jump to: navigation, search
m (→‎Module and Table Documentation)
m
Line 2: Line 2:
  
 
The [[Chado]] schema documentation on this wiki is a mixture of generated content and material directly entered by GMOD users into this wiki.  The generated part of the documentation consists of the table definitions that are included on the [[Template:ChadoModules|Chado module pages]] and on the [[Chado Tables]] page, listing all the tables in Chado.
 
The [[Chado]] schema documentation on this wiki is a mixture of generated content and material directly entered by GMOD users into this wiki.  The generated part of the documentation consists of the table definitions that are included on the [[Template:ChadoModules|Chado module pages]] and on the [[Chado Tables]] page, listing all the tables in Chado.
−
 
−
== Module and Table Documentation ==
 
  
 
All of the table descriptions on [[Template:ChadoModules|Chado module pages]] and the [[Chado Tables]] page are generated every time their is a new release of Chado.  The column and table details, including comments, come from the [[PostgreSQL]] data dictionary.
 
All of the table descriptions on [[Template:ChadoModules|Chado module pages]] and the [[Chado Tables]] page are generated every time their is a new release of Chado.  The column and table details, including comments, come from the [[PostgreSQL]] data dictionary.
  
−
=== Showing and Linking to Chado Schema Documentation ===
+
== Using Module and Table Documentation ==
 +
 
 +
This section describes how to ''use'' the Chado Schema Documentation when updating/creating content on this wiki.
 +
 
 +
=== Showing a Table Description ===
  
−
==== Showing a Table Description ====
 
 
To show the information about any table, use the ''Chado Table Template'' for that table:
 
To show the information about any table, use the ''Chado Table Template'' for that table:
 
   <nowiki>{{ChadoTable_</nowiki>''tablename''<nowiki>}}</nowiki>
 
   <nowiki>{{ChadoTable_</nowiki>''tablename''<nowiki>}}</nowiki>
Line 20: Line 21:
 
</div>
 
</div>
  
−
==== Linking to Module Documentation ====
+
=== Linking to Module Documentation ===
  
 
To link to a module on a wiki page use:
 
To link to a module on a wiki page use:
Line 31: Line 32:
 
: {{ChadoModuleLink|Publication|pub module}}
 
: {{ChadoModuleLink|Publication|pub module}}
  
−
==== Linking to Table Documentation ====
+
=== Linking to Table Documentation ===
  
 
To link to a specific table's description on a wiki page, use:
 
To link to a specific table's description on a wiki page, use:
Line 44: Line 45:
 
Note that this links to the table description on the [[Chado Tables]] page, not to the description on the table's module page.
 
Note that this links to the table description on the [[Chado Tables]] page, not to the description on the table's module page.
  
 +
== Updating Table Documentation Part I ==
 +
 +
''Chado Table Templates'' are the building blocks of the Chado schema documentation.  They are also auto-generated, and cannot be directly updated by editing them on the wiki.  Preventing editing of the templates ensures that user updates are not just written over and lost the next time the templates are auto-generated.
 +
 +
However, it is possible to update table documentation.  It is a two-step process and you must take the first step.  Here's the recipe:
 +
 +
# Enter your update on the wiki.
 +
## Login to the wiki
 +
## Go to the [[Template:ChadoModules|module page]] for the module the table is in.
 +
## Click on the <nowiki>[edit]</nowiki> link to the right of the table you want to comment on.
 +
## Go to the edit window towards the bottom of the page, and add your comments below the section "Additional Comments"
 +
## Save the edits.
 +
# The next time Chado is released, all the module pages will be reviewed for any comments that have been added since the last update. 
 +
## New comments will be added to the Chado SQL table definitions (and probably dropped from the "Additional Comments" sections).
 +
## The table documentation will be regenerated and reposted to the wiki as part of the Chado release.
 +
 +
See [[#Updating Table Documentation Part II|Updating Table Documentation Part II]] for more on how step #2 is done.
  
  
 +
== Updating Module and Table Documentation Part II ==
  
−
A Chado Table Template itself is a perplexing nest of smaller and smaller templates.  This means it's hard to figure out how the wiki decides how it decides what to show.  However, all this complexity doesn't really matter as it is all auto-generated.
+
Table Templates are themselves a nest of smaller MediaWiki templates.  This means it's hard to figure out how the wiki decides what to show.  However, all this complexity doesn't really matter to the wiki user or even to the wiki editor.  It is all auto-generated, and it is never directly updated using the wiki interface.  The upside of this complexity is that it is easy to change the appearance of all Chado tables in the wiki.  All you do is modify the appropriate template.
  
−
The up side of this complexity is it is easy to change the appearance of all Chado tables in the wiki.  All you do is modify the appropriate template.
+
This section describes how to regenerate the Table Templates from a live Chado database as part of creating a new release of Chado.  '''If you are not creating a Chado release, or not a GMOD web site manager, then you don't care about this section.'''

Revision as of 05:36, 20 November 2010

Under Construction

This page or section is under construction.

You bet it is.

The Chado schema documentation on this wiki is a mixture of generated content and material directly entered by GMOD users into this wiki. The generated part of the documentation consists of the table definitions that are included on the Chado module pages and on the Chado Tables page, listing all the tables in Chado.

All of the table descriptions on Chado module pages and the Chado Tables page are generated every time their is a new release of Chado. The column and table details, including comments, come from the PostgreSQL data dictionary.

Using Module and Table Documentation

This section describes how to use the Chado Schema Documentation when updating/creating content on this wiki.

Showing a Table Description

To show the information about any table, use the Chado Table Template for that table: 

 {{ChadoTable_tablename}}

For example, 

 {{ChadoTable_cvterm}}

will show the table description for cvterm:

<protect>

Table: cvterm
Module: CV

A term, class, universal or type within an ontology or controlled vocabulary. This table is also used for relations and properties. cvterms constitute nodes in the graph defined by the collection of cvterms and cvterm_relationships.

cvterm columns
FK Name Type Description
cvterm_id serial PRIMARY KEY
cv cv_id integer UNIQUE#1

NOT NULL
The cv or ontology or namespace to which this cvterm belongs.

name character varying(1024) UNIQUE#1

NOT NULL
A concise human-readable name or label for the cvterm. Uniquely identifies a cvterm within a cv.

definition text A human-readable text

definition.

dbxref dbxref_id integer UNIQUE

NOT NULL
Primary identifier dbxref - The unique global OBO identifier for this cvterm. Note that a cvterm may have multiple secondary dbxrefs - see also table: cvterm_dbxref.

is_obsolete integer UNIQUE#1

NOT NULL
Boolean 0=false,1=true; see GO documentation for details of obsoletion. Note that two terms with different primary dbxrefs may exist if one is obsolete.

is_relationshiptype integer NOT NULL

Boolean 0=false,1=true relations or relationship types (also known as Typedefs in OBO format, or as properties or slots) form a cv/ontology in themselves. We use this flag to indicate whether this cvterm is an actual term/class/universal or a relation. Relations may be drawn from the OBO Relations ontology, but are not exclusively drawn from there.

Tables referencing cvterm via foreign key constraints:

</protect>

Linking to Module Documentation

To link to a module on a wiki page use: 

 {{ChadoModuleLink|Module Name|text to show}}

For example: 

 {{ChadoModuleLink|Publication|pub module}}

Which is shown as:

pub module

Linking to Table Documentation

To link to a specific table's description on a wiki page, use: 

 {{ChadoTableLink|table_name}}

For example: 

 {{ChadoTableLink|feature}}

will result in:

feature

Note that this links to the table description on the Chado Tables page, not to the description on the table's module page.

Updating Table Documentation Part I

Chado Table Templates are the building blocks of the Chado schema documentation. They are also auto-generated, and cannot be directly updated by editing them on the wiki. Preventing editing of the templates ensures that user updates are not just written over and lost the next time the templates are auto-generated.

However, it is possible to update table documentation. It is a two-step process and you must take the first step. Here's the recipe:

  1. Enter your update on the wiki.
    1. Login to the wiki
    2. Go to the module page for the module the table is in.
    3. Click on the [edit] link to the right of the table you want to comment on.
    4. Go to the edit window towards the bottom of the page, and add your comments below the section "Additional Comments"
    5. Save the edits.
  2. The next time Chado is released, all the module pages will be reviewed for any comments that have been added since the last update.
    1. New comments will be added to the Chado SQL table definitions (and probably dropped from the "Additional Comments" sections).
    2. The table documentation will be regenerated and reposted to the wiki as part of the Chado release.

See Updating Table Documentation Part II for more on how step #2 is done.


Updating Module and Table Documentation Part II

Table Templates are themselves a nest of smaller MediaWiki templates. This means it's hard to figure out how the wiki decides what to show. However, all this complexity doesn't really matter to the wiki user or even to the wiki editor. It is all auto-generated, and it is never directly updated using the wiki interface. The upside of this complexity is that it is easy to change the appearance of all Chado tables in the wiki. All you do is modify the appropriate template.

This section describes how to regenerate the Table Templates from a live Chado database as part of creating a new release of Chado. If you are not creating a Chado release, or not a GMOD web site manager, then you don't care about this section.

Retrieved from "http://gmod.org/mediawiki/index.php?title=Chado_Schema_Documentation_HOWTO&oldid=15187"