Asset-level source files

[fred-atherden]

Description

eLife allows source code and source data files to be directly associated with figures and figure supplements, tables and videos. EMBO/SourceData allow source files associated with whole figures, multiple figures and individual figure panels.

User Stories

Author

• (1) As an author, I want to be able to clearly see any source data or code associated with assets (figures, figure supplements, videos or tables) so that I can be sure that they are associated correctly and that none are missing.
• (2) As an author, I want to be able to edit the title and legend for any source data or code associated with assets so that I can ensure that my work is accurately represented for publishing.
• (3) As an author, I want to be able to download any source data or code file so that I can check that the correct file is being used.
• (4) As an author, I want to be able to replace source data or code files so that my manuscript is up to date and ready for publication.

Production staff

• (5) As production staff, I want to be able to remove, replace, add or re-allocate source data or code associated with an asset on behalf of the author during the proofing process, so that I can correct association errors before publication.
• (6) As production staff, I want to know why an author has changed a source data or code file associated with an asset so that I know reasons for the change.
• (7) As production staff, I want to provide an explanation for why I am replacing a source data or code file associated with an asset so that I can record the reason for the change.

EMBO SourceData

• (8) As an author, I want to be able to associate a data file with one or more figures so that I can share the source data for my figure.
• (9) As an author, I want to be able to associate a data file with one or more panels across one or more figures so that I can share the source data for individual panels.
• (10) As an author, I want to be able to delete a data file so that I can remove source data uploaded in error.
• (11) As an author, I want to be able to add a title to a data file so that I can describe it to a collaborator.
• (12) As an author, I want to be able to edit a title for a data file so that I can correct any errors.
• (13) As a collaborator, I want to be able to clearly see which data files are associated with a figure or panel so that I can see the source data for the images.
• (14) As a collaborator, I want to be able to download a data file associated with a figure or panel so that I can review the data.

But what if . . . ?

Considerations

This ticket is specifically about source files that will be contained within the DAR file format. This is important for EMBO SourceData since they want to treat 'internal' source files and 'external' source files (e.g. those hosted on FTP sites, stored in external repositories under accession numbers etc) as equivalent for the purposes of user experience."

• Labelling example, in context of figure and figure supplements:
  • Figure 1
  • Figure 1—source data 1
  • Figure 1—source code 1
  • Figure 1—figure supplement 1
    • Figure 1—figure supplement 1—source data 1
  • Figure 1—figure supplement 2
  • Figure 2
  • Figure 2—source data 1
• As with main figures, we don't want authors to be able to sweepingly decide to delete or add source data files. These kinds of changes may need editorial input, so we need to be able to exercise a degree of arbitration.
• We would expect the hierarchy/order of files in the additional files section to follow this logic:
  • Asset level source files follow the hierarchy of the asset in question (i.e. figure supplement source data is placed after figure supplement source data)
  • Asset level source files appear before article level source files
• The title for the section containing the source files would have to be editable.

XML requirements

Asset level source data and code should be captured in the additional files section in the back:

<back>
     ...
     <sec id="s6" sec-type="supplementary-material">
          <title>Additional files</title>
          ...
          <supplementary-material id="fig3scode1">
               <label>Figure 3—source code 1.</label>
               <caption>
                    <title>Custom python scripts used to generate Figure 3A-C</title>
               </caption>
               <media mime-subtype="zip" mimetype="application" xlink:href="elife-44527-code1-v3.zip"/>
          </supplementary-material>
          <supplementary-material id="fig3s3sdata1">
               <label>Figure 3—figure supplement 3—source data 1.</label>
               <caption>
                    <title>Detailed counts of cells quantified in <xref ref-type="fig" rid="fig2s3">Figure 2—figure supplement 3</xref> in the different experimental conditions.</title>
               </caption>
               <media mime-subtype="xlsx" mimetype="application" xlink:href="elife-44527-fig3-figsupp3-data1-v2.xlsx"/>
          </supplementary-material>
          <supplementary-material id="video1sdata1">
               <label>Video 1—source data 1.</label>
               <caption>
                    <title>Rho mutations from all replicate evolution experiments.</title>
               </caption>
               <media mime-subtype="xlsx" mimetype="application" xlink:href="elife-44527-data1-v1.xlsx"/>          
          </supplementary-material>
          <supplementary-material id="table4sdata1">
               <label>Table 4—source data 1.</label>
               <caption>
                    <title>Thermograms and normalized plotted data from ITC titration of TRAP220 peptide into PPARγ LBD.</title>
                    <p>...</p>
               </caption>
               <media mime-subtype="pdf" mimetype="application" xlink:href="elife-44527-table4-data1-v2.pdf"/>
          </supplementary-material>
          ...
           <supplementary-material id="sdata1">
               <label>Source data 1.</label>
               <caption>
                    <title>Source data for the whole article.</title>
                    <p>...</p>
               </caption>
               <media mime-subtype="pdf" mimetype="application" xlink:href="elife-44527-data1-v2.pdf"/>
          </supplementary-material>
     </sec>
     ...
