Figures

[JGilbert-eLife]

Description

Main figures are present in nearly every research article.

User stories

Author

• As an author, I want to be able to clearly see my figures, so that I can be sure that none are missing and that their quality is sufficient.
• As an author, I want to be able to clearly identify any source data or code that is directly associated with my figures so that I can confirm this relationship has been captured correctly.
• As an author, I want to be able to clearly identify any figure supplements or video supplements associated with my figures so that I can confirm this relationship has been captured correctly.
• As an author, I want to be able to replace the image for a figure in the manuscript, so that I can fix errors in the images that were originally supplied.
• As an author, I want to be able to edit the title and legend for a figure so that I can correct any errors during proofing.
• As an author, I want to be able to add a reference or asset citation to my figure title and legend so that I can cite other articles or assets in this context.
• As an author, I want to be able to reorder my figures so that I can fix any issues with figure ordering.

Production staff

• As production staff, I want to be able to add a new main figure to the manuscript so that I can include new content at the request of the author.
• As production staff, I want to be able to remove an existing figure on behalf of the author, so that the manuscript is up to date for publishing.
• As production staff, I want to know why an author has changed a figure image so that I know reasons for the change.
• As production staff, I want to provide an explanation for why I am replacing a figure image so that I can record the reason for the change.
• As production staff, I want to compare a replacement figure image with the original so that I can check it matches the author's reason for the change.
• As production staff, I want to be able to change the labelling scheme on a figure so that I can implement different naming conventions.
• As production staff, I want to be able to add an attribution to a figure so that appropriate credit can be included when required.
• As production staff, I want to be able to edit the attribution for a figure so that I can correct errors.

Érudit

• As a production staff, I want to be able to edit the figure labels to fix any error detected in this content.

But what if . . . ?

Please provide details of situations that may occur and/or overlap with other features and are not covered in the user stories.

Consideration

• Every figure is accompanied by a title.
• A full caption for the figure describing its contents is optional but preferred.
• Most figures have labels (Figure 1, Figure 2, Figure 3 etc). However, in correction notices and feature content eLife currently allows unlabelled figures.
• Érudit and probably SciELO do not have control of the figure labelling - they received all sorts of figure labels from their journals - and so for them, the labelling scheme should not be pre-formatted.
• For eLife, where labels are present, they should be auto-generated and non-editable. We don’t want authors messing with the labelling scheme. However, we allow several variants on what those labels are. For example, we have three variants of Figure in the main text:
  • Figure 1 [standard main figure, should be cited in the text]
  • Chemical structure 1 [a chemical structure image accompanying a method, does not need to be cited]
  • Scheme 1 [a chemical reaction diagram or other process scheme, does not need to be cited]
• Figures are supplied to us in a variety of image formats, with PDF and TIFFs being the most common. At the moment our author guide states, “Figures can be uploaded individually in the following formats: TIFF, GIF, JPG, EPS, AI, PDF and Corel Draw. If you would like to supply PDF images please ensure that they are saved in a Vector image format.” We will need some sort of convertor to process the images that authors upload into the required output format (high resolution TIFF).
• Authors may label their figures within the image file (mainly because of the editorial process) and we do not change them during production.
• Some figures require attributions - at eLife, this is used in feature content to credit illustrations: https://elifesciences.org/articles/45734
• For eLife, the annual PDF-based print product requires PITstop approved (preflight digital print quality check) PDF quality in order to generate the Highlights from the journal annual print product. We do not know what will be included in this each year and what our print requirements might be in the future. This product requires high-quality images, which need to be stored somewhere in our workflow and available for the PDF generation process, so if an author replaces a figure, the replacement figure must be replaced in this location too.
• The above may be a consideration for print-based publishers if they adopt Texture as well.

XML requirements

Captured using fig.

<fig id="fig1" position="float">
        <label>Figure 1.</label>
        <caption>
                <title>Single figure: The header of an eLife article example on the HTML page. In the PDf this is represented as a single column.</title>
                <p>text text <tex-math>...</tex-math> ... </p>
        </caption>
        <graphic mimetype="image" mime-subtype="tiff" xlink:href="elife-00666-fig1.tif"/>
        <permissions>
                <copyright-statement>&#x00A9; 2016 eLife. All rights reserved</copyright-statement>
                <copyright-year>2016</copyright-year>
                <copyright-holder>eLife</copyright-holder>
                <license>
                        <license-p>For the purpose having a example of how to tag a separate license for an item, we have indicated in the XML and display this is a copyrighted figure; however it is not.</license-p>
                </license>
        </permissions>
</fig>

The content of label is (in part) dependent on fig location. If it's in an appendix (say, Appendix 1), then the label is prefaced with 'Appendix 1—', i.e <label>Appendix 1—figure 1.</label>, and if it's placed in boxed text then it's prefaced with the 'Box 1—' i.e <label>Box 1—figure 1.</label>.

fig must be allowed to captured as a child of the following elements:

• fig-group
• sec
• body
• boxed-text
• app (if used for appendices)

eLife needs to fig to allow the following child elements:

• label
• caption
• graphic
• attrib
• permissions

Example of attrib use:

