support for additional author information and contribution role

[jcolomb]

research object have a specific way to give information about the authors. (affiliations required, optional orcid id, contribution role, funding information, contact information,...)

Some work has been done at https://github.com/jam-schema/jams/, but the project is not yet applicable.
pinging @cderv who knows about it.

[cderv]

Hi @jcolomb !

Yes I believe we plan to tackle this and JAMS is in our radar. Was there another iteration after first prototype https://github.com/jam-schema/jams/blob/master/prototype_v1_JC.yml

I think there was no meeting since last June on this. Hopefully our thinking on this for Quarto will help the working group

For reference, related issue in rticles rstudio/rticles#324

[jcolomb]

There is a PR waiting for review (testing some examples brought some new insights) but not much done indeed since last September (I had a crazy grant writing end of the year). Will try to get things going again soon (also talking to the software citation group at force11).

[jjallaire]

@jcolomb Wondering how JAMS does or does not dovetail w/ the metadata schema used by Pandoc for JATS? (https://pandoc.org/jats.html). That seems to cover similar ground and and relational structure between author and affiliations.

@tarleb I know you have been involved in both JAMS and the Pandoc JATS work, what is your take on this?

[tarleb]

I've grown quite happy with the way JATS structures metadata, generally speaking. It's one of the more important output formats for me right now, so I aim for that schema and adjust the other templates to work with that metadata structure.

Names are the most basic, most important, and possibly the hardest to handle correctly. We wrote a little filter to normalize names, the structure could be described as bastardization of JATS and CSL-JSON. The JATS template requires a few adjustments to support it, most notably handling of particles like van or della. Here's the current state of the documentation (work in progress – names are messy). I'd be happy to bring filter and docs into a state that'd make it easy to use in other projects. And feedback welcome, of course!

Writing down my thoughts on other author properties, roles, and affiliations would take a little longer. The gist is that, IMHO, author convenience should be prioritized over purity, as long as we can convert metadata to a JATS compatible format. E.g., document authors should be able to put their ORCID right next to their name and have it picked up by the system.

Cc @arfon

[jjallaire]

Yes, we definitely want to be able to parse a wide variety of metadata inputs (including simple strings or strings array with full names all the way up to full JATS-style metadata). Or as you said something simple like this:

author: 
  - name: Tim Bray
    orcid: https://orcid.org/0000-0001-8886-5356
  - name: Yihui Xie
    orcid: https://orcid.org/0000-0003-0645-5666

Or alternatively:

author: 
  - given-names: Tim
    surname: Bray
    orcid: https://orcid.org/0000-0001-8886-5356
  - given-names: Yihui
    surname: Xie
    orcid: https://orcid.org/0000-0003-0645-5666

The same sort of thing of course for affiliations.

These should all be transformed into a uniform structure that templates can rely on.

[jcolomb]

About names complexity, this blogpost seems to be a good start: https://www.kalzumeus.com/2010/06/17/falsehoods-programmers-believe-about-names/ :)

For getting info from orcid, you may have a look at https://colomb.shinyapps.io/contributorlist_creator/, its current output is a tenzing spreadsheet to be used by https://tenzing.club, to create text outputs (but the goal is to use the jams schema in both tools and get jatsxml in the end).

Jams goals was/is to get a standard to allow for the recycling of author information from any source to any output, so the convenience can come with a simpler yaml for input (but this may mean not all use case are compatible), or tools to create jams (for example the tenzing spreadsheet may be used for most use cases).

It seems jams would be a perfect place to continue the discussion ?
Join jams by putting some info here
By the way, we will try to get a meeting in 2 weeks, as I already sent the email, see here a direct link to the poll

[Aariq]

Forgive me if my comment is out of place (I have no idea what JAMS or JATS are), but it would also be nice to be able to specify multiple affiliations. For example, in the way that the pandoc scholarly-metadata and author-info-blocks LUA filters work:

---
title: "Full Title"
shorttitle: "Running Title"
author:
  - Eric Scott:
      email: myemail@institute.edu
      institute: [UF]
      correspondence: true
  - Author Two:
      email: secondperson@university.edu
      institute: [UF, ExU]
      correspondence: false
      
institute:
  - UF: University of Florida, Gainesville, Florida 32611-0430 USA
  - ExU: Example University 123 Center Avenue, New York, New York 10027 USA
output: 
    bookdown::word_document2:
      pandoc_args:
      - --lua-filter=templates/scholarly-metadata.lua
      - --lua-filter=templates/author-info-blocks.lua
---

This YAML header produces Word output that looks like:

I tried translating this over to Quarto and couldn't get it to render correctly. It would be nice to have native support for multiple affiliations without the LUA filters, or some guidance on how to make these LUA filters work with a Quarto doc.

[dragonstyle]

We are definitely working on this now, though I haven't yet gotten to word doc specific support (is this what you're looking for?). We will soon document a pretty standard way to address authors (including multiple affiliations and a variety of relevant metadata) and a mechanism that allows you to either use existing templates that target specific outputs (e.g. an Elsevier journal PDF/LaTeX) or to provide custom templates/template partials to customize output yourself. We're getting pretty close to documenting support for this.

In the meantime, can you give us some information about what isn't working with Quarto? Those filters should, in general, work fine with Quarto as it stands.

[Aariq]

If I translate this YAML to Quarto then I get an error when rendering. I assume I'm probably just doing something wrong with the YAML syntax?

---
title: "Full Title"
shorttitle: "Short Title"
author: 
  - name: "Eric R. Scott"
    institute: 
      - UF_WEC
    email: "scottericr@gmail.com"
    correspondence: true
  - name: "Author Two"
    institute: 
      - UF_WEC
      - affiliation2
    email: "email@university.edu"
    correspondence: false
