Disallow file insertion in the middle of a paragraph within panel legend

[evabenitoembo]

How can one make it obvious that a file link can be inserted in the fig legend. Should it be only possible at the end of the caption. Inserting it in the middle does not make much sense a priori.

[michael]

As discussed during our demo, we think that having all supplementary files positioned globally and linked via xref to the panels, ist most elegant. Do you agree?

[source-data]

Not sure if I understand completelty. Is this idea to have a single list of data files that are each linked via xref to panesl? I am not sure the associaton between a specific file and a specific panel would be strong and clear enough. Will users understand that they can add a file linked to a specific panel? When seing a list of files in teh global list, will it be clear which one belongs to which panel? It seems just a xref link is tenuous.
It seemed nice to be able to have the choice to link a file within a panel. But maybe then position it by default at the end of the panel for clarity?

[michael]

@evabenitoembo @source-data

The reasoning behind is this:

• ability to reference a source data file from multiple figure panels (very common scenario is to view the same data set but from different angles, or using different plots)
• editing experience for such nested items is not good (caption becomes a complex editing container if we allow block level elements inside it)
• JATS does not allow supplementary-material inside a figure caption (that is only possible using a hack: wrapping the element inside a paragraph)

So we'd strongly recommend to put a resource somewhere, and reference it (one or multiple times). It's the same concept as a reference and citing a reference. We can derive the connection from the context (when xref is inside a figure panel caption, it belongs to that figure).

However, I agree that the 'visual' part of it could be stronger, but that's something you could solve on the presentation side of SourceData. If a stronger visual connection is required in the editor, we could possibly render a summary below the panel.

Also see Deborah A Lapeyre's comment (she's an architect for JATS).

[Melissa37]

Is this idea to have a single list of data files that are each linked via xref to panesl? I am not sure the associaton between a specific file and a specific panel would be strong and clear enough.

eLife use case does require some files to be associated with one component figure or main figure as it is source data to that specific figure and so it's not appropriate for it to be viewed elsewhere. So we will pursue the ability to add a supplementary file within a figure caption.
We can put in a request to JATS that supplementary-material tag be allowed within fig and I think the proposal will be accepted. It would not go into JATS 2.0 release.
@source-data if you have a use case for this request that would help - the JATS Standing Committee is more receptive to requests if there are more than one publisher requesting it with good and valid use cases.

@JGilbert-eLife @FAtherden-eLife for info

[michael]

Is this idea to have a single list of data files that are each linked via xref to panesl? I am not sure the associaton between a specific file and a specific panel would be strong and clear enough.

eLife use case does require some files to be associated with one component figure or main figure as it is source data to that specific figure and so it's not appropriate for it to be viewed elsewhere. So we will pursue the ability to add a supplementary file within a figure caption.
We can put in a request to JATS that supplementary-material tag be allowed within fig and I think the proposal will be accepted. It would not go into JATS 2.0 release.
@source-data if you have a use case for this request that would help - the JATS Standing Committee is more receptive to requests if there are more than one publisher requesting it with good and valid use cases.

@JGilbert-eLife @FAtherden-eLife for info

I'm down voting this JATS request.

My opinion: Not a good idea at all to squeeze supp files into a figure caption for reasons described in my previous comment. Convinced our tool and format is more future proof if we have supp files globally and link them to all the places where needed. It's the same discussion as with authors and affiliations, where we also decided to use xref, in order to be able to reuse them.

@Melissa37 when using xref, you still can render a figure on the website and also render the associated supp files inside it. It's a visual decision that can be made independently, this should not affect how we best represent content in TextureJATS.

[Melissa37]

@michael we need to have a call about this as I think it is probably going to be a baseline requirement for eLife that we cannot budge on. We should schedule a call soon. Does 11.30 next Monday work for you?

[michael]

@Melissa37 we can do that on Monday.

What strikes me really, is the question what would do you do if two figures use the same dataset / e.g. exact same CSV file? Create two copies of the same file? I think it is very common, to have a dataset and then different views (plots) for it. And it would be a pity if we didn't propose a solution that supports that.

[source-data]

In terms of visual rendering, I think it is absolutely essential to be able to closely associate a source data files to its respective panel. This is the core idea of the 'data-figure package' concept.

In terms of UI, users (=readers) should be able to identify and access the data in a single click and in the authoring mode (users=authors) they should be able to link a data file to a panel in an straighforward manner. A priori, using a reference to a dataset that appears in a list somwehere else would not be the most intuitive experience.