</back>

This should then be referenced with an xref element, which is a direct child of the respective element (fig, table-wrap, or media). The xref should contain the content of the label for the supplementary-material it points to:

<article>
     ...
     <fig-group>
          <fig id="fig3" position="float">
               <label>Figure 3.</label>
               <caption>
                    <title>...</title>
                    <p>...</p>
               </caption>
               ...
               <xref ref-type="supplementary-material" rid="fig3scode1">Figure 3—source code 1.</xref>
          </fig>
          <fig id="fig3s3" position="float">
               <label>Figure 3—figure supplement 3.</label>
               <caption>
                    <title><italic>Hmx3</italic>; tdTOM+ cells negative for <italic>Htr3a</italic>-GFP often express glial markers.</title>
                    <p>...</p>
               </caption>
               <xref ref-type="supplementary-material" rid="fig3s3sdata1">Figure 3—figure supplement 3—source data 1.</xref>
               ...
     </fig-group>
     ...
     <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>...</p>
           </caption>
          <xref ref-type="supplementary-material" rid="video1sdata1">Video 1—source data 1.</xref>
     </media>
     ...
     <table-wrap id="table4" position="float">
          <label>Table 4.</label>
          <caption>
               <title>ITC analysis of TRAP220 peptide titrated into PPARγ LBD.</title>
               <p>...</p>
          </caption>
          <xref ref-type="supplementary-material" rid="table4sdata1">Table 4—source data 1.</xref>
          <table>
               <thead>...</thead>
               <tbody>...</tbody>
          </table>
     </table-wrap>
</article>

SourceData

SourceData require the ability for overall Figures (composed of multiple panels) to also have source files associated. In such instances, xref should be used as a direct child of fig-group:

<fig-group id="fig3">
    <label>Figure 3.</label>
    ...
    <fig id="fig3a" position="float">
     ...
    </fig>
    <fig id="fig3b" position="float">
     ...
    </fig>
     ...
    <xref ref-type="supplementary-material" rid="fig3sdata1">Figure 3—source data 1.</xref>
</fig-group>

Mock ups

This is not required, but if you have mock ups of what you would like to see please provide them here.

Proposal

This will be added by the Texture team after the feature request is discussed and agreed.

[obuchtala]

Labelling example, in context of figure and figure supplements: Figure 1 Figure 1—source data 1 Figure 2 Figure 2—source data 1

Please also take into consideration, that a data file might be the source for two or more figures. This is particularly common if e.g. a larger table of data is processed in different ways, such as using different columns.

[Melissa37]

@oliver---- This is why I'd like the tickets to be combined - that's not an eLife use case, but is a SourceData use case

[Melissa37]

https://groups.niso.org/apps/group_public/view_comment.php?comment_id=830&add_comment=1

[JGilbert-eLife]

@Melissa37, @oliver---- - On reviewing the requirements/user stories that @source-data have in #1245, I think it is important that we distinguish two different kinds of data that can be associated with figures: files that are going to be included in the DAR file, and external data on an FTP site, a data repository etc. This is not something that I expect to be reflected in the user experience, but it does mean we have the case where a file is being directly included (which is what eLife's requirements are centred around) and the case where the data is represented by a link to some external site.

@michael / @oliver---- - am I right in thinking that source data hosted on an external site will need a different XML solution and if so, should be dealt with in a separate ticket?

Given that the other user stories on this ticket are centred around the case where the files will be included in the DAR, I've summarised what I think are @source-data's user stories for this case here. The requirement to also be able to associate source data on external sites with figures and panels should, I think, be captured in a separate ticket, even if the UI ends up similar.

[michael]

@Melissa37, @oliver---- - On reviewing the requirements/user stories that @source-data have in #1245, I think it is important that we distinguish two different kinds of data that can be associated with figures: files that are going to be included in the DAR file, and external data on an FTP site, a data repository etc. This is not something that I expect to be reflected in the user experience, but it does mean we have the case where a file is being directly included (which is what eLife's requirements are centred around) and the case where the data is represented by a link to some external site.

We already have support for external supplementary files. Instead of a file (included in the DAR), those take a URL. Both are represented as supplementary-material elements in JATS.

[Melissa37]

We already have support for external supplementary files. Instead of a file (included in the DAR), those take a URL. Both are represented as supplementary-material elements in JATS.