institute: 
  - UF_WEC: "Department of Wildlife Ecology and Conservation, University of Florida, Gainesville, Florida 32611-0430"
  - affiliation2: "Department of Ecology, Evolution and Environmental Biology, Example University 123 Center Avenue, New York, New York 10027 USA"
filters: 
  - build/scholarly-metadata.lua
  - build/author-info-blocks.lua
  - quarto
---

ERROR: Validation of YAML front matter failed.
ERROR: In file quarto-manuscript.qmd
(line 17, columns 5--117) Array entry 1 with value UF_WEC: "Department of Wildlife Ecology and Conservation, University of Florida, Gainesville, Florida 32611-0430" failed to be a string.
16: institute: 
17:   - UF_WEC: "Department of Wildlife Ecology and Conservation, University of Florida, Gainesville, Florida 32611-0430"
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
18:   - affiliation2: "Department of Ecology, Evolution and Environmental Biology, Example University 123 Center Avenue, New York, New York 10027 USA"
✖ The value UF_WEC: "Department of Wildlife Ecology and Conservation, University of Florida, Gainesville, Florida 32611-0430" is object.
ℹ The error happened in location institute:0.

ERROR: In file quarto-manuscript.qmd
(line 18, columns 5--146) Array entry 2 with value affiliation2: "Department of Ecology, Evolution and Environmental Biology, Example University 123 Center Avenue, New York, New York 10027 USA" failed to be a string.
17:   - UF_WEC: "Department of Wildlife Ecology and Conservation, University of Florida, Gainesville, Florida 32611-0430"
18:   - affiliation2: "Department of Ecology, Evolution and Environmental Biology, Example University 123 Center Avenue, New York, New York 10027 USA"
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
19: filters: 
✖ The value affiliation2: "Department of Ecology, Evolution and Environmental Biology, Example University 123 Center Avenue, New York, New York 10027 USA" is object.
ℹ The error happened in location institute:1.

ERROR: Render failed due to invalid YAML.

[mistune]

If I translate this YAML to Quarto then I get an error when rendering. I assume I'm probably just doing something wrong with the YAML syntax?
...
ERROR: Render failed due to invalid YAML.

@Aariq Were you able to multiple authors working already?

[dragonstyle]

We have finished up documenting the 1.0 support for normalized author and affiliations, documented here:

https://quarto.org/docs/journals/authors.html

We also support replacing title rendering for LaTeX and HTML pretty easily, which should allow pretty custom formatting of authors and affiliations, documented here:

https://quarto.org/docs/journals/templates.html

[tarleb]

Great news, this looks excellent! 🥳

[mistune]

If I am actually following this guide correctly, the way I would access variables under the author structure inside my LaTeX template, like take for example, the author's email would be author.email. The resulting .tex file does not return the value of author.email. Am I missing something? I am currently on v1.0.36.

[dragonstyle]

How are you referring to them? They are primarily intended to be accessible to custom templates or LUA filters (though they are available in metadata and so could theoretically be accessed using {{<meta >}} syntax, since they contain lists of authors and affiliations and shortcodes do not support iteration, they aren't really useful without you doing a bit more work.

[mistune]

Hello @dragonstyle , I am not well versed with pandoc but let me try answering your question. I'm using a custom template using the template file here. The pandoc guide on metadata blocks does not show how to use {{<meta >}} syntax. If you could refer me to readings on this, that would be great.

Please take a look at the metadata and the output I am getting.

Sample metadata:

title: Test Title
classoption: conference
papersize: a4paper
fontsize: 10pt
bibliography: C:/custom/bibliography.bib
biblio-style: numeric
csl: D:/ieee/bibliography.csl
author:
  - name: ZeroCommits
    affiliation: ZeroCommits Inc.
  - name: SinglePush
    email: singlepush@zerocommits.com
keywords:
  - one
  - two
  - three
abstract: |
  This is the abstract.
format:
  pdf:
    pdf-engine: lualatex
    toc: false
    numbersections: true
    colorlinks: true
    mainfont: STIX Two Text
    monofont: Source Code Pro
    sansfont: Source Sans 3
    mathfont: XITS Math
    cite-method: biblatex
filters:
  - quarto

I refer to the variables using the template file.

Accessing the author name via author.name does not seem to work. I just used author instead.

Quarto is executed using the following:

set pandocArgs=--standalone --template=D:\ieee\template.latex
quarto render myfilename.qmd %pandocArgs%

Here is a screenshot of the resulting pdf.

[dragonstyle]

Ok thanks for the detailed summary! You're doing exactly the right things, the one hitch I think is that Quarto is automatically parsing the author metadata into a structure that you can / should use in the template (rather then reading the raw author data). Quarto does this so that users can learn just one way to write authors and affiliations rather than having to learn a new way for each type of template that they use. I haven't had a chance to run this, but here is a sample that I think should do what you're trying to do, but using the normalized schema that Quarto produces:

\author{
$for(by-author)$
  \IEEEauthorblockN{$by-author.name.literal$}
  \IEEEauthorblockA{%$for(by-author.affiliations/first)$
    $it.name$ \\
    $it.country$ \\$endfor$ 
    $by-author.email$}
  $sep$ \and
$endfor$ }

Details of the author schema are here (we provide a couple of different structures for the author data designed to make it easier to author templates):

https://quarto.org/docs/journals/authors.html

[mistune]

@dragonstyle Thanks so much for the explanation and example. This works now. :)