<fig id="fig1" position="float">
        <caption>
                <title>Sports teams recognize the importance of young players ('rookies') and seasoned veterans working together, and the same is true in science.</title>
        </caption>
        <graphic mime-subtype="tiff" mimetype="image" xlink:href="elife-45734-fig1-v1.tif"/>
        <attrib>Illustration: Ben Marder.</attrib>
</fig>

Mock ups

Proposal

[fabiobatalha]

Last minute user stories. (maybe it should be a separated issue to deal with group of figures)

What if

• I want to have a group of figures with title and caption and with multiple figures inside it.

User Stories

• As a production staff I want to edit, remove and update the title and caption of a group of figures
• As a production staff I want to add new figures to a group of figures
• As a production staff I want to remove figures of a group of figures
• As a production staff I wanto to replace figures in a group of figures

XML Sample

<fig-group>
  <label>Figure 2</label>
  <caption xml:lang="fr">
    <title>Le programme original du 1<sup>er</sup> congrès octobre 1960</title>
  </caption>
  <fig id="fi6">
    <graphic xlink:href="1861197n.jpg" position="float" content-type="figure"/>
    <graphic xlink:href="1861198n.jpg" position="float" content-type="figure"/>
  </fig>
</fig-group>

Considerations

• The title and caption concerns to the group of figures and not to one figure inside the group
• The figures inside the group don't have title and caption

[source-data]

Here is an extension of the user stories for structured multi-panel figures.

Multi-panel structured figures

EMBO SourceData allows the creation of structured figures where individual panels benefit from all functionalities normally available to figures.

User stories

• As an author, I want to create a new figure from a local image file so that I can easily provide a visual depiction of a scientific result.
• As an author, I want to create a new empty figure so that I can use it as place holder and work on it later.
• As an author, I want to add and edit a title to a figure so that I can provide a short description of the subject of the figure.
• As an author, I want to add a caption to the figure so that I can provide a detailed unstructured description of its content.
• As an author, I want to add multiple images to my figure so that I can easily create a structured figure with multiple panels.
• As an authors, I want to easily replace or delete the images of the figure so that I can update the illustrations and correct mistakes.
• As an author, I want to add and edit separate captions for each panel so that I can provide detailed descriptions specifically associated with each panel.
• As an author, I want to add and edit a first or last paragraph of the figure caption so that I can provide information common to the whole figure.
• As an author, I want to reference a specific figure in the main text such that I can point the reader to the respective set of results.
• As an author, I want to reference a specific figure panel from the text so that I can point the reader to the specific result.
• As an author, I want to reference a range of figure panels from the text so that I can point the reader to the specific set of results.
• As an author, I want to be able to override panel labels assigned automatically so that I can generate custom labels, in particular to specify arbitrary ranges of panels.
• As an author, I want to add, delete, insert and reorder figure panels so that I can show scientifically related results in the correct sequence.
• As an author, I want to have an overview of all the panels of a figure so that I can see at a glance how many panels there are and what is their content.
• As an author, I want to easily access to any arbitrary panel within a figure so that I can directly work on this panel to write or edit its legend and to add or change the image.
• As an author, I want to group several figures so that I can visually present results as a hierarchy of main vs additional/supplementary/secondary figures.
• As an author, I want to create a new figure from select panels taken from one or multiple figures so that I can quickly assemble a complex figure from previous preliminary figures.
• As a reader, I want an overview of all the panels of a figure so that I understand the results of a given panel in the context of the full figure.
• As a reader, I want a clear relationship between panels and their captions so that I understand easily what is shown in individual panels.
• As a reader, I want to be able to query a panel when it is called out in the main text so that I can keep my focus on the flow of the text while quickly and transiently comparing the results shown with the claim in the text.

Considerations

• The author user stories take into account both the authoring and editing context.
• The user stories above include the SourceData multi-panel figures use case and the eLife’s multi-figure group use case. Current use case do not combine both approaches but making both use cases mutually exclusive would probably not be the best solution for the future.
• 'Reader' can be interpreted as a 'collaborator' with whom the document has been shared.
• Some user stories refer to advanced functionalities, for example merging panels from multiple figures, which may need separate planning.

[Melissa37]

Hi @NickDuf do you have any comments on these additional user stories before I incorporate them into the main ticket specification at the top?

@FAtherden-eLife any changes required to the XML?

[NickDuf]

@Melissa37 I will take a look this morning.

[fred-atherden]

@Melissa37 I think this user story and consideration informs/greatly affects the discussion in #1281: User story

As an author, I want to group several figures so that I can visually present results as a hierarchy of main vs additional/supplementary/secondary figures.

Consideration

The user stories above include the SourceData multi-panel figures use case and the eLife’s multi-figure group use case. Current use case do not combine both approaches but making both use cases mutually exclusive would probably not be the best solution for the future.

I don't think we need to add anything to the XML requirements here though based on these user stories.

[fred-atherden]

@Melissa37, @JGilbert-eLife what about Fabio's comment above? Presumably, we need to account for this in some way?

[JGilbert-eLife]

@FAtherden-eLife It sounds like it could be covered by a stricter implementation of what Source Data want to do. Perhaps we can revisit this once Nick's finished looking over their user stories?

@source-data - @NickDuf is going to be out of the office until Monday but he would like to set up a quick phone call to ask a few questions about the user stories you posted above.