From 72ac635369d07716698ef50c77f38e0eaf1361e0 Mon Sep 17 00:00:00 2001 From: Remi Gau Date: Fri, 6 Dec 2024 09:19:02 +0100 Subject: [PATCH] [ENH] improve metadata pages (#580) --- docs/collaboration/contributors.md | 192 +++--- docs/faq/general.md | 4 +- .../folders_and_files/metadata.md | 593 ------------------ .../folders_and_files/metadata/index.md | 11 + .../folders_and_files/metadata/json.md | 472 ++++++++++++++ .../folders_and_files/metadata/tsv.md | 137 ++++ .../getting_started/resources/dependencies.md | 2 - docs/getting_started/resources/glossary.md | 4 +- mkdocs.yml | 8 +- temp/participants.tsv | 3 + tmp.py | 10 + 11 files changed, 715 insertions(+), 721 deletions(-) delete mode 100644 docs/getting_started/folders_and_files/metadata.md create mode 100644 docs/getting_started/folders_and_files/metadata/index.md create mode 100644 docs/getting_started/folders_and_files/metadata/json.md create mode 100644 docs/getting_started/folders_and_files/metadata/tsv.md create mode 100644 temp/participants.tsv create mode 100644 tmp.py diff --git a/docs/collaboration/contributors.md b/docs/collaboration/contributors.md index 81b2af7e..dd889650 100644 --- a/docs/collaboration/contributors.md +++ b/docs/collaboration/contributors.md @@ -27,274 +27,256 @@ Thanks goes to these wonderful people. Adeen Flinker
Adeen Flinker
πŸ“– Adina S. Wagner
Adina S. Wagner
🎨 πŸ’» Agah Karakuzu
Agah Karakuzu
πŸ’¬ πŸ“– πŸ”£ πŸ€” πŸ’» - Agnese Zazio
Agnese Zazio
πŸ“– + Aki Nikolaidis
Aki Nikolaidis
πŸ“– - Aki Nikolaidis
Aki Nikolaidis
πŸ“– Alberto Lazari
Alberto Lazari
πŸ“– Alejandro de la Vega
Alejandro de la Vega
πŸ› πŸ’» ⚠️ Alessio Giacomel
Alessio Giacomel
πŸ“– Alex Rockhill
Alex Rockhill
πŸ“– πŸ”§ πŸ’» Alexander Jones
Alexander Jones
πŸ’» πŸ› Alexander L. Cohen
Alexander L. Cohen
πŸ› πŸ’» πŸ“– πŸ’¬ + Alexander von Lautz
Alexander von Lautz
πŸ“– - Alexander von Lautz
Alexander von Lautz
πŸ“– Alexandre Gramfort
Alexandre Gramfort
πŸ“– πŸ’‘ Alexandre Hutton
Alexandre Hutton
πŸ“– Alexandre Routier
Alexandre Routier
πŸ“– Alexandru Foias
Alexandru Foias
πŸ“– πŸ”£ Ali Khan
Ali Khan
πŸ“– Alizee Wickenheiser
Alizee Wickenheiser
πŸ”§ + Ana Fouto
Ana Fouto
πŸ““ - Alyssa Dai
Alyssa Dai
πŸ’» - Amber Hopkins
Amber Hopkins
πŸ“– - Ana Fouto
Ana Fouto
πŸ““ Anders Eklund
Anders Eklund
πŸ“– πŸ“’ πŸ’» Andrea Pigorini
Andrea Pigorini
πŸ“– Andrew Hoopes
Andrew Hoopes
πŸ“– Andrew Jahn
Andrew Jahn
πŸ““ - - Andrew Janke
Andrew Janke
πŸ“– πŸ’» Anibal SΓ³lon
Anibal SΓ³lon
πŸ’» πŸ› Anthony Galassi
Anthony Galassi
πŸ“– πŸ’» + + Arianna Sala
Arianna Sala
πŸ“– Ariel Rokem
Ariel Rokem
πŸ“– πŸ’» Arjen Stolk
Arjen Stolk
πŸ“– - Arman Jahanpour
Arman Jahanpour
πŸ’» - - Arnaud Delorme
Arnaud Delorme
πŸ“– πŸ’‘ πŸ€” Arnaud Marcoux
Arnaud Marcoux
πŸ“– Arshitha Basavaraj
Arshitha Basavaraj
πŸ“– πŸš‡ πŸ’» Ashley G. Gillman
Ashley G. Gillman
πŸ“– + + Athanasia Monika Mowinckel
Athanasia Monika Mowinckel
πŸ“– Aysegul Gunduz
Aysegul Gunduz
πŸ“– Azeez Adebimpe
Azeez Adebimpe
πŸ“– - - B. Nolan Nichols
B. Nolan Nichols
πŸ“– Balint Kincses
Balint Kincses
πŸ“– Benjamin Beasley
Benjamin Beasley
πŸ“– Benjamin Dichter
Benjamin Dichter
πŸ“– πŸ’» ⚠️ + + Benjamin Gagl
Benjamin Gagl
πŸ“– Bertrand Thirion
Bertrand Thirion
πŸ“– Bradley Voytek
Bradley Voytek
πŸ“– - - - Brent McPherson
Brent McPherson
πŸ’» Brett L. Foster
Brett L. Foster
πŸ“– Brian A. Wandell
Brian A. Wandell
πŸ“– Brian N. Lundstrom
Brian N. Lundstrom
πŸ“– Camille Maumet
Camille Maumet
πŸ“– - Carlo Miniussi
Carlo Miniussi
πŸ“– - Cecile Madjar
Cecile Madjar
πŸ”£ πŸ”§ + Carlo Miniussi
Carlo Miniussi
πŸ“– + Cecile Madjar
Cecile Madjar
πŸ”£ πŸ”§ ChloΓ© Pasturel
ChloΓ© Pasturel
πŸ“– Chris Benjamin
Chris Benjamin
πŸ“– Chris GahnstrΓΆm
Chris GahnstrΓΆm
πŸ“– Chris Holdgraf
Chris Holdgraf
πŸ“– πŸ€” πŸ’» Chris J. Gorgolewski
Chris J. Gorgolewski
πŸ“– πŸ’» πŸ’¬ πŸ€” πŸ” πŸ“’ πŸ“ πŸ’‘ πŸ”Œ - Chris Rorden
Chris Rorden
πŸ“– πŸ’» - Christian BΓΌchel
Christian BΓΌchel
πŸ“– + Chris Rorden
Chris Rorden
πŸ“– πŸ’» + Christian BΓΌchel
Christian BΓΌchel
πŸ“– Christian Horea
Christian Horea
πŸ’» πŸ“– - Christine Rogers
Christine Rogers
πŸ”£ πŸ“– πŸ€” πŸš‡ πŸ”§ + Christine Rogers
Christine Rogers
πŸ”£ πŸ“– πŸ€” πŸš‡ πŸ”§ Christophe Phillips
Christophe Phillips
πŸ“– Christopher J. Honey
Christopher J. Honey
πŸ“– Christopher J. Markiewicz
Christopher J. Markiewicz
πŸ’¬ πŸ› πŸ’» πŸ“– 🎨 πŸ’‘ πŸ€” πŸ”Œ πŸ‘€ πŸ”§ πŸ“’ πŸ”£ πŸ“‹ 🚧 - Christopher Lee-Messer
Christopher Lee-Messer
πŸ“– - Clara Moreau
Clara Moreau
πŸ“– + Christopher Lee-Messer
Christopher Lee-Messer
πŸ“– + Clara Moreau
Clara Moreau
πŸ“– Clint Hansen
Clint Hansen
πŸ“– πŸ€” Cyril Pernet
Cyril Pernet
πŸ’¬ πŸ“ πŸ“– 🎨 πŸ’‘ πŸ“‹ πŸ€” πŸ“’ Cyrus Eierud
Cyrus Eierud
πŸ“– D. Sturgeon
D. Sturgeon
πŸ’» Dan Levitas
Dan Levitas
πŸ“– - Dan Lurie
Dan Lurie
πŸ€” πŸ“– πŸ”§ πŸ”Œ πŸ’» πŸ’¬ - Daniel A. Handwerker
Daniel A. Handwerker
πŸ“– + Dan Lurie
Dan Lurie
πŸ€” πŸ“– πŸ”§ πŸ”Œ πŸ’» πŸ’¬ + Daniel A. Handwerker
Daniel A. Handwerker
πŸ“– David Alsop
David Alsop
πŸ“– David Boas
David Boas
πŸ“– David Groppe
David Groppe
πŸ“– David Keator
David Keator
πŸ“– David McAlpine
David McAlpine
πŸ“– - David Thomas
David Thomas
πŸ“– πŸ”£ - Dejan Draschkow
Dejan Draschkow
πŸ“– - Desmond Oathes
Desmond Oathes
πŸ“– + David Thomas
David Thomas
πŸ“– πŸ”£ + Dejan Draschkow
Dejan Draschkow
πŸ“– Dianne Patterson
Dianne Patterson
πŸ“– Dimitri Papadopoulos Orfanos
Dimitri Papadopoulos Orfanos
πŸ“– πŸ’‘ πŸ€” πŸ’¬ πŸ’» Dmitry Petrov
Dmitry Petrov
πŸ“– πŸ’» Dora Hermes
Dora Hermes
πŸ“– πŸ’» βœ… πŸ” πŸ€” Dorien Huijser
Dorien Huijser
πŸ“– - Dorota Jarecka
Dorota Jarecka
πŸ’» πŸ“– Douglas N. Greve
Douglas N. Greve
πŸ“– Duncan Macleod
Duncan Macleod
πŸ“– πŸš‡ Dung Truong
Dung Truong
πŸ“– πŸ’» πŸ”§ πŸ€” - Dustin Moraczewski
Dustin Moraczewski
πŸ“– Dylan Nielson
Dylan Nielson
πŸ“– πŸ’» πŸ”§ Eduard Ort
Eduard Ort
πŸ“– πŸ’» Eleonora Marcantoni
Eleonora Marcantoni
πŸ“– + Elizabeth Bock
Elizabeth Bock
πŸ“– πŸ’‘ - Elizabeth Bock
Elizabeth Bock
πŸ“– πŸ’‘ Elizabeth DuPre
Elizabeth DuPre
πŸ“– πŸ’‘ πŸ” πŸ€” πŸ’¬ πŸ’» Elke Warmerdam
Elke Warmerdam
πŸ”£ πŸ“– Erdal Karaca
Erdal Karaca
πŸ’» Eric A. Earl
Eric A. Earl
πŸ“– πŸ’¬ πŸ› 🚧 πŸ”§ πŸ€” πŸ’» Eric Achten
Eric Achten
πŸ“– πŸ”£ πŸ““ Eric Bridgeford
Eric Bridgeford
πŸ“– πŸ”§ + Erin W. Dickie
Erin W. Dickie
πŸ“– πŸ€” πŸ‘€ πŸ“’ πŸ’¬ πŸ’» - Erin W. Dickie
Erin W. Dickie
πŸ“– πŸ€” πŸ‘€ πŸ“’ πŸ’¬ πŸ’» Ethan Blackwood
Ethan Blackwood
πŸ‘€ πŸ“– Eugene P. Duff
Eugene P. Duff
πŸ“– Ezequiel Mikulan
Ezequiel Mikulan
πŸ“– πŸ’» Felipe Orihuela-Espina
Felipe Orihuela-Espina
πŸ“– Fidel Alfaro Almagro
Fidel Alfaro Almagro
πŸ’¬ πŸ“– πŸ’‘ πŸ”Œ Filip Szczepankiewicz
Filip Szczepankiewicz
πŸ“– + Filippo Maria Castelli
Filippo Maria Castelli
πŸ“– πŸ”£ - Filippo Maria Castelli
Filippo Maria Castelli
πŸ“– πŸ”£ Franco Pestilli
Franco Pestilli
πŸ“– πŸ’» 🎨 πŸ’‘ πŸ€” πŸ‘€ πŸ”§ πŸ“‹ πŸ” πŸš‡ πŸ“’ Franklin W. Feingold
Franklin W. Feingold
πŸ“‹ πŸ“ βœ… πŸ’¬ πŸ€” 🎨 πŸ“’ πŸ‘€ πŸš‡ πŸ–‹ πŸ“† πŸ’» FranΓ§ois Tadel
François Tadel
πŸ“– πŸ”Œ πŸ’‘ Gaia Rizzo
Gaia Rizzo
πŸ“– Gang Chen
Gang Chen
πŸ“– GaΓ«l Varoquaux
GaΓ«l Varoquaux
πŸ“– + Ghislain Vaillant
Ghislain Vaillant
πŸ’» - Ghislain Vaillant
Ghislain Vaillant
πŸ’» Giacomo Bertazzoli
Giacomo Bertazzoli
πŸ“– Giacomo Guidali
Giacomo Guidali
πŸ“– Giacomo Mazzamuto
Giacomo Mazzamuto
πŸ“– πŸ”£ Gilles de Hollander
Gilles de Hollander
πŸ“– Gio Piantoni
Gio Piantoni
πŸ“– - Giovanna Nordio
Giovanna Nordio
πŸ“– - - Gitte M. Knudsen
Gitte M. Knudsen
πŸ“– Giulio Castegnaro
Giulio Castegnaro
πŸ“– + + Giuseppe Gallitto
Giuseppe Gallitto
πŸ“– Graham Searle
Graham Searle
πŸ“– Granville J. Matheson
Granville J. Matheson
πŸ“– Gregory Kiar
Gregory Kiar
πŸ“– πŸ’» 🎨 πŸ”§ Gregory Noack
Gregory Noack
πŸ“– πŸ’» ⚠️ - - Greydon Gilmore
Greydon Gilmore
πŸ“– πŸ’» Guillaume Flandin
Guillaume Flandin
πŸ“– πŸ’» + + Gunnar Schaefer
Gunnar Schaefer
πŸ“– Gustav Nilsonne
Gustav Nilsonne
πŸ“– Hamish Innes-Brown
Hamish Innes-Brown
πŸ“– Hanne D. Hansen
Hanne D. Hansen
πŸ“– Hanzhang Lu
Hanzhang Lu
πŸ“– - - Hao-Ting Wang
Hao-Ting Wang
πŸ“– πŸ› Helena Cockx
Helena Cockx
πŸ“– πŸ€” πŸ’¬ + + Henk Mutsaerts
Henk Mutsaerts
πŸ’¬ πŸ› πŸ’» πŸ“– πŸ’‘ πŸ“‹ πŸ€” πŸ“† πŸ“’ πŸ““ Hernando Ombao
Hernando Ombao
πŸ“– Hugo Boniface
Hugo Boniface
πŸ“– πŸ’» Ilkay Isik
Ilkay Isik
πŸ“– Ilona Lipp
Ilona Lipp
πŸ“– - - International Neuroinformatics Coordinating Facility
International Neuroinformatics Coordinating Facility
πŸ’΅ πŸ“‹ Iris Groen
Iris Groen
πŸ“– + + Isla Staden
Isla Staden
πŸ“– Jaap von der Aar
Jaap von der Aar
πŸ“– - Jacob Sanz-Robinson
Jacob Sanz-Robinson
πŸ’» Jakub Kaczmarzyk
Jakub Kaczmarzyk
πŸ“– πŸ”§ πŸš‡ James Gholam
James Gholam
πŸ“– - - James Kent
James Kent
πŸ’¬ πŸ’» Jan Mathijs Schoffelen
Jan Mathijs Schoffelen
πŸ“– Jan Petr
Jan Petr
πŸ’¬ πŸ› πŸ’» πŸ“– πŸ”£ πŸ’‘ πŸ“‹ πŸ€” πŸ“† ⚠️ πŸ“’ + + Jan-Mathijs Schoffelen
Jan-Mathijs Schoffelen
πŸ“– Jean-Baptiste Poline
Jean-Baptiste Poline
πŸ“– πŸ“’ πŸ€” 🎨 πŸ’» - Jean-Charles Mariani
Jean-Charles Mariani
πŸ“– πŸ€” Jean-Christophe Houde
Jean-Christophe Houde
πŸ“– πŸ’» - - Jean-Dominique Gallezot
Jean-Dominique Gallezot
πŸ“– Jean-Philippe Lachaux
Jean-Philippe Lachaux
πŸ“– Jeanette Mumford
Jeanette Mumford
πŸ“– Jefferson Casimir
Jefferson Casimir
πŸ”§ + + Jeffrey G. Ojemann
Jeffrey G. Ojemann
πŸ“– Jeffrey S. Grethe
Jeffrey S. Grethe
πŸ’¬ πŸ› βœ… πŸ“’ πŸ’» JegouA
JegouA
πŸ’» - - Jelle Dalenberg
Jelle Dalenberg
πŸ“– Jeremy Moreau
Jeremy Moreau
πŸ“– πŸ’‘ Jessica A. Turner
Jessica A. Turner
πŸ“– Jochem Rieger
Jochem Rieger
πŸ“– + + John Detre
John Detre
πŸ“– John Pellman
John Pellman
πŸ“– John T. Wodder
John T. Wodder
πŸ’» - - Joke Durnez
Joke Durnez
πŸ“– πŸ”§ πŸ’» Jon Haitz Legarreta GorroΓ±o
Jon Haitz Legarreta GorroΓ±o
πŸ’» πŸ“– Jonathan C. Lau
Jonathan C. Lau
πŸ“– Jonathan Winawer
Jonathan Winawer
πŸ“– + + Joost Kuijer
Joost Kuijer
πŸ“– Jose Manuel Saborit
Jose Manuel Saborit
πŸ“– Joseph Wexler
Joseph Wexler
πŸ“– πŸ’‘ - - Joseph Woods
Joseph Woods
πŸ“– Julia Guiomar Niso GalΓ‘n
Julia Guiomar Niso GalΓ‘n
πŸ€” 🎨 πŸ” πŸ‘€ πŸ“‹ πŸ“ πŸ”§ πŸ› πŸ’» πŸ”£ βœ… πŸ’¬ πŸ“– πŸ’‘ πŸ“’ Julia Sprenger
Julia Sprenger
πŸ“– - Julia-Katharina Pfarr
Julia-Katharina Pfarr
πŸ’» πŸ“– Julien Cohen-Adad
Julien Cohen-Adad
πŸ“– πŸ”£ πŸ€” - Julio C Hernandez Pavon
Julio C Hernandez Pavon
πŸ“– - Julius Welzel
Julius Welzel
πŸ“– πŸ’‘ πŸ› πŸ’» πŸ”£ πŸ€” πŸ’¬ πŸ““ + Julius Welzel
Julius Welzel
πŸ“– πŸ’‘ πŸ› πŸ’» πŸ”£ πŸ€” πŸ’¬ πŸ““ Kai J. Miller
Kai J. Miller
πŸ“– Kangjoo Lee
Kangjoo Lee
πŸ“– Katja Heuer
Katja Heuer
πŸ”§ Kay Robbins
Kay Robbins
πŸ’» πŸ“– πŸ› Kevin Larcher
Kevin Larcher
πŸ’¬ - Kimberly Ray
Kimberly Ray
πŸ“– πŸ“‹ πŸ€” πŸ“† - Kirstie Whitaker
Kirstie Whitaker
πŸ“– πŸ’‘ πŸ” πŸ€” πŸ“’ πŸ’¬ πŸ’» + Kimberly Ray
Kimberly Ray
πŸ“– πŸ“‹ πŸ€” πŸ“† + Kirstie Whitaker
Kirstie Whitaker
πŸ“– πŸ’‘ πŸ” πŸ€” πŸ“’ πŸ’¬ πŸ’» Klara Gregorova
Klara Gregorova
πŸ“– Klaus Gramann
Klaus Gramann
πŸ“– πŸ€” Kris Thielemans
Kris Thielemans
πŸ“– Kristofer Bouchard
Kristofer Bouchard
πŸ“– Kurt Schilling
Kurt Schilling
πŸ“– Laetitia Fesselier
Laetitia Fesselier
πŸ”§ - Laura and John Arnold Foundation
Laura and John Arnold Foundation
πŸ’΅ + Laura and John Arnold Foundation
Laura and John Arnold Foundation
πŸ’΅ Leandro Beltrachini
Leandro Beltrachini
πŸ“– Lee Kamentsky
Lee Kamentsky
πŸ“– Lennart Walger
Lennart Walger
πŸ“– Lennart Wittkuhn
Lennart Wittkuhn
πŸ“– Liberty Hamilton
Liberty Hamilton
πŸ“– Luca Pollonini
Luca Pollonini
πŸ“– - Luis Hernandez-Garcia
Luis Hernandez-Garcia
πŸ“– πŸ““ - Luke J. Edwards
Luke J. Edwards
πŸ“– πŸ’¬ + Luis Hernandez-Garcia
Luis Hernandez-Garcia
πŸ“– πŸ““ + Luke J. Edwards
Luke J. Edwards
πŸ“– πŸ’¬ Lyuba Zehl
Lyuba Zehl
πŸ“– Mainak Jas
Mainak Jas
πŸ“– πŸ’» - Mana Biabani
Mana Biabani
πŸ“– Manjari Narayan
Manjari Narayan
πŸ“– Manuel Mercier
Manuel Mercier
πŸ“– πŸ€” Maqsood Yaqub
Maqsood Yaqub
πŸ“– @@ -302,109 +284,91 @@ Thanks goes to these wonderful people. Marc Lalancette
Marc Lalancette
πŸ“– πŸ’» Marco Castellaro
Marco Castellaro
πŸ’¬ πŸ› πŸ’» πŸ“– πŸ’‘ ⚠️ πŸ“’ πŸš‡ - Maria Ermolova
Maria Ermolova
πŸ“– Maria de la Iglesia
Maria de la Iglesia
πŸ“– Marie-HΓ©lΓ¨ne Bourget
Marie-Hélène Bourget
πŸ“– πŸ”£ πŸ’» πŸ€” Mark Mikkelsen
Mark Mikkelsen
πŸ“– πŸ’» πŸ”£ πŸ‘€ Markus Morawski
Markus Morawski
πŸ“– + Marta Bortoletto
Marta Bortoletto
πŸ“– - Marta Bortoletto
Marta Bortoletto
πŸ“– Martin Craig
Martin Craig
πŸ”£ Martin Noergaard
Martin Noergaard
πŸ“– πŸ”£ πŸ’» πŸ€” πŸ“’ Martin Szinte
Martin Szinte
πŸ“– Martin Wilson
Martin Wilson
πŸ“– Martina Bulgari
Martina Bulgari
πŸ“– Mateusz Pawlik
Mateusz Pawlik
πŸ“– πŸ› πŸ€” 🚧 πŸ‘€ + Mathias Goncalves
Mathias Goncalves
πŸ’» πŸ”§ πŸ“’ - Mathias Goncalves
Mathias Goncalves
πŸ’» πŸ”§ πŸ“’ Mathieu Boudreau
Mathieu Boudreau
πŸ’¬ πŸ€” πŸ“’ - Mathieu DugrΓ©
Mathieu DugrΓ©
πŸ’» Matt Sanderson
Matt Sanderson
πŸ“– πŸ’» Matteo Tonietto
Matteo Tonietto
πŸ“– Matthias GΓΌnther
Matthias GΓΌnther
πŸ“– Matthias Van Osch
Matthias Van Osch
πŸ“– - - - Mattia Veronese
Mattia Veronese
πŸ“– Maureen J Shader
Maureen J Shader
πŸ“– Maurice Pasternak
Maurice Pasternak
πŸ““ + + Max A. van den Boom
Max A. van den Boom
πŸ’» πŸ‘€ πŸ“– πŸ› Melanie Ganz-Benjaminsen
Melanie Ganz-Benjaminsen
πŸ“– πŸ”£ πŸ’» πŸ€” πŸ“† πŸ” πŸ“’ - Melissa kline
Melissa kline
πŸ“– Michael Chappell
Michael Chappell
πŸ“– πŸ”£ πŸ“† - - Michael Hanke
Michael Hanke
πŸ“– πŸ€” πŸ”§ πŸ› πŸ“’ Michael P. Harms
Michael P. Harms
πŸ“– ⚠️ πŸ”§ Michael P. Milham
Michael P. Milham
πŸ’‘ πŸ” Michael P. Notter
Michael P. Notter
πŸ’¬ πŸ“ βœ… πŸ“’ πŸ“– - Michael Schirner
Michael Schirner
πŸ“– - Michelle Wang
Michelle Wang
πŸ’» - MikaΓ«l Naveau
MikaΓ«l Naveau
πŸ› - Mohammad Torabi
Mohammad Torabi
πŸ’» - Monique Denissen
Monique Denissen
πŸ“– - Murat Bilgel
Murat Bilgel
πŸ“– + Michael Schirner
Michael Schirner
πŸ“– + MikaΓ«l Naveau
MikaΓ«l Naveau
πŸ› Nader Pouratian
Nader Pouratian
πŸ“– Natalia Petridou
Natalia Petridou
πŸ“– - Natalie Rotstein
Natalie Rotstein
πŸ“– National Institute of Mental Health
National Institute of Mental Health
πŸ’΅ - - Nell Hardcastle
Nell Hardcastle
πŸ’» πŸ“– πŸ€” πŸš‡ πŸ‘€ πŸ’¬ - Nicholas Holmes
Nicholas Holmes
πŸ“– Nicholas Traut
Nicholas Traut
πŸ“– πŸ”§ πŸ’» - Nick F. Ramsey
Nick F. Ramsey
πŸ“– - Nicole C. Swann
Nicole C. Swann
πŸ“– - Nigel Rogasch
Nigel Rogasch
πŸ“– - Nikhil Bhagwat
Nikhil Bhagwat
πŸ’» - Nikita Beliy
Nikita Beliy
πŸ“– + Nick F. Ramsey
Nick F. Ramsey
πŸ“– + Nicole C. Swann
Nicole C. Swann
πŸ“– + Nikita Beliy
Nikita Beliy
πŸ“– Nima Bigdely Shamlo
Nima Bigdely Shamlo
πŸ“– Olivier David
Olivier David
πŸ“– Orrin Devinsky
Orrin Devinsky
πŸ“– Oscar Esteban
Oscar Esteban
πŸ“– πŸ”§ πŸ€” πŸ’¬ πŸ’» - Pamela LaMontagne
Pamela LaMontagne
πŸ“– πŸ’‘ - Parul Sethi
Parul Sethi
πŸ“– πŸ”§ ⚠️ πŸ’» + Pamela LaMontagne
Pamela LaMontagne
πŸ“– πŸ’‘ + Parul Sethi
Parul Sethi
πŸ“– πŸ”§ ⚠️ πŸ’» Patricia Clement
Patricia Clement
πŸ’¬ πŸ› πŸ’» πŸ“– πŸ”£ πŸ’‘ πŸ“‹ πŸ€” πŸ“† ⚠️ πŸ“’ Patrick Park
Patrick Park
πŸ“– πŸ’‘ πŸ’¬ πŸ’» Paule-Joanne Toussaint
Paule-Joanne Toussaint
πŸ“– Peer Herholz
Peer Herholz
πŸ’¬ πŸ“– πŸ‘€ πŸ”§ βœ… πŸ“’ Petra Ritter
Petra Ritter
πŸ“– - Pierre Rioux
Pierre Rioux
πŸ“– - Pieter Vandemaele
Pieter Vandemaele
πŸ“– πŸ’» + Pierre Rioux
Pierre Rioux
πŸ“– + Pieter Vandemaele
Pieter Vandemaele
πŸ“– πŸ’» Pradeep Reddy Raamana
Pradeep Reddy Raamana
πŸ’» πŸ”§ R. Cameron Craddock
R. Cameron Craddock
πŸ“– πŸ“’ Remi Gau
Remi Gau
πŸ“– πŸ’» πŸ’¬ πŸ“’ πŸ› πŸ’» πŸš‡ πŸ‘€ πŸ”§ πŸ€” Richard HΓΆchenberger
Richard HΓΆchenberger
πŸ“– πŸ’» Richard N. Henson
Richard N. Henson
πŸ“– - Robert B. Innis
Robert B. Innis
πŸ“– - Robert E. Smith
Robert E. Smith
πŸ’» πŸ“– + Robert B. Innis
Robert B. Innis
πŸ“– + Robert E. Smith
Robert E. Smith
πŸ’» πŸ“– Robert Knight
Robert Knight
πŸ“– Robert Luke
Robert Luke
πŸ’» Robert Oostenveld
Robert Oostenveld
πŸ“– πŸ”§ πŸ“’ πŸ’‘ βœ… ⚠️ πŸ€” πŸ’¬ πŸ› πŸ“ πŸ’» πŸ–‹ πŸ”£ 🎨 πŸ“‹ πŸš‡ πŸ‘€ πŸ““ πŸ“Ή - Roberto Guidotti
Roberto Guidotti
πŸ“– Roberto Toro
Roberto Toro
πŸ”§ Rohan Goyal
Rohan Goyal
πŸ“– - Ross W. Blair
Ross W. Blair
πŸ’» + Ross W. Blair
Ross W. Blair
πŸ’» Russell A. Poldrack
Russell A. Poldrack
πŸ“– πŸ” πŸ“’ RΓ©mi Adon
RΓ©mi Adon
πŸ“– Samir Das
Samir Das
πŸ“– - Samuel Diebolt
Samuel Diebolt
πŸ“– πŸ€” Samuel Garcia
Samuel Garcia
πŸ€” πŸ‘€ πŸ“– - Samuel Guay
Samuel Guay
πŸ“– + Samuel Guay
Samuel Guay
πŸ“– Samuel Nastase
Samuel Nastase
πŸ’» @@ -412,44 +376,35 @@ Thanks goes to these wonderful people. Sasha D'Ambrosio
Sasha D'Ambrosio
πŸ“– Satrajit S. Ghosh
Satrajit S. Ghosh
πŸ“– πŸ’» Scott Makeig
Scott Makeig
πŸ“– - Sebastian Urchs
Sebastian Urchs
πŸ’» πŸ“– πŸ€” Sein Jeung
Sein Jeung
πŸ“– πŸ’‘ πŸ› πŸ’» πŸ”£ πŸ€” πŸ’¬ πŸ”§ πŸ““ - Seyed Yahya Shirazi
Seyed Yahya Shirazi
πŸ“– πŸ€” - - Shashank Bansal
Shashank Bansal
πŸ“– - Silvia Isabella
Silvia Isabella
πŸ“– Sjoerd B. Vos
Sjoerd B. Vos
πŸ“– + + Soichi Hayashi
Soichi Hayashi
πŸ“– πŸ”§ πŸ› Stefan Appelhoff
Stefan Appelhoff
πŸ“– πŸ’¬ πŸ€” πŸ› πŸ’‘ πŸ’» πŸ‘€ ⚠️ πŸ“’ βœ… πŸ”§ πŸ”Œ πŸ“ 🚧 πŸ”£ - Stefanie De Smet
Stefanie De Smet
πŸ“– Stephan Bickel
Stephan Bickel
πŸ“– - - - Steven Meisler
Steven Meisler
πŸ› πŸ’» πŸ’¬ πŸ”§ πŸ““ + Steven Meisler
Steven Meisler
πŸ› πŸ’» πŸ’¬ πŸ”§ πŸ““ Suyash Bhogawar
Suyash Bhogawar
πŸ“– πŸ’‘ ⚠️ πŸ”§ πŸ’¬ Sylvain Baillet
Sylvain Baillet
πŸ“– πŸ” Sylvain Takerkart
Sylvain Takerkart
πŸ“– + + SΓ©bastien Tourbier
SΓ©bastien Tourbier
πŸ€” πŸ‘€ πŸ“’ πŸ› πŸ’» πŸ“– SΓΆren Grothkopp
SΓΆren Grothkopp
πŸ“– πŸ”£ πŸ““ Tal Pal Attia
Tal Pal Attia
πŸ“– - - Tal Yarkoni
Tal Yarkoni
πŸ’» πŸ“– πŸ€” πŸ” πŸ”Œ πŸ‘€ πŸ“’ πŸ› 🎨 Tamas Spisak
Tamas Spisak
πŸ“– TamΓ‘s JΓ³zsa
TamΓ‘s JΓ³zsa
πŸ““ - Taylor Khuhn
Taylor Khuhn
πŸ“– Taylor Salo
Taylor Salo
πŸ’¬ πŸ“– πŸ”Œ πŸ’» - Teon L. Brooks
Teon L. Brooks
πŸ“– πŸ’» ⚠️ πŸ’¬ πŸ‘€ πŸ€” πŸ”§ πŸ› πŸ“’ - Thomas Deffieux
Thomas Deffieux
πŸ“– πŸ€” + Teon L. Brooks
Teon L. Brooks
πŸ“– πŸ’» ⚠️ πŸ’¬ πŸ‘€ πŸ€” πŸ”§ πŸ› πŸ“’ Thomas E. Nichols
Thomas E. Nichols
πŸ“– πŸ“’ πŸ”§ πŸ‘€ 🚧 πŸ’» Thomas Funck
Thomas Funck
πŸ“– Thomas Kirk
Thomas Kirk
πŸ“– Thomas Okell
Thomas Okell
πŸ“– Tibor Auer
Tibor Auer
πŸ’¬ πŸ“– πŸ’‘ πŸ”§ πŸ“’ πŸ› πŸ€” - Til Ole Bergmann
Til Ole Bergmann
πŸ“– Timo Dickscheid
Timo Dickscheid
πŸ“– @@ -466,30 +421,25 @@ Thanks goes to these wonderful people. Ulrike Bingel
Ulrike Bingel
πŸ“– Vanessa Sochat
Vanessa Sochat
πŸ“– Vasudev Raguram
Vasudev Raguram
πŸ’» 🎨 πŸ“– πŸ”§ - Victor Hugo Souza
Victor Hugo Souza
πŸ“– Vince D. Calhoun
Vince D. Calhoun
πŸ“– Vittorio Iacovella
Vittorio Iacovella
πŸ“– + Viviana Siless
Viviana Siless
πŸ“– - Viviana Siless
Viviana Siless
πŸ“– Vladimir Litvak
Vladimir Litvak
πŸ“– Wietske van der Zwaag
Wietske van der Zwaag
πŸ”£ πŸ’¬ William Clarke
William Clarke
πŸ“– William Triplett
William Triplett
πŸ“– Wouter V. Potters
Wouter V. Potters
πŸ’» πŸ“– Xiangrui Li
Xiangrui Li
πŸ“– πŸ’» + Yaroslav O. Halchenko
Yaroslav O. Halchenko
πŸ“– πŸ“’ πŸ”§ πŸ’¬ πŸ› πŸ’» πŸ”£ πŸ” πŸ€” πŸ”Œ πŸ‘€ πŸ““ πŸš‡ - Yaroslav O. Halchenko
Yaroslav O. Halchenko
πŸ“– πŸ“’ πŸ”§ πŸ’¬ πŸ› πŸ’» πŸ”£ πŸ” πŸ€” πŸ”Œ πŸ‘€ πŸ““ πŸš‡ Yoni Ashar
Yoni Ashar
πŸ“– Yuan Wang
Yuan Wang
πŸ’» Zachary Michael
Zachary Michael
πŸ“– - Zhi-De Deng
Zhi-De Deng
πŸ“– ezemikulan
ezemikulan
πŸ’» josator2
josator2
πŸ’» - - - mathieu_guay-paquet
mathieu_guay-paquet
πŸ“– monkeyman192
monkeyman192
πŸ’» Γ‰tienne Bergeron
Γ‰tienne Bergeron
πŸ”£ πŸ’» diff --git a/docs/faq/general.md b/docs/faq/general.md index 4f7f286c..52582134 100644 --- a/docs/faq/general.md +++ b/docs/faq/general.md @@ -87,7 +87,7 @@ sub-S003/ ## How to import Excel files to TSV file? -See [our sections on TSV files](../getting_started/folders_and_files/metadata.md#tsv-files) for more information. +See [our sections on TSV files](../getting_started/folders_and_files/metadata/tsv.md) for more information. See also this bids tool to import and export a `participants.tsv` file: [bids-matlab-tools](https://github.com/sccn/bids-matlab-tools/blob/master/bids_spreadsheet2participants.m) @@ -172,7 +172,7 @@ work with data in BIDS format. Check it out [here](../getting_started/resources/ ## What is a `json` file? You can find more information about `json` (and `tsv`) files in the -[Metadata-file-formats](../getting_started/folders_and_files/metadata.md#json) page. +[Metadata-file-formats](../getting_started/folders_and_files/metadata/json.md) page. ## What liense should I choose for my dataset? diff --git a/docs/getting_started/folders_and_files/metadata.md b/docs/getting_started/folders_and_files/metadata.md deleted file mode 100644 index 7937d3d4..00000000 --- a/docs/getting_started/folders_and_files/metadata.md +++ /dev/null @@ -1,593 +0,0 @@ -Metadata are stored in .json and .tsv files. - -These files are language-agnostic, meaning you can work with them in, for example: Python, Matlab, or R. - -This page covers common ways to read/write these files in common languages for neuroscience analysis. - -More extensive example templates can be found -[here](https://github.com/bids-standard/bids-starter-kit/tree/main/templates), -well as [MATLAB / Octave code](https://github.com/bids-standard/bids-starter-kit/tree/main/matlabCode) -and [Python code](https://github.com/bids-standard/bids-starter-kit/tree/main/pythonCode) -to help you generate some of those files. - -## JSON Files - -JSON stands for JavaScript Object Notation -and as its name indicates takes its syntax from the JavaScript language. - -JSON files are text files that take the following structure: - -```json -{ - "key": "value", - "key2": "value2", - "key3": { - "subkey1": "subvalue1" - } -} -``` - -Note that they can be nested (curly brackets within curly brackets). -Here are some common ways to read / write these files. - -### Editing JSON file online - -Working with JSON can be a headache if you do not have the proper tools. - -To get started we suggest playing around with JSON in an online editor, -to get a feeling for how JSON works. - -See for example this one: [http://jsoneditoronline.org/](http://jsoneditoronline.org/) - -Online editors can also usually tell you if you forgot a comma, -forgot to close a bracket or something similar. -And even fix mistakes for you. - -![](../../assets/img/autofix.png) - -### Editing JSON file on your computer - -If you need to edit JSON files on your computer, it will make your life easier -if you use a modern code editor like: - -- [visual studio code](https://code.visualstudio.com/) - -Modern code editors can tell you if you have a valid JSON file -and highlight the lines where you have errors. -Most of them usually also have code formatting extensions -that can automatically indent your JSON like -[Prettier for vscode](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) - -#### Matlab / Octave - -There are many toolboxes in Matlab for reading / writing JSON files. - -Since MATLAB R2016b, you can use the built-in functions `jsonencode` (to write) and `jsondecode` (to read) JSON files. -Hopefully they should be available in Octave 6.1 next year. - -The [JSONio library](https://github.com/gllmflndn/JSONio) will allow you to read -and write JSON files with matlab and octave (see examples below to use `jsonwrite` and `jsonread`). - -SPM12 uses the JSONio library by calling `spm_jsonwrite` and `spm_jsonread` and -it has [other interesting functions to help you with BIDS](https://en.wikibooks.org/wiki/SPM/BIDS). - -[bids-matlab](https://github.com/bids-standard/bids-matlab) has 2 functions -(`bids.util.jsonencode` and `bids.util.jsondecode`) that act as wrappers and -will use whatever implementation (SPM, JSONio, MATLAB) is available. - -The examples below are for the [JSONio library](https://github.com/gllmflndn/JSONio): - -##### Reading a `.json` file - -```matlab - jsonread([filename]) -``` - -##### Writing a `.json` file - -```matlab -root_dir = './'; -project = 'temp'; -sub_id = '01'; -ses_id = '01'; -acquisition = 'anat'; - -anat_json_name = fullfile(root_dir,project,... - ['sub-' sub_id],... - ['ses-' ses_id],... - acquisition,... - ['sub-' sub_id '_ses-' ses_id '_T1W.json']); - -% Assign the fields in the Matlab structure that can be saved as a json: -anat_json.Manufacturer = 'GE'; -anat_json.ManufacturersModelName = 'Discovery MR750'; -anat_json.MagneticFieldStrength = 3; -anat_json.PulseSequence = 'T1 weighted SPGR'; - -json_options.indent = ' '; % this makes the json lThe BIDS statistical models are written in JSON files. - -If you have never heard of JSON, this section is for you. - -Here we will quickly: - -- explain some of the terms that you need to be familiar to work with JSON -- suggest some tools that you may want to use to make it easier for you to work - with JSON.ook pretier when opened in a txt editor -jsonwrite(loc_json_name,anat_json,json_options) -``` - -#### Python - -In Python, JSON support is built into the core library, -meaning you don't need to install anything to read/write JSON files. -In addition, the structure of JSON is almost identical -to that of Python dictionaries (assuming you are only storing text / numbers in the dictionary). - -##### Reading a `.json` file - -```python - -import json -with open('myfile.json', 'r') as ff: - data = json.load(ff) -``` - -##### Writing a `.json` file - -```python -import json -data = {'field1': 'value1', 'field2': 3, 'field3': 'field3'} -with open('my_output_file.json', 'w') as ff: - json.dump(data, ff) -``` - -#### R - -There is a new package to help intract with BIDS datasets: [bidser](https://github.com/bbuchsbaum/bidser) - -There are several packages for reading and writing JSON files from R. -In this example, we will be using jsonlite. -Remember to install and call a package before using it. - -[jsonlite](https://github.com/jeroen/jsonlite) - -```R - install.packages('jsonlite') -``` - -##### Reading a `.json` file - -```R - library(jsonlite) - data = fromJSON('myfile.json', pretty=TRUE) -``` - -##### Writing a `.json` file - -```R - library(jsonlite) - data = '{"field1": "value1", "field2": 3, "field3": "field3"}' - writeLines(data, file="myData.json") -``` - -### Interoperability issues - -Many parts of JSON files are often loaded as -[`structures`](https://nl.mathworks.com/help/matlab/ref/struct.html) by MATLAB / Octave, -where a `key` in a JSON file becomes `fieldname` in that structure. - -Here is an example with a simple `example.json` - -```json -{ - "key": "value" -} -``` - -loaded with bids-matlab - -```matlab ->> json_content = bids.util.jsondecode('example.json') - -json_content = - - struct with fields: - - key: 'value' -``` - -There are however some strict rules for what makes a valid fieldname in MATLAB and octave. - -Fieldnames must: - -- start with a letter, otherwise assigning to that field will error - -- contain only letters, numbers, and/or the underscore character, otherwise assigning to that field will error, and - -- must be no longer than `namelengthmax` (currently 63) characters, otherwise - you will receive a warning and the field name will be truncated - -If there are keys in your JSON that do not comply to those rules, -they keys will be renamed when loading which can lead to some headaches down the line. - -For example when loading the `bad_keys.json` - -```json -{ - "@foo": "@foo", - "1": "1", - "x1": "x1", - "x_1": "x_1", - "/t": "/t", - "%f": "%f" -} -``` - -We get some quite different fieldnames when read with matlab: - -```matlab ->> jsondecode(fileread('bad_keys.json')) - -ans = - - struct with fields: - - x_foo: '@foo' - x1: '1' - x1_1: 'x1' - x_1: 'x_1' - x_t: '/t' - x_f: '%f' -``` - -or with JSONio for Octave (though at least here we get a warning): - -```matlab ->> jsonread('bad_keys.json') -Warning: Duplicate key. - -ans = - - struct with fields: - - x_foo: '@foo' - x1: 'x1' - x_1: 'x_1' - x_t: '/t' - x_f: '%f' -``` - -This can lead to some unexpected behavior if you did not know about this. - -If you load this `collision.json` - -```json -{ - "1": "1", - "x1": "x1", - "x_1": "x_1" -} -``` - -and try to retrieve the value associated to the `key` `x1`, you will in fact be -getting the value for the key `1`. - -```matlab ->> json_content = bids.util.jsondecode('collision.json'); ->> json_content.x1 - - x1: '1' -``` - -#### Why and when does this matter for BIDS? - -In most cases this will not be an issue, -but this could be problem if in your `events.tsv` -you have named some of your trial_type things like `1_face`, -`2_sound` and then want to annotate those events in a side car JSON file like this. - -```json -{ - "trial_type": { - "LongName": "", - "Description": "image type", - "Levels": { - "1_face": "A face is displayed", - "2_sound": "A sound is played" - } - } -} -``` - -If you do this, it will be much harder to work with that JSON file for anyone who uses MATLAB or Octave. - -```{attention} -So in general here are some suggestions on how to name your events: -- start with a letter -- make sure they contain only letters, numbers, and/or the underscore character -- make sure they are must be no longer than currently 63 characters -``` - -### More about JSON - -#### JSON terms - -The main "building blocks" of JSON you must be familiar with are `Objects` and `Arrays`. - -##### Objects - -In JSON, objects - -- are opened and closes by curly brackets `{ }` - -- are a collection of key–value pairs where: - - - the keys are strings - - the key and the value are separated by a colon `:` - -For example, this is an object. - -```json -{ "Key": "value", "Key2": 1 } -``` - -As you can see, in JSON strings start and end with double quotes `"`. -Also note the comma between the key-value pairs but not after the last key-value pair. - -##### Arrays - -In JSON, arrays are: - -- are opened and closes by square brackets `[ ]` -- an ordered list of zero or more elements, each of which may be of any type (string, number..) -- elements must be separated by a comma - -```json -["this", "is", 1, "JSON", "array"] -``` - -#### A note on Booleans - -In JSON boolean values must be typed as lowercase with no quotes: - -- `true` -- `false` - -#### JSON "styling" - -In JavaScript it is custom to use CamelCase to write code, -this is why most of keys you will see in JSON are also in CamelCase. - - - -For example: - -```json -{ "ThisIsTrue": true, "ThisIsTrue": false } -``` - -It is common to indent JSON files to improve readability. - -```json -{ - "ThisIsTrue": true, - "ThisIsTrue": false -} -``` - -Finally, you cannot add comments in JSON files, -but the BIDS stats model allows you to add a `"Description"` key -to most objects to give explanations to the reader. - -#### Nesting - -JSON allows to "nest" objects within objects, to create arrays of objects -and combine all those elements however deep you want or need. - -Just remember to place commas: - -- between array elements -- between key-value pairs -- unless this is the last element (or key-value pair) - -```json -{ - "MixedArray": ["This", "is", "one", "array"], - "ArrayOfNumbers": [0, 0, 1, 0, 0], - "ArrayOfObjects": [ - { - "NestedObject": true, - "Content": { "value": 0 } - }, - { - "NestedObject": false, - "Content": 1 - } - ] -} -``` - -#### JSON schema - -If the content of your JSON must follow certain rules, like - -!!! note - - your JSON file must contain a key-value pair - - with a key called: "Version" - - with a value that must be a number - -Then you can specify those rules in what is called a JSON schema. - -##### Online - -If you are working on a JSON file in the browser like with [http://jsoneditoronline.org/](http://jsoneditoronline.org/), -and if there is a JSON schema for the JSON file you are working on -you can also use that schema to validate while editing -by clicking `Options --> JSON schema --> URL` -and give it the URL to the schema. - -See the example below using the [BIDS stats model schema](https://bids-standard.github.io/stats-models/BIDSStatsModel.json): - -![](../../assets/img/schema_in_browser.png) - -##### On your computer - -If you want to validate a JSON file you are editing using a JSON schema -you can do so by adding the following key-value pair in your BIDS stats model, -(here using the BIDS stats model schema as an example) - -```json - "$schema": "https://raw.githubusercontent.com/bids-standard/stats-models/gh-pages/BIDSStatsModel.json", -``` - -For vs-code you can also add this to your settings: - -```json -"json.schemas": [ - {"fileMatch": [ - "model-*_smdl.json" - ], - "url": "https://raw.githubusercontent.com/bids-standard/stats-models/gh-pages/BIDSStatsModel.json" - } -] -``` - -[Source](https://code.visualstudio.com/docs/languages/json#_json-schemas-and-settings) - -Example of JSON syntax error and BIDS stats model schema error in VS code: - -![](../../assets/img/vs_code_validation.png) - -## TSV files - -A Tab-Separate Values (TSV) file is a text file where tab characters (`\t`) separate fields that are in the file. -It is structured as a table, with each column representing a field of interest, -and each row representing a single datapoint. - -Below are ways to read / write TSV files in common languages. - -### Matlab - -#### Reading a `.tsv` file - -```matlab -table_content = readtable(filename, ... - 'FileType', 'text', ... - 'Delimiter', '\t', ... - 'TreatAsEmpty', {'N/A','n/a'}); -``` - -#### Writing a `.tsv` file - -##### Matlab - -```matlab -root_dir = pwd; -bidsProject = 'temp'; -mkdir(fullfile(root_dir, bidsProject)); -bids_participants_name = 'participants.tsv'; - -participant_id = ['sub-01'; 'sub-02']; -age = [20 30]'; -sex = ['m';'f']; - -t = table(participant_id,age,sex); -writetable(t, fullfile(root_dir, bidsProject, bids_participants_name), ... - 'FileType', 'text', ... - 'Delimiter', '\t'); -``` - -##### Octave - -The `writetable` function is not implemented in older version of Octave -(e.g 4.2.2) and the `table` function differs from its matlab counterpart. -These are still in development for future -[releases](https://github.com/apjanke/octave-tablicious) so some of the scripts -provided in the BIDS starter-kit repository in the matlab code folder -to create .tsv might not work with octave because of that reason. - -### Python - -In Python, the easiest way to work with TSV files is to use the Pandas library. -This provides a high-level structure to organize, manipulate, clean, and -visualize tabular data. -You can install `pandas` with the following command: - -`pip install pandas` - -#### Reading a `.tsv` file - -There are many ways to read a `.tsv` file in Pandas. -One option is the following: - -```python -import pandas as pd -pd.read_csv('./ds001/participants.tsv', delimiter='\t') -``` - -Note that this function will default to using `,` as a delimiter, so we explicitly give it the tab character. - -#### Writing a `.tsv` file - -You can write to a `.tsv` file using the `to_csv` method of a pandas DataFrame: - -```python -import pandas as pd -df = pd.read_csv('./ds001/participants.tsv', delimiter='\t') - -# Add an extra column for demonstration -df['subject_id'] = range(len(df)) - -# Show contents of the dataframe -df.head() - Out: - participant_id sex age subject_id - 0 sub-01 F 26 0 - 1 sub-02 M 24 1 - 2 sub-03 F 27 2 - 3 sub-04 F 20 3 - 4 sub-05 M 22 4 - -# Save as a .tsv file -df.to_csv('my_new_file.tsv', sep='\t') -``` - -### Excel - -- Create a file with the following columns - (at least, for other values see paragraph the - [BIDS specification](https://bids-specification.readthedocs.io/en/latest/03-modality-agnostic-files.html#participants-file)) - - participant_id - - age - - sex - -- Save as tab separated `.txt` and change extension to `.tsv` - -### R - -Reading and writing tab separated files comes natively in R, no need for extra packages. - -#### Reading a `.tsv` file - -In this example, we assume the .tsv includes column names (headers), -and explicitly set column separator (delimiter) to tab ('\t') - -```R -data = read.table('myFile.tsv', header=TRUE, sep='\t') -``` - -#### Writing a `.tsv` file - -When writing files, column and row names are always saved, we remove row names, -and quotes from the outpur explicitly by setting them to FALSE. - -```R -data = cbind.data.frame( - participant_id = c('sub-01', 'sub-02'), - age = c(20,30), - sex = c('m','f')) - -write.table(data, file='myData.tsv',sep='\t', - row.names = FALSE, quote = FALSE) -``` diff --git a/docs/getting_started/folders_and_files/metadata/index.md b/docs/getting_started/folders_and_files/metadata/index.md new file mode 100644 index 00000000..7b8e7f0f --- /dev/null +++ b/docs/getting_started/folders_and_files/metadata/index.md @@ -0,0 +1,11 @@ +Metadata are stored in [.json](./json.md) and [.tsv](./tsv.md) files. + +These files are language-agnostic, meaning you can work with them in, for example: Python, Matlab, or R. + +This page covers common ways to read/write these files in common languages for neuroscience analysis. + +More extensive example templates can be found +[here](https://github.com/bids-standard/bids-starter-kit/tree/main/templates), +well as [MATLAB / Octave code](https://github.com/bids-standard/bids-starter-kit/tree/main/matlabCode) +and [Python code](https://github.com/bids-standard/bids-starter-kit/tree/main/pythonCode) +to help you generate some of those files. diff --git a/docs/getting_started/folders_and_files/metadata/json.md b/docs/getting_started/folders_and_files/metadata/json.md new file mode 100644 index 00000000..d5c91f20 --- /dev/null +++ b/docs/getting_started/folders_and_files/metadata/json.md @@ -0,0 +1,472 @@ +# JSON Files + +JSON stands for JavaScript Object Notation +and as its name indicates takes its syntax from the JavaScript language. + +JSON files are text files that take the following structure: + +```json +{ + "key": "value", + "key2": "value2", + "key3": { + "subkey1": "subvalue1" + } +} +``` + +Note that they can be nested (curly brackets within curly brackets). +Here are some common ways to read / write these files. + +- [Official documentation about JSON](https://www.json.org/json-en.html) + +## Editing JSON file + +### Online + +Working with JSON can be a headache if you do not have the proper tools. + +To get started we suggest playing around with JSON in an online editor, +to get a feeling for how JSON works. + +See for example this one: [http://jsoneditoronline.org/](http://jsoneditoronline.org/) + +Online editors can also usually tell you if you forgot a comma, +forgot to close a bracket or something similar. +And even fix mistakes for you. + +![](../../../assets/img/autofix.png) + +### On your computer + +If you need to edit JSON files on your computer, it will make your life easier +if you use a modern code editor like: + +- [visual studio code](https://code.visualstudio.com/) + +Modern code editors can tell you if you have a valid JSON file +and highlight the lines where you have errors. +Most of them usually also have code formatting extensions +that can automatically indent your JSON like +[Prettier for vscode](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) + +### Python + +In Python, JSON support is built [into the core library](https://docs.python.org/3/library/json.html), +meaning you don't need to install anything to read/write JSON files. +In addition, the structure of JSON is almost identical +to that of Python dictionaries (assuming you are only storing text / numbers in the dictionary). + +### MATLAB / Octave + +Since MATLAB R2016b +and [Octave](https://octave.org/) >= 7.1 (an open-source drop-in compatible with many Matlab scripts), +you can use the built-in functions +[`jsonencode`](https://www.mathworks.com/help/matlab/ref/jsonencode.html) +and [`jsondecode`](https://www.mathworks.com/help/matlab/ref/jsondecode.html) +to help your read and write JSON files. + +!!! note -- "bids-matlab and other libraries" + + There are also several toolboxes in MATLAB or Octave + for reading / writing JSON files. + + [bids-matlab](https://github.com/bids-standard/bids-matlab) has functions + ([`bids.util.jsonencode`](https://bids-matlab.readthedocs.io/en/main/utility_functions.html#bids.util.jsonencode) + and [`bids.util.jsondecode`](https://bids-matlab.readthedocs.io/en/main/utility_functions.html#bids.util.jsonencode)) + that act as wrappers and will use whatever implementation (MATLAB, Octave...) is available. + + The [JSONio library](https://github.com/gllmflndn/JSONio) will allow you to read + and write JSON files with MATLAB and Octave with the `jsonread` and `jsonwrite` functions. + + SPM12 uses the JSONio library by calling `spm_jsonwrite` and `spm_jsonread` and + it has [other interesting functions to help you with BIDS](https://en.wikibooks.org/wiki/SPM/BIDS). + +### R + +There are several packages for reading and writing JSON files from R. +In the examples in this page, we will be using [jsonlite](https://github.com/jeroen/jsonlite). +Remember to install and call a package before using it. + + + +## Reading a `.json` file + +=== "python" + + ```python + import json + with open('myfile.json', 'r') as ff: + metadata = json.load(ff) + ``` + +=== "MATLAB" + + For MATLAB >= R2016b + + ```matlab + % Read JSON data from a file + jsonStr = fileread('myfile.json'); + % Convert JSON string to MATLAB variables + jsonData = jsondecode(jsonStr); + ``` + +=== "octave" + + The example below uses the [JSONio library](https://github.com/gllmflndn/JSONio). + + ```matlab + metadata = jsonread('myfile.json') + ``` + +=== "R" + + The example below uses the [jsonlite](https://github.com/jeroen/jsonlite) library. + + ```R + # install jsonlite in case you did not already do it + # install.packages('jsonlite') + library(jsonlite) + metadata = fromJSON('myfile.json') + ``` + +## Writing a `.json` file + +=== "python" + + ```python + import json + metadata = {'field1': 'value1', 'field2': 3, 'field3': 'field3'} + with open('my_output_file.json', 'w') as ff: + json.dump(metadata, ff) + ``` + +=== "MATLAB" + + ```matlab + metadata = struct('field1', 'value1', 'field2', 3, 'field3', 'field3') + jsonencode('my_output_file.json', metadata); + ``` + +=== "octave" + + The example below uses the [JSONio library](https://github.com/gllmflndn/JSONio). + + ```matlab + metadata = struct('field1', 'value1', 'field2', 3, 'field3', 'field3') + jsonwrite('my_output_file.json', metadata) + ``` + +=== "R" + + The example below uses the [jsonlite](https://github.com/jeroen/jsonlite) library. + + ```R + # install jsonlite in case you did not already do it + # install.packages('jsonlite') + library(jsonlite) + metadata <- list(field1 = "value1", field2 = 3, field3 = "field3") + metadata = toJSON(metadata, pretty=TRUE) + write(metadata, "my_output_file.json") + ``` + +## Interoperability issues + +!!! warning -- "Summary of this section" + + In general, use key names that: + + - start with a letter, + - contain only letters, numbers, and/or the underscore character, + - are no longer than 63 characters. + +Many parts of JSON files are often loaded as +[`structures`](https://nl.mathworks.com/help/matlab/ref/struct.html) by MATLAB / Octave, +where a `key` in a JSON file becomes `fieldname` in that structure. + +Here is an example with a simple `example.json` + +```json +{ + "key": "value" +} +``` + +loaded with bids-matlab + +```matlab +>> json_content = bids.util.jsondecode('example.json') + +json_content = + + struct with fields: + + key: 'value' +``` + +There are however some strict rules for what makes a valid fieldname in MATLAB and Octave. + +Fieldnames must: + +- start with a letter, otherwise assigning to that field will error + +- contain only letters, numbers, and/or the underscore (`_`) character, otherwise assigning to that field will error, and + +- must be no longer than `namelengthmax` (currently 63) characters, otherwise + you will receive a warning and the field name will be truncated + +If there are keys in your JSON that do not comply to those rules, +they keys will be renamed when loading which can lead to some headaches down the line. + +For example when loading the `bad_keys.json` + +```json +{ + "@foo": "@foo", + "1": "1", + "x1": "x1", + "x_1": "x_1", + "/t": "/t", + "%f": "%f" +} +``` + +We get some quite different fieldnames when read with MATLAB: + +```matlab +>> jsondecode(fileread('bad_keys.json')) + +ans = + + struct with fields: + + x_foo: '@foo' + x1: '1' + x1_1: 'x1' + x_1: 'x_1' + x_t: '/t' + x_f: '%f' +``` + +or with JSONio for Octave (though at least here we get a warning): + +```matlab +>> jsonread('bad_keys.json') +Warning: Duplicate key. + +ans = + + struct with fields: + + x_foo: '@foo' + x1: 'x1' + x_1: 'x_1' + x_t: '/t' + x_f: '%f' +``` + +This can lead to some unexpected behavior if you did not know about this. + +If you load this `collision.json` + +```json +{ + "1": "1", + "x1": "x1", + "x_1": "x_1" +} +``` + +and try to retrieve the value associated to the `key` `x1`, you will in fact be +getting the value for the key `1`. + +```matlab +>> json_content = bids.util.jsondecode('collision.json'); +>> json_content.x1 + + x1: '1' +``` + +### Why does this matter for BIDS? + +In most cases this will not be an issue, +but this could be problem if in your `events.tsv` +you have named some of your trial_type things like `1_face`, +`2_sound` and then want to annotate those events in a side car JSON file like this. + +```json +{ + "trial_type": { + "LongName": "", + "Description": "image type", + "Levels": { + "1_face": "A face is displayed", + "2_sound": "A sound is played" + } + } +} +``` + +If you do this, it will be much harder to work with that JSON file for anyone who uses MATLAB or Octave. + +!!! warning + + So in general here are some suggestions on how to name your events: + + - start with a letter + - make sure they contain only letters, numbers, and/or the underscore (`_`) character + - make sure they are no longer than 63 characters + +## More about JSON + +This section below gives you more in depth details about using JSON. + +### JSON terms + +The main "building blocks" of JSON you must be familiar with are `Objects` and `Arrays`. + +#### Objects + +In JSON, objects + +- are opened and closes by curly brackets `{ }` + +- are a collection of key-value pairs where: + + - the keys are strings + - the key and the value are separated by a colon `:` + +For example, this is an object. + +```json +{ "Key": "value", "Key2": 1 } +``` + +As you can see, in JSON strings start and end with double quotes `"`. +Also note the comma between the key-value pairs but not after the last key-value pair. + +#### Arrays + +In JSON, arrays are: + +- are opened and closes by square brackets `[ ]` +- an ordered list of zero or more elements, each of which may be of any type (string, number..) +- elements must be separated by a comma + +```json +["this", "is", 1, "JSON", "array"] +``` + +#### A note on Booleans + +In JSON boolean values must be typed as lowercase with no quotes: + +- `true` +- `false` + +### JSON "styling" + +In JavaScript it is custom to use CamelCase to write code, +this is why most of keys you will see in JSON are also in CamelCase. + + + +For example: + +```json +{ "ThisIsTrue": true, "ThisIsTrue": false } +``` + +It is common to indent JSON files to improve readability. + +```json +{ + "ThisIsTrue": true, + "ThisIsTrue": false +} +``` + +Finally, you cannot add comments in JSON files, +but the BIDS stats model allows you to add a `"Description"` key +to most objects to give explanations to the reader. + +### Nesting + +JSON allows to "nest" objects within objects, to create arrays of objects +and combine all those elements however deep you want or need. + +Just remember to place commas: + +- between array elements +- between key-value pairs +- unless this is the last element (or key-value pair) + +```json +{ + "MixedArray": ["This", "is", "one", "array"], + "ArrayOfNumbers": [0, 0, 1, 0, 0], + "ArrayOfObjects": [ + { + "NestedObject": true, + "Content": { "value": 0 } + }, + { + "NestedObject": false, + "Content": 1 + } + ] +} +``` + +### JSON schema + +If the content of your JSON must follow certain rules, like + +!!! warning + + your JSON file must contain a key-value pair: + + - with a key called: "Version" + - with a value that must be a number + +Then you can specify those rules in what is called a JSON schema. + +#### Online + +If you are working on a JSON file in the browser like with [http://jsoneditoronline.org/](http://jsoneditoronline.org/), +and if there is a JSON schema for the JSON file you are working on +you can also use that schema to validate while editing +by clicking `Options --> JSON schema --> URL` +and give it the URL to the schema. + +See the example below using the [BIDS stats model schema](../../../standards/bids_stats_model/index.md): + +![](../../../assets/img/schema_in_browser.png) + +#### On your computer + +If you want to validate a JSON file you are editing using a JSON schema +you can do so by adding the following key-value pair in your BIDS stats model, +(here using the BIDS stats model schema as an example) + +```json + "$schema": "https://raw.githubusercontent.com/bids-standard/stats-models/gh-pages/BIDSStatsModel.json", +``` + +For vs-code you can also add this to your settings: + +```json +"json.schemas": [ + {"fileMatch": [ + "model-*_smdl.json" + ], + "url": "https://raw.githubusercontent.com/bids-standard/stats-models/gh-pages/BIDSStatsModel.json" + } +] +``` + +[Source](https://code.visualstudio.com/docs/languages/json#_json-schemas-and-settings) + +Example of JSON syntax error and BIDS stats model schema error in VS code: + +![](../../../assets/img/vs_code_validation.png) diff --git a/docs/getting_started/folders_and_files/metadata/tsv.md b/docs/getting_started/folders_and_files/metadata/tsv.md new file mode 100644 index 00000000..b33f3de8 --- /dev/null +++ b/docs/getting_started/folders_and_files/metadata/tsv.md @@ -0,0 +1,137 @@ +# TSV files + +A Tab-Separate Values (TSV) file is a text file where tab characters (`\t`) separate fields that are in the file. +It is structured as a table, with each column representing a field of interest, +and each row representing a single datapoint. + +## Python + +In Python, the easiest way to work with TSV files is to use the [Pandas library](https://pandas.pydata.org/). +This provides a high-level structure to organize, manipulate, clean, and visualize tabular data. +You can install `pandas` with the following command: + +```bash +pip install pandas +``` + +## MATLAB / Octave + +Since MATLAB R2013b, +there is a [`readtable`](https://www.mathworks.com/help/matlab/ref/readtable.html) function that can load TSV files, +and a [`writetable`](https://www.mathworks.com/help/matlab/ref/writetable.html) function to write them. + +For Octave, the `writetable` function is not implemented in older version of Octave +(e.g 4.2.2) and the `table` function differs from its MATLAB counterpart, +so it may be easier to rely on [bids-matlab](https://github.com/bids-standard/bids-matlab) functions +([`bids.util.tsvwrite`](https://bids-matlab.readthedocs.io/en/main/utility_functions.html#bids.util.tsvwrite) and +[`bids.util.tsvread`](https://bids-matlab.readthedocs.io/en/main/utility_functions.html#bids.util.tsvread)) +to help you work with those files. + +## R + +Reading and writing tab separated files comes natively in R, no need for extra packages. + +## Reading a `.tsv` file + +=== "python" + + In this example, we assume the .tsv includes column names (headers), + and explicitly set column separator (delimiter) to tab (`'\t'`). + + ```python + import pandas as pd + data = pd.read_csv("file.tsv", sep="\t", headers=True) + ``` + +=== "MATLAB" + + ```matlab + table_content = readtable('file.tsv', ... + 'FileType', 'text', ... + 'Delimiter', '\t', ... + 'TreatAsEmpty', {'N/A','n/a'}); + ``` + +=== "octave" + + The example below uses the [bids-matlab](https://github.com/bids-standard/bids-matlab) library. + + ```matlab + table_content = bids.util.tsvread('file.tsv'); + ``` + +=== "R" + + In this example, we assume the .tsv includes column names (headers), + and explicitly set column separator (delimiter) to tab (`'\t'`) + + ```R + data = read.table('file.tsv', header=TRUE, sep='\t') + ``` + +=== "Excel / LibreOffice Calc" + + Excel, [LibreOffice Calc](https://www.libreoffice.org/) and similar software to work with tables + should have no problem opening TSV files. + +## Writing a `.tsv` file + +=== "python" + + ```python + import pandas as pd + + participants = pd.DataFrame( + { + "participant_id": ["sub-01", "sub-02"], + "age": [20, 30], + "sex": ["m", "f"], + } + ) + participants.to_csv("participants.tsv") + ``` + +=== "MATLAB" + + ```matlab + participant_id = ['sub-01'; 'sub-02']; + age = [20; 30]'; + sex = ['m'; 'f']; + participants = table(participant_id, age, sex); + + writetable(participants, ... + 'participants.tsv', ... + 'FileType', 'text', ... + 'Delimiter', '\t'); + ``` + +=== "Octave" + + The example below uses the [bids-matlab](https://github.com/bids-standard/bids-matlab) library. + + ```matlab + participants = struct(... + 'participant_id', ['sub-01', 'sub-02']; + 'age', [20, 30]'; + 'sex', ['m', 'f'] + ); + + bids.util.tsvwrite('participants.tsv', participants); + ``` + +=== "R" + + When writing files, column and row names are always saved, + we remove row names and quotes from the output explicitly by setting them to `FALSE`. + + ```R + participant_id <- c('sub-01', 'sub-02'); + age <- c(20, 30); + sex <- c('m', 'f'); + participants <- data.frame(participant_id, age, sex) + write.table(participants, + file='participants.tsv', + sep='\t', + row.names = FALSE, + quote = FALSE) + ``` diff --git a/docs/getting_started/resources/dependencies.md b/docs/getting_started/resources/dependencies.md index 1305c243..6927c365 100644 --- a/docs/getting_started/resources/dependencies.md +++ b/docs/getting_started/resources/dependencies.md @@ -20,8 +20,6 @@ It'll work for all the languages below! [**_Octave Information_**](https://www.gnu.org/software/octave/) -Required JSON package [**JSONio**](https://github.com/gllmflndn/JSONio) - ## Python [**_Information_**](https://www.python.org/) (Both Python 2 and 3 will work for BIDS) diff --git a/docs/getting_started/resources/glossary.md b/docs/getting_started/resources/glossary.md index 6cc6ab39..f0d79853 100644 --- a/docs/getting_started/resources/glossary.md +++ b/docs/getting_started/resources/glossary.md @@ -106,7 +106,7 @@ Example: ``` - You can find more information about `json` files - in the [Metadata file formats](../folders_and_files/metadata.md#json-files) page. + in the [Metadata file formats](../folders_and_files/metadata/json.md) page. ### M @@ -180,7 +180,7 @@ A .tsv file contains a table (like a simple excel spreadsheet) containing text. Table values are separated by tabs. - You can find more information about `TSV` files - in the [Metadata file formats](../folders_and_files/metadata.md#tsv-files) page. + in the [Metadata file formats](../folders_and_files/metadata/json.md) page. ### U diff --git a/mkdocs.yml b/mkdocs.yml index 985fa1d3..5f4d4e5b 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -110,7 +110,10 @@ nav: - getting_started/folders_and_files/index.md - getting_started/folders_and_files/folders.md - getting_started/folders_and_files/files.md - - getting_started/folders_and_files/metadata.md + - Metadata: + - getting_started/folders_and_files/metadata/index.md + - JSON: getting_started/folders_and_files/metadata/json.md + - TSV: getting_started/folders_and_files/metadata/tsv.md - getting_started/folders_and_files/derivatives.md - Resources: - getting_started/resources/index.md @@ -184,6 +187,7 @@ theme: - announce.dismiss - content.action.edit - content.code.copy + - content.tabs.link - content.tooltips - footnotes - header.autohide @@ -240,6 +244,8 @@ markdown_extensions: - name: mermaid class: mermaid format: !!python/name:pymdownx.superfences.fence_code_format + - pymdownx.tabbed: + alternate_style: true - tables - toc: anchorlink: true diff --git a/temp/participants.tsv b/temp/participants.tsv new file mode 100644 index 00000000..acd0205e --- /dev/null +++ b/temp/participants.tsv @@ -0,0 +1,3 @@ +participant_id age sex +sub-01 20 m +sub-02 30 f diff --git a/tmp.py b/tmp.py new file mode 100644 index 00000000..69661293 --- /dev/null +++ b/tmp.py @@ -0,0 +1,10 @@ +import pandas as pd + +participants = pd.DataFrame( + { + "participant_id": ["sub-01", "sub-02"], + "age": [20, 30], + "sex": ["m", "f"], + } +) +participants.to_csv("participants.tsv")