[Feature] Figure Panels (WIP)

[michael]

Description

We want a complete solution for multi-panel figures addressing the use cases for eLife, SourceData, Erudit and SciELO.

This is a work in progress but we are attempting to address the user stories from #1280.

Source XML (TextureJATS)

<fig-group id="fig1">
  <fig id="fig1" fig-type="main">
    <label>Figure 1</label>
    <caption>
      <title>Figure 1 title</title>
    </caption>
    <graphic id="fig1-graphic" mime-subtype="jpeg" mimetype="image" xlink:href="fig1.jpg" />
  </fig>

  <fig id="fig1a" fig-type="panel">
    <label>Figure 2A</label>
    <caption id="fig1a-caption">
      <title>First panel title (optional)</title>
      <p id="fig1a-caption-p1">First panel caption. </p>
      <p id="fig1a-caption-p2">The dataset <xref id="xref-1" ref-type="bibr" rid="r1">[1]</xref> has been analysed to generate the following projection:</p>
    </caption>
    <graphic id="fig1a-graphic" mime-subtype="jpeg" mimetype="image" xlink:href="fig1a.jpg" />
  </fig>
  <fig id="fig1b" fig-type="panel">
    <label>Figure 1B</label>
    <caption id="fig1b-caption">
      <title>Second panel title (optional)</title>
      <p id="fig1b-caption-p1">Second panel caption</p>
      <p id="fig1b-caption-p2"><xref id="xref-2" ref-type="bibr" rid="source-data-1">Source data 1</xref> has been used to generate this figure.</p>
    </caption>
    <graphic id="fig1b-graphic" mime-subtype="jpeg" mimetype="image" xlink:href="fig1b.jpg" />
  </fig>
</fig-group>

Proposal

We want to propose an opt-in multi-panel figures feature. This means, we don't touch the regular semantics of a single (composite) figure but allow to progressively enhance them with separate panels (each represented as a figure). So a panel has the same properties as a main figure.

Use cases:

• Attach files (source data) for each panel: This allows reproducibility of individual panel images
• Attach metadata/keywords to each panel:
• Attach permissions to each panel separately

Edit main figure of a multi-panel figure:

• can have all information a single figure can have
• supplementary figures can be assigned (aka Figure supplements)
• Supplementary files can be assigned (aka source data for the whole figure)

Edit a panel:

• title is optional (by default main figure title is used)
• legend is optional (by default main figure legend is used)
• permission (license, copyright etc.) can be assigned for individual panels

Edge cases

• Grouped panels in caption: Sometimes the author refers to more than one panel with one legend (D-E). Usually there should be one caption per panel, but in this edge case we suggest to use a combined caption on the main figure. See https://github.com/substance/texture/issues/1250#issuecomment-486620333
• Text that refers to all panels: We suggest to use the main figure caption for that.

[michael]

@source-data can you take a look at the proposal, so we can discuss tomorrow in our call?

[evabenitoembo]

To keep in mind: often we will have situations in which authors may want to group panels. E.g. panels E-D and F-G as in this example:

[evabenitoembo]

And one more thing to keep in mind (did not find a more appropriate place to put this example, feel free to move to correct thread if need be): sometimes we have a short paragraph of text that refers to all of the panels in a figure group, like the last paragraph here with the data information:

Caution: this is not really a footer element!

[michael]

To keep in mind: often we will have situations in which authors may want to group panels. E.g. panels E-D and F-G as in this example:

I think an explicit feature for grouping of panels is problematic here. In cases where authors want to group panels, I'd suggest they just use one combined caption and free-form text. Of course while we keep the panel images separate.

[michael]

And one more thing to keep in mind (did not find a more appropriate place to put this example, feel free to move to correct thread if need be): sometimes we have a short paragraph of text that refers to all of the panels in a figure group, like the last paragraph here with the data information:

You could use the main figure caption here for such additions that belong to all panels. That sound ok?

[Melissa37]

@michael thanks for this - let's discuss on the call on Thursday - I've assigned this to @NickDuf, @JGilbert-eLife and @FAtherden-eLife too so they can assess it before our call too.

If we have useful feedback beforehand we'll try to provide it.

[Melissa37]

@michael I found it quite hard to understand what some of the text meant to describe the options. Can I make the suggested changes below:

Modern (individual panels only, no layout) does not have a graphic element fig group is used just as a container (and reference target)

Change to: SourceData (Modern/future) Fig group has a label and caption/title but no figure associated with this top level tagging. The panels are each provided as figures within the fig group

