[Feature] Asset-level source files (WIP)

[michael]

Description

We want the ability to associate files directly with a figure/figure panel. A common use case for this is attaching datasets to individual figures.

This is a work in progress addressing the user stories from #1276.

Proposed Source XML (TextureJATS)

Two figures using the same dataset, one figure uses another.

<fig id="fig1">
  <label>Figure 1</label>
  <caption id="fig1-caption">
    <title>Figure 1 title</title>
    <p id="fig1-caption-p1">Figure 1 caption</p>
  </caption>
  <graphic id="fig1-graphic" mime-subtype="jpeg" mimetype="image" xlink:href="fig1.jpg" />
  <xref ref-type="supplementary-material" rid="source-data-1" />
</fig>
<fig id="fig2">
  <label>Figure 2</label>
  <caption id="fig2-caption">
    <title>Figure 2 title</title>
    <p id="fig2-caption-p1">Figure 2 caption</p>
  </caption>
  <graphic id="fig2-graphic" mime-subtype="jpeg" mimetype="image" xlink:href="fig2.jpg" />
  <xref ref-type="supplementary-material" rid="source-data-1" />
</fig>
<fig id="fig3">
  <label>Figure 3</label>
  <caption id="fig3-caption">
    <title>Figure 3 title</title>
    <p id="fig3-caption-p1">Figure 3 caption</p>
  </caption>
  <graphic id="fig3-graphic" mime-subtype="jpeg" mimetype="image" xlink:href="fig3.jpg" />
  <xref ref-type="supplementary-material" rid="source-data-2" />
</fig>
<table-wrap id="table1">
  <label>Table 1</label>
  <caption><p>Table 1 caption</p></caption>
  ...
  <xref ref-type="supplementary-material" rid="source-data-3" />
</table-wrap>
<media mimetype="video" mime-subtype="mp4" id="video1" xlink:href="elife-00666-video1.mp4">
  <label>Video 1</label>
  <caption>
    <title>A description of the eLife editorial process.</title>
    <p>Video source data legend.</p>
  </caption>
  <xref ref-type="supplementary-material" rid="source-data-4" />
</media>

<sec sec-type="supplementary-files">
  <title>Supplementary Files</title>
  <supplementary-material id="source-data-1" content-type="sdata" mimetype="text" mime-sub-type="csv" xlink:href="source-data-1.csv">
    <label>Supplementary File 1</label>
    <caption>
      <title>Orthogroup clustering analysis</title>
    </caption>
  </supplementary-material>
  <supplementary-material id="source-data-2" content-type="sdata" mimetype="text" mime-sub-type="csv" xlink:href="source-data-2.csv">
    <label>Supplementary File 2</label>
    <caption>
      <title>Orthogroup clustering analysis</title>
      <p>Lorem ipsum dolor sit amet</p>
    </caption>
  </supplementary-material>
  <supplementary-material id="source-data-3" content-type="sdata" mimetype="text" mime-sub-type="xlsx" xlink:href="source-data-3.xlsx">
    <label>Supplementary File 3</label>
    <caption>
      <title>Representative curves of steady-state kinetic analyses for each IGF1R protein characterized</title>
      <p>Each data point was performed in duplicate and is shown separately.</p>
    </caption>
  </supplementary-material>
  <supplementary-material id="source-data-4" content-type="sdata" mimetype="text" mime-sub-type="xlsx" xlink:href="elife-00666-video1-code1.xlsx">
    <label>Supplementary File 4</label>
    <caption>
      <title>Title of the source code</title>
      <p>Legend of the source code.</p>
    </caption>
  </supplementary-material>
</sec>

We propose to allow <xref> inside of a <fig> element (currently not allowed in JATS). We would then not need to abuse the caption for associating files with figures or putting <supplementary-material> inside the caption.

Proposal

Supplementary files are globally available in a special managed section "Supplementary files". It serves as a collection to keep all available files of a document in one place. What a <ref-list> is to references this section is to supplementary files.

Possible user interactions:

• Add file: New files are automatically added to the managed list of supplementary files
• Reorder supplementary files: you can move supp files up and down in the list
• Link a supplementary file from the text: Supplementary files can be cited anywhere, just like references
• Assign supplementary file to figure: Figures have a files section, where the user can link supplementary files to a figure

