Community practices documentation first version #3

beccaclements99 · 2024-02-12T20:22:26Z

Version 1 of best practices documentation

Change Type

Checklist before review

I added everything I wanted to add to this PR.
[Code or tests only] I wrote/updated the necessary docstrings.
[Code or tests only] I ran and passed tests locally.
[Documentation only] I built the docs locally.
My contribution is harmonious with the rest of the code: I'm not introducing repetitions.
My code respects the adopted style, especially linting conventions.
The title of this PR is explanatory on its own, enough to be understood as part of a changelog.
I added or indicated the right labels.

I added information regarding the timeline of completion for this PR.

Please, comment on my PR while it's a draft and give me feedback on the development!

Upload version 1 best practices documentation

docs/source/physio_importance.md

docs/source/collect_phys.md

docs/source/process_phys.md

RayStick · 2024-02-28T15:32:36Z

Great work 👏 🤩

likeajumprope

Fantastic effort, and very well written!

likeajumprope · 2024-02-28T16:14:17Z

docs/source/physiopy_community.md

@@ -0,0 +1,11 @@
+# 2. What type of physiological data does the Physiopy community work with?
+
+The most common types of physiological data acquired in fMRI analysis within members of our community are cardiac (photoplethysmographypulse, ECG/EKG) and respiration, either ventilation (respiratory belt) and/or gas concentration (particularly expired CO2). Links are provided to their lab websites if you wish to reach out about questions or look through any methods/analyses in their publications.


The first and second sentence somehow do not flow - what does the "their" in "their lab websites" refer to? Data? Maybe change "their" to "some common examples by labs of members in the community" or something

docs/source/physiopy_community.md

Co-authored-by: Rachael Stickland <50215726+RayStick@users.noreply.github.com>

Co-authored-by: Johanna Bayer <hannabayer.89@gmail.com>

Co-authored-by: Rachael Stickland <50215726+RayStick@users.noreply.github.com>

rgbayrak

Some references are incomplete, not added to the References list as a full citation and have different formatting.

Citations under data collection section that do not appear in References:

(Liu et al., 2019)
Bulte and Wartolowska (2017)
Zvolanek et al., NeuroImage, 2023
Liu et al., 2017
Pinto et al. 2021

Also some in Data Processing section as well (disclaimer: I did not check every tab)
(Bhattacharyya and Lowe, 2004).

References Section/Tab:
Not alphabetically ordered, making it hard to read, i.e. Bottenhorn comes last.

rgbayrak · 2024-02-28T17:26:10Z

docs/source/phys_set_up.md

ex. full date, milliseconds since 12 AM, other formats… > such as full date, milliseconds since 12 AM, other formats

[SETUP_170322] Is this purposefully left in the text?

BNC > abbreviation not explained in this specific page.

Will the link be clickable of just appear next to the title for the link?

+1 for the citation of the community practice meeting [SETUP_170322] being confusing.

Thank you for spotting that @rgbayrak, I added those and more references that were missing (here 5083560). The Community Practices Meetings list was also added to the references. Maybe we can cite them like "(CPM1, March 2022)", @rgbayrak and @m-miedema?

The other comments have been addressed here 6383ff6 (except for the references to the Community Practices meetings, which will be fixed when we have a consensus on the nomenclature).

Regarding the Community Practices meetings references (e.g. [SETUP_170322]), we decided to remove them (kept them as a comment only, so they can still be tracked internally).

me-pic

Great work !

I just added really minor comments, please feel free to ignore them if not relevant.

me-pic · 2024-02-28T19:12:23Z

docs/source/phys_set_up.md

+
+When establishing a physiological monitoring setup, it is essential to follow a systematic approach. Once you have identified the signals you intend to capture, and prior to initiating data collection from a subject, it is imperative to ensure that all necessary checks from the essentials’ list have been completed.
+
+You will require **peripheral devices**, typically attached to the subject, and **recording devices** (often connected to a computer/laptop) for data acquisition and storage. Post-recording, it is crucial to accurately track events corresponding to both physiological and neuroimaging recordings at equivalent time points. To achieve this, beforehand, additional **synchronization** is necessary, unless it is already integrated into the software you are utilizing. 


Really great work 🎉 🎉

