Finding Convention Discussion

lomky commented 6 years ago

A ticket to discuss the conventions surrounding Findings.

Finding Fields:

                                                                                               Table "gcis_metadata.finding"
       Column       |       Type        | Modifiers | Storage  | Stats target |                                                                 Description
--------------------+-------------------+-----------+----------+--------------+---------------------------------------------------------------------------------------------------------------------------------------------
 identifier         | character varying | not null  | extended |              | A descriptive identifier for this finding.
 chapter_identifier | character varying |           | extended |              | The chapter containing this finding.
 statement          | character varying |           | extended |              | The statement of the finding.
 ordinal            | character varying |           | extended |              | The numeric position of this finding within a chapter. Must start with a number, may contain numbers, letters, dashes, dots and underscores
 report_identifier  | character varying | not null  | extended |              | The report associated with this finding.
 process            | character varying |           | extended |              | The process for developing this finding.
 evidence           | character varying |           | extended |              | A description of the evidence base.
 uncertainties      | character varying |           | extended |              | A description of the uncertainties.
 confidence         | character varying |           | extended |              | An assessment of the confidence in this finding based on the evidence.
 url                | character varying |           | extended |              | A URL for a landing page for this finding.
Indexes:
    "finding_pkey" PRIMARY KEY, btree (identifier, report_identifier)
    "finding_report_identifier_chapter_identifier_ordinal_key" UNIQUE CONSTRAINT, btree (report_identifier, chapter_identifier, ordinal)
Check constraints:
    "ck_finding_identifier" CHECK (identifier::text ~ similar_escape('[a-z0-9_-]+'::text, NULL::text))
    "finding_mostly_numeric_ordinal" CHECK (ordinal::text ~ '^[0-9]+[0-9a-zA-Z._-]*$'::text)
Foreign-key constraints:
    "finding_chapter_fkey" FOREIGN KEY (chapter_identifier, report_identifier) REFERENCES chapter(identifier, report_identifier) ON UPDATE CASCADE ON DELETE CASCADE
    "finding_report_fkey" FOREIGN KEY (report_identifier) REFERENCES report(identifier) ON UPDATE CASCADE ON DELETE CASCADE
Triggers:
    audit_trigger_row AFTER INSERT OR DELETE OR UPDATE ON finding FOR EACH ROW EXECUTE PROCEDURE audit.if_modified_func('true')
    audit_trigger_stm AFTER TRUNCATE ON finding FOR EACH STATEMENT EXECUTE PROCEDURE audit.if_modified_func('true')
    delpub BEFORE DELETE ON finding FOR EACH ROW EXECUTE PROCEDURE delete_publication()
    updatepub BEFORE UPDATE ON finding 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:

 prov:wasInformedBy
 cito:isCitedBy
 prov:wasDerivedFrom
 cito:cites

Relationships:

Chapter
Report

lomky commented 6 years ago

Overview

What is a Finding?
In USGCRP Reports, every chapter has a "Key Message" - a short statement of fact with backing supporting evidence.
Only used on USGCRP published reports, and only exists as a subobject.

TODO

Ask TSU for their guidance for the fields:
- evidence
- statement
- process
- uncertainty
- confidence

Field Breakdown

identifier
Existing Meaning:

A descriptive identifier for this finding.

Should follow the convention of:

Key-Finding-CH#-ORD
Key-Message-CH#-ORD

The initial part of the identifier should match the naming of this object type for that report

chapter_identifier
Existing Meaning:

The chapter containing this finding.

The chapter, if any, that contains this finding.

statement
Existing Meaning:

The statement of the finding.

The shorter, headline sentence that conveys the key information. Filled in via data provided from TSU. Data contained within is provided by the authors following guidance.
HTML Formatting is supported.
Callouts to References should be done via their UUIDs, and captured within <tbib> tags.

ordinal
Existing Meaning:

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

The ordinal as specified in the actual report.

report_identifier
Existing Meaning:

The report associated with this finding.

The report that contains this finding.

process
Existing Meaning:

The process for developing this finding.

Filled in via data provided from TSU. Data contained within is provided by the authors following guidance.
HTML Formatting is supported.
Callouts to References should be done via their UUIDs, and captured within <tbib> tags.

evidence
Existing Meaning:

A description of the evidence base.

Filled in via data provided from TSU. Data contained within is provided by the authors following guidance.
HTML Formatting is supported.
Callouts to References should be done via their UUIDs, and captured within <tbib> tags.

uncertainties
Existing Meaning:

A description of the uncertainties.

Filled in via data provided from TSU. Data contained within is provided by the authors following guidance.
HTML Formatting is supported.
Callouts to References should be done via their UUIDs, and captured within <tbib> tags.

confidence
Existing Meaning:

An assessment of the confidence in this finding based on the evidence.

Filled in via data provided from TSU. Data contained within is provided by the authors following guidance.
HTML Formatting is supported.
Callouts to References should be done via their UUIDs, and captured within <tbib> tags.

url
Existing Meaning:

A URL for a landing page for this finding.

If there is a direct URL to the finding, add it here.
Prefer not linking to the general parent page (aka the chapter).

lomky commented 6 years ago

Provenance Connections:

cito:cites & cito:isCitedBy

The Finding cites its references
If future USGCRP product cite this Finding, it may have 'isCitedBy'

Relationships:

Chapter

If it is within a report chapter, this must be filled in.

Report

This must be filled in.

USGCRP / gcis-conventions