There are 2 errors in the XML which means it does not validate:

    <label>Figure 1B</label>
    <caption id="fig1b-caption">
      <title>Second panel title (optional)</title>
      <p id="fig1b-caption-p1">Second panel caption</p>
      <p id="**fig1a-caption-p2**"><xref id="**xref-1"** ref-type="bibr" rid="source-data-1">Source data 1</xref> has been used to generate this figure.</p>
    </caption>
    <graphic id="fig1b-graphic" mime-subtype="jpeg" mimetype="image" xlink:href="fig1b.jpg" />
  </fig>```

Bold should be ` fig1b-caption-p2` and `xref-2`

It would also be useful to have labels that match the asset naming, so for instance 

Figure 2 Figure 2A ``` Either label the figures as 1 or change the ids to 2.

Modern Hybrid (individual panels + composite cover image) Main figure legend can be derived from the panels, and is not stored in the fig-group fig-group has the composite figure image (including panels at once)

Can I change to: SourceData (Hybrid model) Fig group has a label and caption/title and the composite figure associated with this tagging. The panels are each provided as figures within the fig group

Errors in the XML that prevent validation: IDs have to be unique, cannot have the same id of id="fig1 for the fig-group as well as the graphic For <fig id="fig1b">' this: id="fig1a-caption-p2"needs to be changed toid="fig1b-caption-p2"`

<xref id="xref-1" is used for both figure panels. They have to be different.

<label>Figure 2A</label> it would be useful to change this to: <label>Figure 1A</label> to match the IDs and the rest.

Legacy (panels only for permissions) ability to refence panels ability to assign permissions to individual panels only one composite figure image needs to be maintained

Could we change this to: Sourcedata (Legacy content without panels split out, but where permissions are different for different panels) ability to refence panels although they are not provided as separate images only one composite figure image stored

Errors in the XML that prevent validation: IDs have to be unique, cannot have the same id of id="fig1 for the fig-group as well as the graphic Please change the label and title in fig1 so it matches the ids - it's easier to understand, eg

<fig-group id="fig1">
  <label>**Figure 1**</label>
  <caption>
    <title>**Figure 1 title**</title>
    <p>A: caption a B: caption b</p>
  </caption>
  <graphic id="fig1" mime-subtype="jpeg" mimetype="image" xlink:href="fig1.jpg" />

The permissions tagging does not validate, should be something like:

<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>

Also, eLife requires the ability to add multiple permissions to a single figure

@michael the use cases and tagging for eLife are contrary to the requirements and usecases we've provided in the tickets you reference. You need to go back to them, sorry! Our fig suppls won't go into supplemetary. We agreed to this for source code/source data, but NOT Figure suppls.

Also, the license button won't work for eLife - we rarely have a different license, so would not want this to appear on every paper (the license normally follows that of the paper). When we add a license it's non-standard and requires all the fields we've specified to be filled out manually as they rarely follow a "named license" that is linked to a uri. Usually named licenses are for open and free to re-use content, which are more akin to what we publish :-)

Proposal Confusion that in the screenshot you mention supplementary figures but you are talking above about SourceDatas panel requirements.

[michael]

@Melissa37 thank you! We are working on improving the wording for more clarity. We also moved "Figure Attachments" into a separate feature ticket. #1289. Please have a look, but no need to comment as we will discuss tomorrow anyways.

[Melissa37]

Hi @michael I just drew this quickly this morning. I think essentially ScourceData and eLife have the same requirement and can be treated the same way in the XML.

Perhaps we could discuss on the call?

Essentially, the word "supplement" in the eLife figure naming does not mean they are supplementary files. If we changed that word and said instead eg Figure 1 part A they'd be the same thing. The word does not hold semantic meaning.

[obuchtala]

Hi @Melissa37 , Yes, that is similar to what we had in mind initially. But, since you brought up the idea of using <graphic>s as panels of a figure, I think, that would fit better for the SourceData use case. Just to make sure that I understood your sketch correctly: would it be wrong to presume, that a Figure Part could potentially consist of multiple 'panels', that means be something like a <fig><graphic/><graphic/></fig>?

[Melissa37]

But, since you brought up the idea of using s as panels of a figure, I think, that would fit better for the SourceData use case.

Humm, it came from Jeff, not me :-) and as a potentially solution to the issues we face, not seeing everything required.

I would personally warn against using graphic for Sourcedata - if you look at the content model on JATS there are far fewer options for graphic than fig and it could be limiting. For instance, permissions is not allowed, neither is disp-formula...

Just to make sure that I understood your sketch correctly: would it be wrong to presume, that a Figure Part could potentially consist of multiple 'panels', that means be something like a ?

I assumed that the SourceData project parts are a single panel and that's the point of them being split out?

eLife and SourceData are two edge cases and although we'd both like the world to take on our approaches, not happened so far! So I think it is almost 100% unlikely anyone would ever need to have figure suppls (aka eLife) and panels (ask SourceData) so for Texture it would be easiest to use the same content model for both?

[obuchtala]

Ok. Let's discuss later in the call.