This a just a minor detail, but I would maybe just rephrase this paragraph to respect the chronogical order of proceeding, i.e. talking about the necessity to synchronize physio and neuroimaging recordings to accurately track events.

Thanks Marie-Eve! I tried to reorder the sentence according to your suggestion (here 19f0024)

LGTM ! Thank you Inês !

me-pic · 2024-02-28T19:53:55Z

docs/source/collect_phys.md

+
+## ECG
+ECG is based on electrical activity and allows a reliable monitoring of cardiac cycle features.
+ECG traces the potential change over the heart generated by the sinoatrial (SA) and atrioventricular (AV) nodes. It provides very precise beat-by-beat HR information. Depending on the system you are using and whether it is connected to another device (e.g., EEG cap), the electrodes can be placed on the chest or on the back of the subject. The ECG allows us to clearly monitor the entire QRS complex and cardiac cycle of the patient. 


Since the abbreviation was not define previously on this page, I would be tempted to explicitly write heart rate (HR) instead of just HR

Fixed here 6289ff6 to always use "heart rate".

me-pic · 2024-02-28T19:57:02Z

docs/source/collect_phys.md

+ECG is based on electrical activity and allows a reliable monitoring of cardiac cycle features.
+ECG traces the potential change over the heart generated by the sinoatrial (SA) and atrioventricular (AV) nodes. It provides very precise beat-by-beat HR information. Depending on the system you are using and whether it is connected to another device (e.g., EEG cap), the electrodes can be placed on the chest or on the back of the subject. The ECG allows us to clearly monitor the entire QRS complex and cardiac cycle of the patient. 
+
+Inside the MRI environment, the ECG will be distorted by magnetic induction and RF pulses.


I don't know if it's relevant, but I would maybe explicitly mention radiofrequency (RF) instead of just RF

Fixed here 6289ff6 to always use "radiofrequency".

me-pic · 2024-02-28T19:58:38Z

docs/source/collect_phys.md

+ECG traces the potential change over the heart generated by the sinoatrial (SA) and atrioventricular (AV) nodes. It provides very precise beat-by-beat HR information. Depending on the system you are using and whether it is connected to another device (e.g., EEG cap), the electrodes can be placed on the chest or on the back of the subject. The ECG allows us to clearly monitor the entire QRS complex and cardiac cycle of the patient. 
+
+Inside the MRI environment, the ECG will be distorted by magnetic induction and RF pulses.
+It is important to note that like most signals, the ECG is susceptible to artifacts introduced by magnetic induction and RF pulses and to cardio-ballistic effects from the mechanical movement of the heart and flow of blood in the magnetic field that need to be cleaned appropriately after the scan (Kugel et al., 2003). Certain commercial devices have built in filters to suppress MRI-related artifacts; however, understanding what is real and noise in your signal is essential prior to using it for any kind of analysis (Abacherli, et al., 2005; Gray et al., 2009; Odille et al., 2007). 


what is real and what is noise

Fixed here 6289ff6.

m-miedema · 2024-02-29T11:57:21Z

docs/source/collect_phys.md

Typo: For particularly thin subjects, adding a pad between the belt and the chest might be necessary to avoid saturation due to loosen belts.

Fixed here 6289ff6.

m-miedema · 2024-02-29T12:02:04Z

It's exciting the way this is coming together! My main comments are that

The in-text references to community meetings, while helpful internally, are not helpful in this context. Perhaps there could be a list of topics that have been discussed and in-text references that make it more clear that we're referencing a conversation? E.g. (Community Practice Meeting: Respiration, date).
The comment regarding eddy currents should be moved out of the gas section and into a more general practice for collecting data.
I'm not sure if this is in the scope of this PR, but section 6 seems to currently imply that e.g. HRV or other physiological derivatives should be directly input into a GLM. It seems unhelpful to include this section without at least mentioning PRFs.

goodalse2019 · 2024-03-12T01:40:34Z

This all looks amazing! Awesome job everyone. Super excited for this to go public.

joanacspinto · 2024-03-12T14:51:49Z

Hi all, I've taken a brief look at this - amazing work! Well done :)
Just some minor points:

the references to the community meetings look a bit odd
the order. I would recommend moving "2. Community" to a later stage. I like the flow of 1. motivation, 2. setting up the system, 3. acquiring data, 3. analysing data etc

afni-dglen · 2024-03-20T06:36:49Z

