Allow additional information in metadata.yaml

[slochower]

Based on some of the points already discussed on deep review and greenelab/meta-review#75 (comment), I think adding a few additional variables to the metadata would help Manubot be a little more flexible. Some ideas of what we might want to allow:

• Address information (in addition to affiliation)
• Corresponding author status
• First/co-first author status
• Specification of author symbol

For the last three, I think we could implement sensible defaults in the jinja template to use if not specified. For example, corresponding author status may be set to "no" unless it is explicitly set to "yes."

[agitter]

This relates to some early discussion in #7 and #10. The debate before was whether some annotations are common enough to warrant special support or whether the authors should be add custom annotations with symbols. Co-first and corresponding annotations seem fairly common to me. Other annotations (current address, co-second author, deceased, etc.) are infrequent, but may be a good reason for general symbol support.

Now that we've moved to yaml instead of tsv for author metadata, I'm more supportive of including optional attributes like corresponding. As @slochower says, they could be ignored by default.

[agitter]

This could also be a good time to re-assess whether we want to make the affiliations field mandatory. That would allow us to automatically check whether the affiliations were provided correctly.

[slochower]

This could also be a good time to re-assess whether we want to make the affiliations field mandatory.

And consider having an option for condensing multiple affiliations into one symbol?

My general thinking is that as many things that journals might "require" should be configured via flags like condense_affiliation: yes in the yaml file so that changing a manuscript to resubmit to another journal would only require changing things in content/ and not editing the python. Do you agree?

[agitter]

I agree that it would be better to make manuscripts configurable with the yaml instead of editing the Manubot source. Some of these changes would require Manubot changes. Others, like symbols, would be easier and could be demonstrated with updates to Manubot rootstock alone.

[dhimmel]

This could also be a good time to re-assess whether we want to make the affiliations field mandatory. That would allow us to automatically check whether the affiliations were provided correctly.

We could start enforcing certain YAML fields using a schema as discussed in #126 (comment). However, I am not necessarily in favor of this as it adds considerable complexity. However, it would be a standardized way for ensuring certain fields are set, without having to modify the manubot python source code. In other words, it allows different manuscripts to require different fields.

I think adding a few additional variables to the metadata would help Manubot be a little more flexible.

There is nothing preventing manuscripts from adding additional fields to their metadata.yaml. The question is whether a field is general purpose enough that we should add it as a standard & default to setting it in the manubot-rootstock example metadata.yaml. For example, you could add an additional mapping field like affiliation_to_address, if you would like to be tracking that information to make journal submission easier. In general I think we should have a high bar for any change that creates additional maintenance and overhead for all manuscripts for the benefit of a few.

@slochower, you seem to be interested in making the Manubot frontmatter match the style of a specific journal. In my experience, that's not neccessary. All of the information to populate the journal frontmatter is provided to the submission system, and is not actually generated from the submitted manuscript document. Hence it doesn't matter whether the corresponding author or addresses are displayed in the manubot output as they will be entered elsewhere in the submission system. Am I wrong here?

The reason I avoided putting addresses and corresponding information in the default frontmatter is that I was envisioning the paper of the future. Addresses are irrelevant IMO (expect for some rare circumstances). Corresponding authorship is sometimes important, but often does more harm then good. We want to encourage interested readers to communicate by opening GitHub Issues rather than emailing a single author.

The Deep Review uses an alternative frontmatter, which is more traditional and is more amenable to the features @slochower is interested in. To accommodate corresponding authors & other symbols as well as affiliation addresses, we could think about making this more accessible via manubot-rootstock.

[agitter]

To accommodate corresponding authors & other symbols as well as affiliation addresses, we could think about making this more accessible via manubot-rootstock.

Adding an example of frontmatter symbols to manubot-rootstock would be a small change that doesn't require additional maintenance. It also provides a lot of flexibility for whatever field-specific annotations an author finds important.

[slochower]

@slochower, you seem to be interested in making the Manubot frontmatter match the style of a specific journal.

I'm actually not trying to make the frontmatter match a specific journal. On the contrary: I want Manubot to be able to match a bunch of "common" journal requirements (of course we can debate what is "common," as @agitter mentioned -- I'm not talking about dozens of options here, just a few common ones). I've lost a lot of time reformatting documents for different journals. If I have to muck around in the code when I need to submit to a different journal, I've just replaced time messing with Word documents with time spent writing and testing the Python. Does that make sense?

Edit: updated a few more points below.

Hence it doesn't matter whether the corresponding author or addresses are displayed in the manubot output as they will be entered elsewhere in the submission system. Am I wrong here?

I'm not sure how to say this other than... I've encountered an obtuse editor that gave a paper back to me to be reformatted with the journal's arcane template before even sending the paper out to reviewers, despite filling in the form information correctly.

The reason I avoided putting addresses and corresponding information in the default frontmatter is that I was envisioning the paper of the future. Addresses are irrelevant IMO (expect for some rare circumstances). Corresponding authorship is sometimes important, but often does more harm then good. We want to encourage interested readers to communicate by opening GitHub Issues rather than emailing a single author.

I agree philosophically.

[dhimmel]

Noting that 9504aa7 adds support for author.corresponding in metadata.yaml.