MACROS___make_metadata

Dr Cyril, Pernet

unread,

Dec 14, 2021, 9:58:57 AM12/14/21

to bids-di...@googlegroups.com

Hey BIDS dev,

I totally get why we now use MACROS___make_metadata_table in our md
files, tables are such a joy to make :-)

However, I'd like to draw your attention to a few things

- higher barrier for anyone to create such md file

- sparse documentation about where to find or update yaml files (trying
to update the description of the 'reconstruction' table in
https://github.com/bids-standard/bids-specification/blob/master/src/04-modality-specific-files/09-positron-emission-tomography.md)

thx

cyril

Remi Gau

unread,

Dec 14, 2021, 11:00:36 AM12/14/21

to bids-di...@googlegroups.com, Dr Cyril, Pernet

Can you tell us what else we should put in the CONTRIBUTING to make it easer?

https://github.com/bids-standard/bids-specification/blob/master/CONTRIBUTING.md#using-macros

I believe this section also points to how the yml files of the schema are organized: https://github.com/bids-standard/bids-specification/blob/master/src/schema/README.md

We've tried to write some doc as we went, but I am sure it can be improved or made easier to find.

@+

Rémi

--

Rémi Gau

Kay Robbins

unread,

Dec 14, 2021, 11:57:54 AM12/14/21

to bids-di...@googlegroups.com, Dr Cyril, Pernet

Remi,

I think the Using macros section is nice, but I also agree with Cyril that macros are a bit daunting. (I personally would be hesitant to embarrass myself by trying to do a pull request using macros--- I would probably try to talk you into doing it for me :-)).

Here are a couple of observations:

In the Contributing link you sent:

This macro will create a table for the "SamplingFrequency" and "StartTime" metadata, filling the table with the content specified in their respective yaml files (see SamplingFrequency.yaml and StartTime.yaml).

The links are broken. I think it would be helpful to show what the table actually looks like after using the MACROS....

Remi Gau

unread,

Dec 14, 2021, 12:17:01 PM12/14/21

to bids-di...@googlegroups.com, Kay Robbins, Dr Cyril, Pernet

Cool !!

Thanks for feedback: too easy for maintainers to get tunnel vision.

Really helps to get a description of all the things that could be made clearer.

Will work on that.

On 14/12/2021 17:57, Kay Robbins wrote:

Remi,

I think the Using macros section is nice, but I also agree with Cyril that macros are a bit daunting. (I personally would be hesitant to embarrass myself by trying to do a pull request using macros--- I would probably try to talk you into doing it for me :-)).

Yup and for BEPs we have started to make it clear that this could be handled by maintainers, but maybe we should make it clear that this is not restricted to BEP.

Here are a couple of observations:

In the Contributing link you sent:

This macro will create a table for the "SamplingFrequency" and "StartTime" metadata, filling the table with the content specified in their respective yaml files (see SamplingFrequency.yaml and StartTime.yaml).

The links are broken.

oops! maybe we could extend out CI to pick up those.

I think it would be helpful to show what the table actually looks like after using the MACROS....

Agreed: I had the same thought when we re reading it.

Other questions that I had were :

What macros are available and what do they do? The

make_metadata_table seems to always have the same column names? What are these?

When is it appropriate to use the metadata table --- there are lots of other tables in the spec.

Should we create a macro if we need a new kind of table?

What other macros are available?

Whole Using macros may eventually need its own section. It is at a level of technicality that is well beyond what came before --- such as how to post an issue on GitHub.

Agreed on all of the above.

Another thing that might be useful is to split out the whole section on building the specs into a separate document and put a link. The description of that very complicated procedure splits up the discussion of putting tables in the spec and putting figures in. That section isn't listed in the table of contents.

Yes it will make it easier to browse because that document is starting to get a wee bit long.

I am not wedded to any of these suggestions, I'm just thinking about it as a perplexed user.

Much appreciated!! :-D

@+

Rémi

To view this discussion on the web visit https://groups.google.com/d/msgid/bids-discussion/SN6PR08MB496043152724F2F837FA9B5087759%40SN6PR08MB4960.namprd08.prod.outlook.com.

--

Rémi Gau

Remi Gau

unread,

Dec 15, 2021, 2:30:47 AM12/15/21

to bids-di...@googlegroups.com, Kay Robbins, Dr Cyril, Pernet

Whole Using macros may eventually need its own section. It is at a level of technicality that is well beyond what came before --- such as how to post an issue on GitHub.

Another thing that might be useful is to split out the whole section on building the specs into a separate document and put a link. The description of that very complicated procedure splits up the discussion of putting tables in the spec and putting figures in. That section isn't listed in the table of contents.

Quick thought on this

There is already quite a bit of redundancy in the docs / contributing across some of the BIDS repositories. While some others have no docs or contributing for such things as "how to open / review a pull request".

Could be useful to have one single Contributing in this repo that for the part that applies to all repositories, and then have more detailled docs for each repository according to their needs.

--

Rémi Gau

Dr Cyril, Pernet

unread,

Dec 15, 2021, 3:07:50 AM12/15/21

to Remi Gau, bids-di...@googlegroups.com, Kay Robbins

looks to me that the 1st thing is to explain how they work

some macro have the header of each table and thus it seems easy to fill - change, some others (like the one i want to change) do not meaning some contend is assembled automatically but we do not know where the different pieces are (and as the repo gets bigger it becomes harder to find)

-- 
Dr Cyril Pernet, PhD, OHBM fellow, SSI fellow
Neurobiology Research Unit, 
Building 8057, Blegdamsvej 9
Copenhagen University Hospital, Rigshospitalet
DK-2100 Copenhagen, Denmark

wamc...@gmail.com
https://cpernet.github.io/
https://orcid.org/0000-0003-4010-4632

Remi Gau

unread,

Dec 16, 2021, 6:07:18 AM12/16/21

to Dr Cyril, Pernet, bids-di...@googlegroups.com, Kay Robbins

Hey all,

We (members of the maintainers and steering group) quickly put together some doc on how to use macros: it is in this hackmd that you can edit and comment on.

https://hackmd.io/rpSwaxpuSOCNhK2Tf2F9Cw

Let us know if this is helpful and what needs further clarification.

@+

Rémi

--

Rémi Gau

Kay Robbins

unread,

Dec 16, 2021, 10:20:54 AM12/16/21

to Remi Gau, Dr Cyril, Pernet, bids-di...@googlegroups.com

This is a good start --- but maybe too friendly without enough info content. I'll make specific comments and suggestions on the document in the next couple of days. Thanks for starting this.....

In the meantime, I was hoping that someone might make a quick cleanup pass on the documentation in:

https://github.com/bids-standard/bids-specification/blob/master/tools/mkdocs_macros_bids/macros.py

Several of the macros (such as make_metadata_table) have some mismatches. I am assuming that all of these macros take a dictionary and not a list?

def make_metadata_table(field_info):

"""Generate a markdown table of metadata field information.

Parameters

----------

field_names : dict

A list of the field names.

From: Remi Gau <remi...@gmail.com>
Sent: Thursday, December 16, 2021 5:07 AM
To: Dr Cyril, Pernet <wamc...@gmail.com>; bids-di...@googlegroups.com <bids-di...@googlegroups.com>; Kay Robbins <Kay.R...@utsa.edu>
Subject: [EXTERNAL] Re: [EXTERNAL] Re: [bids-discussion] MACROS___make_metadata_table

**EXTERNAL EMAIL**
This email originated outside of The University of Texas at San Antonio.
Please exercise caution when clicking on links or opening attachments.

Hey all,

Reply all

Reply to author

Forward