Considerations

• Provide explicit UI to add (=link) files to figures
• Ability to assign one file (e.g. dataset) to multiple figures
• Use same tagging style for all use-cases in TextureJATS
• Custom labels for files are not considered in this proposal (difficult to generalise, expensive)
• Scoped labels (Figure 1 - Supplementary File 1) are problematic when the same file (e.g. dataset) is referenced by different figures. So we propose to use global counters for files (Supplementary File 1, ...)

[michael]

@dalapeyre what is your opinion about allowing <xref> inside the <fig> element directly, in order to link other resources directly to a figure?

[michael]

@Melissa37 @evabenitoembo @source-data I'd like to put a priority on this topic as we want to move on with implementation of this in the current dev iteration. We'd need to find agreement on the TextureJATS tagging, and define a translation layer for eLife if needed.

Could you all review and update the user stories, including XML requirements for this topic? Once we have that, it would be a good time to set up a call and discuss and refine together the proposal.

[Melissa37]

@michael sounds good. Have pinged @evabenitoembo by email and we'll get back to you next week I hope

[dalapeyre]

On Apr 5, 2019, at 6:13 AM, Michael Aufreiter notifications@github.com wrote:

@dalapeyre what is your opinion about allowing inside the element directly, in order to link other resources directly to a figure?

At the next JATS Standing Committee meeting, we are discussing ways to connect a figure or table with the dataset(s) behind the figure/ table.

If you want to do it through allowing directly inside (not a bad idea at all), post that on the NISO comment list. Then the full Committee will discuss it, along with any other proposals to do the same.

The NISO list is:

https://groups.niso.org/apps/group_public/add_comment.php?document_id=21029

--Debbie

================================================================ Deborah A Lapeyre mailto:dalapeyre@mulberrytech.com Mulberry Technologies, Inc. http://www.mulberrytech.com 17 West Jefferson Street Phone: 301-315-9631 (USA) Suite 207 Fax: 301-315-8385 Rockville, MD 20850

Mulberry Technologies: Consultancy for XML, XSLT, and Schematron

[dalapeyre]

There are some other decisions the JATS Standing Committee made that you guys should know about:

1) Block alternatives

2) Repeated figure and table labels and captions

I will attach an explanation of Block Alternatives in this message, and of multi-lingual table and figure labels and captions in the next.

--Debbie

================================================================ Deborah A Lapeyre mailto:dalapeyre@mulberrytech.com Mulberry Technologies, Inc. http://www.mulberrytech.com 17 West Jefferson Street Phone: 301-315-9631 (USA) Suite 207 Fax: 301-315-8385 Rockville, MD 20850

Mulberry Technologies: Consultancy for XML, XSLT, and Schematron

[dalapeyre]

There are some other decisions the JATS Standing Committee made that you guys should know about:

--Debbie

================================================================ Deborah A Lapeyre mailto:dalapeyre@mulberrytech.com Mulberry Technologies, Inc. http://www.mulberrytech.com 17 West Jefferson Street Phone: 301-315-9631 (USA) Suite 207 Fax: 301-315-8385 Rockville, MD 20850

Mulberry Technologies: Consultancy for XML, XSLT, and Schematron

[michael]

Thank you @dalapeyre ! Glad to hear you support that idea. :)

I just posted a comment: https://groups.niso.org/apps/group_public/view_comment.php?comment_id=814&add_comment=1

@dalapeyre email attachments are not possible I think, you'd need to use the Github interface to attach the files.

[dalapeyre]

Attach them to WHAT at Github? My two email attachments are just descriptions of JATS SC decisions that MAY OR MAY NOT be related to any of your items, that is for you to decide.

I replied all, so some of you should have this in your inbox.

That is one of the things I find annoying on Github, if you know WHERE to put it, its easy, but if you do not know... or there is not good "where"...

Sorry

--Debbie

On Apr 5, 2019, at 11:49 AM, Michael Aufreiter notifications@github.com wrote:

Thank you @dalapeyre ! Glad to hear you support that idea. :)