@michael that's great! For eLife we don't list them in supplementary material but have http links or put them in references, but I assume that's not a problem either.

[source-data]

'as a Collaborator (I am not sure how this role is defined; we had the role "Recipient" defined in our doc which is similar to a 'reader') I want a separate View where all the Files are listed with their associations.'
This may or may not have implications on the tagging but it could put some constraints on how the tagging at the figure or panel level can be used to render an overview list.

[JGilbert-eLife]

Hi @source-data - thanks for commenting. Sorry, I misunderstood what you meant by 'recipient' previously. Would it be better to use 'reader' in these user stories? At a glance, it looks like all recipients of the data (either collaborators with the authors or post-publication readers) would count as readers for the purposes of the Texture interface?

The user story in your comment sounds like a solution to "As a [collaborator/recipient/reader], I want to be able to clearly see which data files are associated with a figure or panel so that I can see the source data for the images" rather than a separate requirement. Is that right? Or should we have another user story that is something like, "I want to be able to see all the files at once so that I can study the source files for the entire article"?

[source-data]

Here is a updates list of user stories. The description is also updated below:

Linked source files

EMBO SourceData allows files to be associated with the whole document, individual or multiple figures, individual or multiple figure panels.

User stories

• As an author, I want to link or unlink one or several files with one or several panels of a given figure so that datasets, protocols, computer scripts related to the results depicted in the linked panels are available to those who will use the panels.
• As an author, I want to link or unlink one or several files to one or several figures so that datasets, protocols, computer scripts related to the results depicted in the linked figures are available to those who will use the figures.
• As an author, I want to associate one or several data files to the whole document so that datasets, protocols, computer scripts related to the results depicted in the linked figures are available to those who will use the document.
• As an author, I want to add or edit a title to a file associated to panels, figures or document so that I can provide a short description of the content and nature of the file (data, protocol, scripts, …).
• As an author, I want to link or unlink a local file (to a panel or figure or document) so that I can easily share in a lossless manner the document and its associated files.
• As an author, I want to link a remotely hosted file (to a panel or figure or document) so that I can share a document associated with files that would be not practicable to move around in particular because of size, legal or controlled access issues.
• As an author, I want to link files hosted on a public database so that I can easily use database accession numbers.
• As an author, I want to provide an overview of all the linked files so that I and readers can have an overview of the number and nature of the files and easily visualize which panel or figure depicts the corresponding results.
• As a reader, I want to easily access the files associated with a specific panel or figure so that I can use them locally.
• As a reader, I want an overview of all the linked files so that I see how many files are linked, what is their nature and size and easily identify and access the panels or figures that depict the corresponding results.

Considerations:

• The author user stories take into account both the authoring and editing context.
• Linking to local or remote files will require different implementations. However from the point of view of an author and reader user experience, it may not need to be fundamentally different. To keep in mind a general solution, I kept this in the user stories above even if it is understood that this may require separate planning.
• The co-packaging of files in the .dar archive is a particular implementation of how the document and associated files can be easily shared. 'Easy sharing' may then include sending the archive as an attachment by email or posting on sharing tools similar to DropBox etc... For very large files, 'easy sharing' may not involve co-packaging of data files but rather linking to downloadable resources.

[Melissa37]

Hey @NickDuf do you have any comments on these user stories and considerations before I integrate them into the ticket? @FAtherden-eLife do you have any amendments to make to the XML?

Thanks!

M

[fred-atherden]

@FAtherden-eLife do you have any amendments to make to the XML?

@Melissa37, presumably I do, but I'm not sure exactly what's required here.

@source-data, for this user story:

As an author, I want to link a remotely hosted file (to a panel or figure or document) so that I can share a document associated with files that would be not practicable to move around in particular because of size, legal or controlled access issues.

Is the requirement here just to be able to add an ext-link in the caption or something more akin to the xref for local files? If the latter, please can you let us know if any markup has been proposed/decided upon so that this can be included in the ticket above. (I can't see any XML samples for this in #1245)

[tlemberger]

@oliver---- and @michael need to decide on the suitable xml implementation. In terms of the underlying tagging, it seems to me more akin to ext-link since it refers to external resources. I don't see how xref could be used in this context, but my knowledge is imited.

In terms of UI implementation for the authoring scenario, linking to remote or local files will most likely be somewhat related since the reasons indicated in both user stories are indeed similar: "so that I can easily share in a lossless manner the document (the figure) and its associated files". It should be made clear to the user whether s/he is linking to a remote or local file, but the purpose from the user's point of view is simialr. So, it needs some more specialized implementation than just instering some link somewhere in the caption. It needs to make it clear that this is THE data for THIS particular panel.