Table Convention Discussion

[lomky]

A ticket to discuss the conventions surrounding Tables.

Current Table Conventions. (none)

Finding Fields:

gcis=# \d+ table
                                                                                               Table "gcis_metadata.table"
       Column       |       Type        | Modifiers | Storage  | Stats target |                                                                Description
--------------------+-------------------+-----------+----------+--------------+-------------------------------------------------------------------------------------------------------------------------------------------
 identifier         | character varying | not null  | extended |              | A desciptive identifier.
 report_identifier  | character varying | not null  | extended |              | The report.
 chapter_identifier | character varying |           | extended |              | The chapter containing this table.
 ordinal            | character varying |           | extended |              | The numeric position of this table within a chapter. Must start with a number, may contain numbers, letters, dashes, dots and underscores
 title              | character varying |           | extended |              | The title of the table.
 caption            | character varying |           | extended |              | The caption for the table.
 url                | character varying |           | extended |              | A URL for a landing page for this table.
Indexes:
    "table_pkey" PRIMARY KEY, btree (identifier, report_identifier)
    "table_report_identifier_chapter_identifier_ordinal_key" UNIQUE CONSTRAINT, btree (report_identifier, chapter_identifier, ordinal)
Check constraints:
    "ck_table_identifier" CHECK (identifier::text ~ similar_escape('[a-z0-9_-]+'::text, NULL::text))
    "table_mostly_numeric_ordinal" CHECK (ordinal::text ~ '^[0-9]+[0-9a-zA-Z._-]*$'::text)
Foreign-key constraints:
    "table_chapter_identifier_fkey" FOREIGN KEY (chapter_identifier, report_identifier) REFERENCES chapter(identifier, report_identifier) ON UPDATE CASCADE ON DELETE CASCADE
    "table_report_identifier_fkey" FOREIGN KEY (report_identifier) REFERENCES report(identifier) ON UPDATE CASCADE ON DELETE CASCADE
Referenced by:
    TABLE "array_table_map" CONSTRAINT "array_table_map_table_identifier_fkey" FOREIGN KEY (table_identifier, report_identifier) REFERENCES "table"(identifier, report_identifier) ON UPDATE CASCADE ON DELETE CASCADE
Triggers:
    audit_trigger_row AFTER INSERT OR DELETE OR UPDATE ON "table" FOR EACH ROW EXECUTE PROCEDURE audit.if_modified_func('true')
    audit_trigger_stm AFTER TRUNCATE ON "table" FOR EACH STATEMENT EXECUTE PROCEDURE audit.if_modified_func('true')
    delpub BEFORE DELETE ON "table" FOR EACH ROW EXECUTE PROCEDURE delete_publication()
    updatepub BEFORE UPDATE ON "table" FOR EACH ROW WHEN (new.identifier::text <> old.identifier::text OR new.report_identifier::text <> old.report_identifier::text) EXECUTE PROCEDURE update_publication()

Provenance Connections:

 cito:isCitedBy
 prov:wasDerivedFrom

Relationships:

Chapter
Report
Contributors
Files
gcmd_keywords
regions
Array

[lomky]

Table Conventions

Appropriate Use Case

The high level representation of array data.
They represent the Table objects in Reports.
We only create them for USGCRP publications.
We create them by hand.

Field Conventions

identifier

Short identifier based on the title.

Current Definition:

A desciptive identifier.

ordinal

Current definition is good.

Current Definition:

The numeric position of this table within a chapter. Must start with a number, may contain numbers, letters, dashes, dots and underscores

title

The title of the table as it appears in the publication.

Current Definition:

The title of the table.

caption

The visible explanatory text that accompanies the array data in the publication.
When there is a difference in the caption between the print and online tables, we match the online table.

Current Definition:

The caption for the table.

url

Generally not used.
If the Table has a proper, stand alone landing page, it should go here.

Current Definition:

A URL for a landing page for this table.

Provenance Conventions

As child:
prov:wasDerivedFrom

With very rare exceptions, not to be used on Tables, but rather their underlying Array.

cito:cites

If a cell in the array or a statement in the caption includes a citation, the table should use this semantic connection to link to the reference.

As parent:
cito:isCitedBy
prov:wasDerivedFrom

These are used when future USGCRP publications cite or derive things from the table.
We do not actively look for outside use of the table.

Relationship Conventions

Chapter

If the Table is within a chapter, this should be connected.
If the Table is in a publication lacking chapters, this may be blank.

Report

Should always be provided, linking to the containing publication.

Contributors

To be filled in if specified in the Publication and we chose to do so on a Publication wide basis.

Files

Not used.

gcmd_keywords

Can be associated if used on a publication wide basis.

regions

not implemeneted

Array

Every table should have at least one array.

[lomky]

Very Poor 1: Report + identifier

Poor 2: Chapter + Report Ordinal + Report Title + Report Array + Report

Acceptable 3: Title + Array + Report

Good 4: Ordinal chapter

Very Good 5: URL caption

-- Should we be considering Array?

[rasherman]

I am thinking we should NOT consider Array, so it would look like this:

Very Poor 1: Report + identifier

Poor 2: Chapter + Report Ordinal + Report

Acceptable 3: Title + Report

Good 4: Ordinal chapter

Very Good 5: URL caption

[amruelama]

We should also document array convention discussion, starting with steps to create array(s) from data.