I just posted a comment: https://groups.niso.org/apps/group_public/view_comment.php?comment_id=814&add_comment=1

@dalapeyre email attachments are not possible I think, you'd need to use the Github interface to attach the files.

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub, or mute the thread.

================================================================ Deborah A Lapeyre mailto:dalapeyre@mulberrytech.com Mulberry Technologies, Inc. http://www.mulberrytech.com 17 West Jefferson Street Phone: 301-315-9631 (USA) Suite 207 Fax: 301-315-8385 Rockville, MD 20850

Mulberry Technologies: Consultancy for XML, XSLT, and Schematron

[jcolomb]

Hi, I am new in the discussion, and I like the whole texture idea very much! Here my comments as a reproducible report enthusiast.

On top of data set, one might want to link a key reagent table or a protocol, or an analysis code, you might find some inspiration looking at how profeza is doing this: https://www.profeza.com

Do I understand it right that tagging the supplementary files to tell what kind of file it is will come later?

Can the link be a doi link or do you plan on attaching files only ?

[source-data]

SourceData user stories

Narrative

Extended narrative from the author, reader and publisher's perspective: https://docs.google.com/document/d/12FBtfwFPjp78XKclNhp4NzDqnuCM1es1RMRBd1xL_t4/edit?usp=sharing

SUMMARY

Objects: Package, Figure, Title, Caption, Label, File, URL, Accession, Link

Users:

• Author: the User who creates, updates and shares a figure-data Package.
• Recipient: the User who receives a figure-data Package shared by another Author.
• Publisher: the User who renders a figure-data Package for online display.

As an Author:

• I give a Title to a Figure.
• I create sequentially new Panels.
• I delete some Panels.
• I insert panels.
• I change the order of Panels.
• For each new Panel, a new Label is generated.
• I can edit the Label to change create a Range of Labels.
• When Labels are changed, the other Labels are updated to keep the consecutive order.
• When the order of the Panels is changed, the other Labels are updated to keep the consecutive order.
• I write one Caption for one Panel.
• I write one Caption for a sub-group of consecutive Panels.
• I add a first/final Caption that provides information common the whole Figure.
• I associate one/several data Files to one/several Panels.
• I associate one/several data Files to one/several Figures [Note: not strictly a scenario for a single standalone figure-data Package, but still useful].
• I associate one/several data Files the whole document [Note: not strictly a scenario for a single standalone figure-data Package, but still useful].
• I give a Title to an already associated File.
• I give a Title to a File before it is associated with any Panels or Figures.
• I associate one or several data URLs to one or several Panels or one or several Figures.
• I associate one or several Accession numbers to one or several Panels or one or several Figures.
• I edit and change an URL or the Accession number.
• I save/open/share one Package as a single file.

As a Recipient:

• I want to download the data File associated with a specific Panel or a Figure without having to open a separate View
• I want a separate View where all the Files are listed with their associations.

As a Publisher:

• I want to generate Links that trigger the download of a specific data File.
• For Files associated with a specific Panel, I want to display Links before/next to/within/after the Caption of this Panel.
• For Files associated with a specific Figure, I want to display Links before/next to/within/after the Caption of this Panel.
• I want to assemble a list/table of all Files and their associated Figures and Panels
• I want to generate a list/table of all Accession numbers and data URLs and their associated Figures and Panels

[obuchtala]

@source-data Thanks for this detailed list. Will discuss with @michael next week, and also think about a 'normalized' format for user stories.

[obuchtala]

@Melissa37 could you help consolidating above user stories?

[michael]

Thank you @source-data for the user stories. It would be great if you could consolidate those into #1276 and coordinate with Melissa. We will use this ticket solely for discussing the proposal (will delete the user stories now).

[michael]

@Melissa37 @source-data are the SourceData user stories already consolidated in #1276 or are you still working on that.

[Melissa37]

@michael I discussed this with @JGilbert-eLife this morning - he added them but has not heard back from @source-data whether they are OK

[JGilbert-eLife]

Looking back, I think I might have confused myself and I didn't directly ask @source-data about the user stories in #1276. Very sorry if there was any confusion there!