This would speak for a solution that visualizes the data set name/file/link, at the bottom of the legend of the said panel. I also think that this should be very clear in the authoring mode since our goal is to use this mechanism precisely to promote the notion of figure as data packages.

It is true that the scenario where the same dataset is 'viewed' in different figures or panels is common. It is however not more common that having one dataset for for one panel. So we should not see these as mutually exclusive scnenarios.

Whether xref covers this satisfactorily is harder to tell for me. Would we be happy to use xref for the illustration(s) or the caption(s) and would it be satisfactory to defer the decision to put these elements in a single container when rendering? Why would the illustration and the legend be more 'integral' to a figure than the actual data?

[michael]

In terms of UI, users (=readers) should be able to identify and access the data in a single click and in the authoring mode (users=authors) they should be able to link a data file to a panel in an straighforward manner. A priori, using a reference to a dataset that appears in a list somwehere else would not be the most intuitive experience.

you have all freedom on the display side.

It is true that the scenario where the same dataset is 'viewed' in different figures or panels is common. It is however not more common that having one dataset for for one panel. So we should not see these as mutually exclusive scnenarios.

In Texture we strive to have exactly one solution for a certain thing. And that solution should support all different use-cases. So in this case we are very keen to have one way to do it instead of two. It creates a lot of friction.

Imagine the following scenario:

• user adds a dataset to panel A
• user wants to assign that dataset to panel B as well

To solve this they have to do:

• remove dataset from panel A
• add it globally
• reference it in panel A and B

In the other case, you always do the same flow:

• create dataset
• link dataset (as often as you wish)

[source-data]

"you have all freedom on the display side": in theory maybe. In practice, it is a bit more limited. If there is a too large disconnect between the authoring side and the core concept that we want to implement, and the 'display' side (which may not even exist in our case since the dar archive might be share as is), then it is a sign there is an issue that might need extra-attention. I do think that the rendering in the authoring mode has to match reasonably well with the core concept and we would be keen to find an acceptable solution for the core concept of figure-data package.

I take your point with the 1-to-many relationship between dataset and figures and your example is a good illustration.

Now, the rule of having 1 solution for 1 thing is only wise as long as the 1 thing is indeed 1 thing and not 2 things. Maybe this decision is not super clear in this case.

There are panel-level datasets, figure-level datasets and paper-level dataset. We have implemented the three in SourceData because it is just the reality of what authors produce and how they analyse data.. In cell and molecular biology, the vast majority of figure panels represent 1 coherent experiemtn whithin which data points/measurements can be meaningfully compared. In my view this is the most fundamental level and this is what we like to call "source data" because it is really the source data behind the figure. In this case, there is usually a 1-to-1 association and it reflects how the science is being done. Experiment 1, figure 1A, conclusion 1A. Experiment 2, figure 1B, conclusion 1B. etc....
Now it is equally true that in other fields, eg genomics, systems biology etc..., there is a large dataset that is analyzed and dissected in multiple ways. IN this case dataset 1 is shown under this angle in figure 1A and under this analysis pipeline in figure 1B.

So, is this 1 thing or 2 things? If we impose a workflow based on paper-level datasets to users who have dozens of figure-level or panel-level dataset, maybe we have 1 solution but for these user it is a massive unintuitive friction. But I also take your point that if we impose a solution based on figure-level association for paper-level datasets, then we create another set of frictions. In my view, from the point of view of UI/Ux this would argue for 2 things. Maybe a unified underlying implementation is fine, but still, some clarity in the UI would be important. Maybe one can distinguish this in terms of how to 'create' the figure-data assoction form how to visualize it (in the authoring tool!) once the association has been made?

[evabenitoembo]

See my comment in #1141 , let us elaborate on this in a separate call if ok with everyone?

[michael]

So, is this 1 thing or 2 things?

Since it can be represented with one concept, powerful enough to cover all cases I'd say 1 thing.

Maybe a unified underlying implementation is fine, but still, some clarity in the UI would be important. Maybe one can distinguish this in terms of how to 'create' the figure-data assoction form how to visualize it (in the authoring tool!) once the association has been made?

That's something we can discuss of course. We just need to make sure we don't make an arbitrary decision, so that other Texture users would be bothered. A generated "Files" summary underneath the caption I could imagine. Like this:

@Melissa37 is this also something that could help in eLife's case. In addition to putting the main supp files into a section that is not rendered eventually on the eLife website. So as a reader you see the files only in the context of a figure. Still, I don't get why you wouldn't want to have a section with a complete list of source data files to browse?