This is really nice work on this documentation, and I learned a lot reading this. I will note a few nit-picky details - please see the attached md files.

collect_phys.md
process_phys.md
physio_importance.md
phys_set_up.md

- Added a small summary about the references - Added the list of Community Practices Meetings and short descriptions - Updated the references with missing items and ordered them

- Minor formatting changes - Minor text changes in the "Syncing with the neuroimaging acquisition" subsection

- Added two missing references - Removed one reference that was not being used

Updated based on feedback from Daniel Glen

More updates based on feedback from Daniel Glen

- Removed CMP in-text references - Minor text changes (reordered one paragraph according to the comments)

Updated based on feedback from Daniel Glen

Make this section appear first instead of second (here I am just changing the numbering)

- Added list of contributors (orcid, affiliations, name)

- Minor changes

smoia · 2024-05-28T20:40:01Z

Are we pushing the button?

Yes, we are.

🎉 🎉 🎉

smoia · 2024-05-28T20:40:35Z

🚀 PR was released in 2024.0.0 🚀

Add files via upload

f969bbe

Upload version 1 best practices documentation

smoia added the Minormod This PR generally closes an "Enhancement" issue. It increments the minor version (0.+1.0) label Feb 13, 2024

beccaclements99 added 2 commits February 13, 2024 10:03

Update index.rst

1095d82

Merge branch 'master' into 1.0

a4b5aa2

RayStick reviewed Feb 28, 2024

View reviewed changes

docs/source/physio_importance.md Outdated Show resolved Hide resolved

RayStick reviewed Feb 28, 2024

View reviewed changes

docs/source/collect_phys.md Outdated Show resolved Hide resolved

RayStick reviewed Feb 28, 2024

View reviewed changes

docs/source/process_phys.md Outdated Show resolved Hide resolved

likeajumprope reviewed Feb 28, 2024

View reviewed changes

smoia and others added 4 commits February 28, 2024 18:15

Update docs/source/process_phys.md

0d13426

Co-authored-by: Rachael Stickland <50215726+RayStick@users.noreply.github.com>

Update docs/source/physiopy_community.md

8435001

Co-authored-by: Johanna Bayer <hannabayer.89@gmail.com>

Update docs/source/collect_phys.md

b543eab

Co-authored-by: Rachael Stickland <50215726+RayStick@users.noreply.github.com>

Update docs/source/physio_importance.md

fba0429

Co-authored-by: Rachael Stickland <50215726+RayStick@users.noreply.github.com>

rgbayrak suggested changes Feb 28, 2024

View reviewed changes

me-pic reviewed Feb 28, 2024

View reviewed changes

m-miedema reviewed Feb 29, 2024

View reviewed changes

isesteves and others added 10 commits March 21, 2024 15:03

Update references.md

5083560

- Added a small summary about the references - Added the list of Community Practices Meetings and short descriptions - Updated the references with missing items and ordered them

Update phys_set_up.md

6383ff6

- Minor formatting changes - Minor text changes in the "Syncing with the neuroimaging acquisition" subsection

Update references.md

df7e1ca

- Added two missing references - Removed one reference that was not being used

Update physio_importance.md

21d9eab

Updated based on feedback from Daniel Glen

Update process_phys.md

6d634de

Updated based on feedback from Daniel Glen

Update process_phys.md

c4f8927

More updates based on feedback from Daniel Glen

Update phys_set_up.md

19f0024

- Removed CMP in-text references - Minor text changes (reordered one paragraph according to the comments)

Update phys_set_up.md

bd08ca2

Updated based on feedback from Daniel Glen

Update collect_phys.md

727955d

Updated based on feedback from Daniel Glen

Update physiopy_community.md

b652d30

Make this section appear first instead of second (here I am just changing the numbering)

Update .zenodo.json

c734612

- Added list of contributors (orcid, affiliations, name)

github-actions bot added the Internal Changes affect the internal API. It doesn't increase the version, but produces a changelog label May 27, 2024

isesteves and others added 22 commits May 27, 2024 19:03

Update .zenodo.json

9471fc0

- Minor changes

Fix zenodo.json

66c0f45

Merge branch 'master' into 1.0

e70437b

docs: add @likeajumprope as a contributor

f04e675

docs: add @rgbayrak as a contributor

