Figure Convention Discussion

[lomky]

A ticket to discuss the conventions surrounding Figures.

Current Figure Conventions. (none)

Figure Fields:

       Column       |              Type              | Modifiers | Storage  | Stats target |                                                                Description
--------------------+--------------------------------+-----------+----------+--------------+--------------------------------------------------------------------------------------------------------------------------------------------
 identifier         | character varying              | not null  | extended |              | A descriptive identifier for this figure.
 chapter_identifier | character varying              |           | extended |              | The chapter in which this figure appears.
 title              | character varying              |           | extended |              | The short title, if any.
 caption            | character varying              |           | extended |              | The figure caption.
 attributes         | character varying              |           | extended |              | A free form list of attributes for this figure.
 time_start         | timestamp(3) without time zone |           | plain    |              | The start of the spatial extent represtented by this figure.
 time_end           | timestamp(3) without time zone |           | plain    |              | The end of the spatial extent represtented by this figure.
 lat_max            | character varying              |           | extended |              | The nothernmost latitude in the bounding box for this figure.
 lat_min            | character varying              |           | extended |              | The southernmost latitude in the bounding box for this figure.
 lon_max            | character varying              |           | extended |              | The eastermost longitude in the bounding box for this figure.
 lon_min            | character varying              |           | extended |              | The westernmost longitude in the bounding box for this figure.
 usage_limits       | character varying              |           | extended |              | Copyright restrictions describing how this figure may be used.
 submission_dt      | timestamp(3) without time zone |           | plain    |              | The date on which this image was submitted.
 create_dt          | timestamp(3) without time zone |           | plain    |              | The date on which this image was created.
 source_citation    | character varying              |           | extended |              | Text describing the source of this figure.
 ordinal            | character varying              |           | extended |              | The numeric position of this figure 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 figure
 url                | character varying              |           | extended |              | A URL for a landing page for this figure.
 _origination       | json                           |           | extended |              | origination metadata collected by TSU, should eventually be mapped to an Activity
Indexes:
    "figure_pkey" PRIMARY KEY, btree (identifier, report_identifier)
    "figure_report_identifier_chapter_identifier_ordinal_key" UNIQUE CONSTRAINT, btree (report_identifier, chapter_identifier, ordinal)
Check constraints:
    "ck_figure_identifier" CHECK (identifier::text ~ similar_escape('[a-z0-9_-]+'::text, NULL::text))
    "figure_mostly_numeric_ordinal" CHECK (ordinal::text ~ '^[0-9]+[0-9a-zA-Z._-]*$'::text)
Foreign-key constraints:
    "figure_chapter_report" FOREIGN KEY (chapter_identifier, report_identifier) REFERENCES chapter(identifier, report_identifier) ON UPDATE CASCADE ON DELETE CASCADE
    "figure_report_fkey" FOREIGN KEY (report_identifier) REFERENCES report(identifier) ON UPDATE CASCADE ON DELETE CASCADE
Referenced by:
    TABLE "image_figure_map" CONSTRAINT "image_figure_map_figure_fkey" FOREIGN KEY (figure_identifier, report_identifier) REFERENCES figure(identifier, report_identifier) ON UPDATE CASCADE ON DELETE CASCADE
Triggers:
    audit_trigger_row AFTER INSERT OR DELETE OR UPDATE ON figure FOR EACH ROW EXECUTE PROCEDURE audit.if_modified_func('true')
    audit_trigger_stm AFTER TRUNCATE ON figure FOR EACH STATEMENT EXECUTE PROCEDURE audit.if_modified_func('true')
    delpub BEFORE DELETE ON figure FOR EACH ROW EXECUTE PROCEDURE delete_publication()
    updatepub BEFORE UPDATE ON figure 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:cites
cite:isCitedBy
others?

Relationships:

images
gcmd_keywords
regions

[lomky]

Field work through:

identifier

The title of the figure with hyphens.
May differ if the figure is renamed late in the report process.
Generally, we write "US" instead of "United-States"

chapter_identifier

The associated chapter identifier inside the report, if any, associated with the figure.

title

The title of the Figure as set by TSU.
In the case of FIgures not from TSU, the title as it appears in the report.

caption

Any text appearing alongside the figure.

attributes

deprecated. Unknown use. Not filled in anywhere.

time_start time_end

The start and end of the temporal extent represented by this figure.
We prefer to have these on the image rather than the figure.

lat_max lat_min lon_max lon_min

The nothernmost/southmost latitude & eastmost/westmost longitudes in the bounding box for this figure.

Future development: https://en.wikipedia.org/wiki/Well-known_text

usage_limits

Copyright restrictions describing how this figure may be used.
Historically this has not been filled in properly. Needs to come from TSU, but should not be filled in from their usage limits, but rather whether we created it or not.
For non-TSU figures, fill in accordingly.

Follow-up needed.

submission_dt

Currently, we think this is the last update before submission.
Final determination to be made after conversation with TSU.

Followup needed.

create_dt

Currently, we think this is the initial creation in TSU's system.
Final determination to be made after conversation with TSU.

Follow-up needed.

source_citation

If this isn't an original creation, the citation to that.

Follow-up: should this be captured in provenance?

ordinal

The internal chapter or report numbering (alphanumeric)

report_identifier

The associated report identifier the figure.

url

Direct URL to the Figure landing page in the associated report, if any.

_origination

Internal field to hold data needed by TSU for presetnation of report websites.
Eventually to be phased out via Activity update.

[lomky]

Provenance

cito:cites

Figures can cite their sources

cito:isCitedBy

If the Figure has been cited in a future USGCRP publication, it may be marked as isCitedBy

prov:wasGeneratedBy, prov:wasDerivedFrom, prov:wasInformedBy

These provenence relationships would be better placed on the Image assciated with a Figure, rather than on the Figure itself.

Relationships

Image

All Figures should have an Image.

A Figure should have an Image for each logical subpanel within the figure. When a logical subdivision of the Figure is unavailable, a single backing Image is acceptable.

For when the TSU creates the Figures & Images, the Image subobjects are expected to have proper context and not jsut be cropped.

Report

Figures must belong to a Report or Indicator.

Chapter

Figures may belong to a Chapter, if the Report is broken into Chapters and the Figure is within them.

Contributors

• All Figures should have a Point of Contact
• Figures may have authors, editors, or other contributors depending on the associated Assessment.

regions

Not yet implemented.

gcmd_keywords

On a case by case basis for the parent report, we may assign GCMD keywords to the Figure.

File

All figures should have a high resolution image file associated with it. Preference for PNG for vector-like graphics and JPG for photo-like graphics.

[rasherman]

Generally looks good (a few typos fixed). Follow-up with TSU is definitely needed for usage limits. My understanding is that source citation should definitely go in provenance and not in object metadata. However, we may want to use that field for how a user should cite the figure itself?

[lomky]

Done. Link Leaving open for discussing source citation.

[lomky]

Changed my mind and filed a new ticket for source citation discussion, for clarity.