@Melissa37 @evabenitoembo maybe we could do a call all together? What do you think?

[obuchtala]

Thanks for all your input!

For our call I see two alternatives that we should discuss:

1. xref and a dedicated display.
2. in-place supplementary files in captions.

The first is the more general approach and does not introduce a new concept (also no JATS change needed).
The latter is probably more natural in specific cases, but demands for a new concept and raises questions as @michael has pointed out here: #1142 (comment).

Is there a way to make the first more user-friendly? E.g. inserting a supplementary file inside a caption creates a file and an xref at once? ... with the effect of being displayed as @michael proposed.

[obuchtala]

I want to add another twist to my previous comment, in response to

Why would the illustration and the legend be more 'integral' to a figure than the actual data?

This suggests that data are an alternative representation of the illustration. JATS has a concept for that: <alternatives>. See https://jats.nlm.nih.gov/archiving/tag-library/1.1/element/alternatives.html
A supplementary file can exist as an alternative to a graphic. This would be 1-to-1.

UX-wise, this would not be like adding a supplement to the caption, but providing a file as an alternative for the image.

Just to put everything onto the table.

[obuchtala]

@dalapeyre what is your take on my last suggestion?

[obuchtala]

Just for the records: the ability to add alternatives for content has been requested in other situations:

• Tables as images: Ability to use an image as table #1168
• Equations as images: Allow disp-formula as image #1011

[dalapeyre]

On Feb 12, 2019, at 6:32 PM, Oliver Buchtala ***@***.***> wrote: Just for the records: the ability to add alternatives for content has been requested in other situations: • #1168 • #1011 — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub, or mute the thread.

These are for table as image and disp-formula as image. I have asked the JATS Standing Committee to either: - Add table, disp-formula, block-text, etc. to <alternatives> OR - to add a block-level alternatives element that can hold these block objects. Either will take care of your problem. JATS SC is meeting this Thursday, but may not get to this request on the list. —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]

I like using <alternatives> Supplementary material inplace in a paragraph, caption, or similar seems awful to me. Cannot justify that, just an irrational semantic revulsion. —Debbie

On Feb 12, 2019, at 6:14 PM, Oliver Buchtala ***@***.***> wrote: @dalapeyre what is your take on my last suggestion? — 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 ================================================================

[michael]

Thank you @dalapeyre. Agre that, if we decide supp files need to be nested under a figure, I'd also prefer to have them in a separate container and not mashed into the caption.

However, that still leaves us with two different concepts/editing workflows:

1. figure-scoped supp file (stored in alternatives)
2. supp file globally and linked multiple times via xref

[evabenitoembo]

@michael @Melissa37 , can you confirm you are having a call today at 11.30? Ok for us to join in, since also relevant to us? Thanks!

[Melissa37]

Hi there

we had no confirmation that there was going to be a call and we've scheduled an internal meeting to discuss this in that slot now. Sorry!

[evabenitoembo]

Hi @Melissa37 , thanks for the quick feedback! No worries! We were also not sure whether this was formally scheduled.

Should we try to schedule a call with the 3 parties for some time this week then? How about Thursday or Friday sometime between 9am-12am? Or alternatively @michael , @Melissa37 , please suggest available time slots for you. We are relatively flexible this week.

[Melissa37]

Hi @evabenitoembo @michael @source-data

We've discussed this internally and have a plan:

1. Approaching editorial first off to discuss the way we handle source data in general DONE
2. Generate user stories - we'd like to do this with Source data so we have a common starting point
3. Share user stories with Debbie and Jeff from JATS - so they have a clear understanding of all requirements and could theorise a good JATS tagging

How does this sound to everyone?

@JGilbert-eLife @FAtherden-eLife

[dalapeyre]

Good to me. —dal

…

On Feb 19, 2019, at 1:46 AM, Melissa Harrison ***@***.***> wrote: Hi @evabenitoembo @michael @source-data We've discussed this internally and have a plan: • Approaching editorial first off to discuss the way we handle source data in general • Generate user stories - we'd like to do this with Source data so we have a common starting point • Share user stories with Debbie and Jeff from JATS - so they have a clear understanding of all requirements and could theorise a good JATS tagging How does this sound to everyone? @JGilbert-eLife @FAtherden-eLife — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub, or mute the thread.

[michael]

Openend a dedicated feature ticket for this topic. Let's continue discussion there. #1245