e4573cc

docs: add @beccaclements99 as a contributor

71f9e03

docs: add @isesteves as a contributor

7a39a1b

docs: add @patriciampfigueiredo as a contributor

e1cfdef

docs: add @afni-dglen as a contributor

804cf98

docs: add @goodalse2019 as a contributor

63a7753

docs: add @m-miedema as a contributor

5ccc844

docs: add @smoia as a contributor

fbb6594

docs: add @murphyk2 as a contributor

d4bae01

docs: add @me-pic as a contributor

74fc93a

docs: add @joanacspinto as a contributor

8408937

docs: add @RayStick as a contributor

2257716

docs: add @kristinazvolanek as a contributor

c0acefb

Hopefully fixing allcontributors

9374615

Reverts a few commits to remove table from index

484ae6d

Add citation

28c8912

Move to md file

889b961

Move contributors

ae8000f

github-actions bot added the Documentation This issue or PR is about the documentation label May 28, 2024

smoia merged commit f2267c1 into master May 28, 2024
2 checks passed

smoia added the released This issue/pull request has been released label May 28, 2024

smoia deleted the 1.0 branch July 15, 2024 17:27

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Community practices documentation first version #3

Community practices documentation first version #3

beccaclements99 commented Feb 12, 2024 •

edited by smoia

Loading

RayStick commented Feb 28, 2024

likeajumprope left a comment

likeajumprope Feb 28, 2024

rgbayrak left a comment •

edited

Loading

rgbayrak Feb 28, 2024

m-miedema Feb 29, 2024

isesteves Mar 21, 2024

isesteves Mar 21, 2024

isesteves Mar 27, 2024

me-pic left a comment

me-pic Feb 28, 2024

isesteves Mar 26, 2024

me-pic Mar 27, 2024

me-pic Feb 28, 2024 •

edited

Loading

isesteves Mar 26, 2024

me-pic Feb 28, 2024

isesteves Mar 26, 2024

me-pic Feb 28, 2024

isesteves Mar 26, 2024

m-miedema Feb 29, 2024

isesteves Mar 26, 2024

m-miedema commented Feb 29, 2024 •

edited

Loading

goodalse2019 commented Mar 12, 2024

joanacspinto commented Mar 12, 2024

afni-dglen commented Mar 20, 2024 •

edited

Loading

smoia commented May 28, 2024

smoia commented May 28, 2024

		@@ -0,0 +1,11 @@
		# 2. What type of physiological data does the Physiopy community work with?

		The most common types of physiological data acquired in fMRI analysis within members of our community are cardiac (photoplethysmographypulse, ECG/EKG) and respiration, either ventilation (respiratory belt) and/or gas concentration (particularly expired CO2). Links are provided to their lab websites if you wish to reach out about questions or look through any methods/analyses in their publications.


		When establishing a physiological monitoring setup, it is essential to follow a systematic approach. Once you have identified the signals you intend to capture, and prior to initiating data collection from a subject, it is imperative to ensure that all necessary checks from the essentials’ list have been completed.

		You will require peripheral devices, typically attached to the subject, and recording devices (often connected to a computer/laptop) for data acquisition and storage. Post-recording, it is crucial to accurately track events corresponding to both physiological and neuroimaging recordings at equivalent time points. To achieve this, beforehand, additional synchronization is necessary, unless it is already integrated into the software you are utilizing.

Community practices documentation first version #3

Community practices documentation first version #3

Conversation

beccaclements99 commented Feb 12, 2024 • edited by smoia Loading

Change Type

Checklist before review

RayStick commented Feb 28, 2024

likeajumprope left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

rgbayrak left a comment • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

me-pic left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

me-pic Feb 28, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

m-miedema commented Feb 29, 2024 • edited Loading

goodalse2019 commented Mar 12, 2024

joanacspinto commented Mar 12, 2024

afni-dglen commented Mar 20, 2024 • edited Loading

smoia commented May 28, 2024

smoia commented May 28, 2024

beccaclements99 commented Feb 12, 2024 •

edited by smoia

Loading

rgbayrak left a comment •

edited

Loading

me-pic Feb 28, 2024 •

edited

Loading

m-miedema commented Feb 29, 2024 •

edited

Loading

afni-dglen commented Mar 20, 2024 •

edited

Loading