[DOC] Governance update (#615)

* Added GovernanceSteeringDraft * Cleaning up governance text * cleaning up hyperlinks * Added project scope * typo fix Co-authored-by: Joshua Teves <[email protected]> * typo fix Co-authored-by: Joshua Teves <[email protected]> * Update docs/governance.rst typo fix Co-authored-by: Joshua Teves <[email protected]> * Update docs/governance.rst opening sentence Co-authored-by: Elizabeth DuPre <[email protected]> * Update docs/governance.rst typo correction Co-authored-by: Elizabeth DuPre <[email protected]> * Update docs/governance.rst contributors can review PR Co-authored-by: Elizabeth DuPre <[email protected]> * Update docs/governance.rst community review PR2 Co-authored-by: Elizabeth DuPre <[email protected]> * Signif restructure based on PR feedback * Update docs/governance.rst typo fix Co-authored-by: Taylor Salo <[email protected]> * Update docs/governance.rst rewording Co-authored-by: Joshua Teves <[email protected]> * Update docs/governance.rst rewording Co-authored-by: Joshua Teves <[email protected]> * Update docs/governance.rst typo Co-authored-by: Joshua Teves <[email protected]> * Update docs/governance.rst typo Co-authored-by: Joshua Teves <[email protected]> * Update docs/governance.rst typo Co-authored-by: Joshua Teves <[email protected]> * Update docs/governance.rst rewording Co-authored-by: Joshua Teves <[email protected]> * Update docs/governance.rst rewording * Update docs/governance.rst typo Co-authored-by: Joshua Teves <[email protected]> * Update docs/governance.rst typo Co-authored-by: Joshua Teves <[email protected]> * Update docs/governance.rst typo Co-authored-by: Joshua Teves <[email protected]> * Update docs/governance.rst typo Co-authored-by: Joshua Teves <[email protected]> * Update docs/governance.rst rewording Co-authored-by: Joshua Teves <[email protected]> * Update docs/governance.rst typo Co-authored-by: Joshua Teves <[email protected]> * fixing typos in governance.rst Co-authored-by: Joshua Teves <[email protected]> * Rewording edits in contributing.rst and governance.rst Co-authored-by: Elizabeth DuPre <[email protected]> * Apply suggestions from code review Changed votes from maintainers to contributors and changed voting timelines. Several other style changes or typo fixes. * Update docs/governance.rst added tentative steering committee * Apply suggestions from code review Several language changes for clarity & added Javier as a Maintainer. Co-authored-by: Eneko Uruñuela <[email protected]> * Adds steering committee link * Fix accidental heading * Fixes missing CoC link * Add @smoia as a CoC enforcer * Shortened line length and fixed typos * Fixes rst mistakes from myself * Fixes missing colons * Removes trailing whitespace * Fixes periods and whitespace in roadmap.rst * Text cleaning. Removed Kirstie as a maintainer * Apply suggestions from code review typo fixes Co-authored-by: Joshua Teves <[email protected]> * Apply suggestions from code review typo/working fixes suggested by stalo Co-authored-by: Taylor Salo <[email protected]> * Update docs/contributing.rst grammer fix * Apply suggestions from code review Language clarifications from emdupre's review Co-authored-by: Elizabeth DuPre <[email protected]> * Fix warnings in html make Co-authored-by: Joshua Teves <[email protected]> Co-authored-by: Elizabeth DuPre <[email protected]> Co-authored-by: Taylor Salo <[email protected]> Co-authored-by: Eneko Uruñuela <[email protected]> Co-authored-by: Joshua Teves <[email protected]>
ME-ICA · Dec 8, 2020 · 45e5ad7 · 45e5ad7
1 parent 23d58f4
commit 45e5ad7
Show file tree

Hide file tree

Showing 5 changed files with 427 additions and 44 deletions.
diff --git a/docs/contributing.rst b/docs/contributing.rst
@@ -8,46 +8,121 @@ For a more practical guide to the tedana development, please see our
 
 .. _contributing guide: https://github.com/ME-ICA/tedana/blob/master/CONTRIBUTING.md
 
-.. _governance:
-
-Governance
-----------
-
-Governance is a hugely important part of any project.
-It is especially important to have clear process and communication channels
-for open source projects that rely on a distributed network of volunteers, such as ``tedana``.
-
-``tedana`` is currently supported by a small group of five core developers.
-Even with only five members involved in decision making processes,
-we've found that setting expectations and communicating a shared vision has great value.
-
-By starting the governance structure early in our development,
-we hope to welcome more people into the contributing team.
-We are committed to continuing to update the governance structures as necessary.
-Every member of the ``tedana`` community is encouraged to comment on these processes and suggest improvements.
-
-As the first interim `Benevolent Dictator for Life (BDFL)`_,
-Elizabeth DuPre is ultimately responsible for any major decisions pertaining to ``tedana`` development.
-However, all potential changes are explicitly and openly discussed in the described channels of
-communication, and we strive for consensus amongst all community members.
-
-.. _Benevolent Dictator for Life (BDFL): https://en.wikipedia.org/wiki/Benevolent_dictator_for_life
-
 Code of conduct
 ```````````````
 
-All ``tedana`` community members are expected to follow our `code of conduct`_
-during any interaction with the project.
+All ``tedana`` community members are expected to follow our code of conduct
+during any interaction with the project. `The full code of conduct is here`_.
 That includes---but is not limited to---online conversations,
 in-person workshops or development sprints, and when giving talks about the software.
 
 As stated in the code, severe or repeated violations by community members may result in exclusion
 from collective decision-making and rejection of future contributions to the ``tedana`` project.
 
-.. _code of conduct: https://github.com/ME-ICA/tedana/blob/master/CODE_OF_CONDUCT.md
+.. _The full code of conduct is here: https://github.com/ME-ICA/tedana/blob/master/CODE_OF_CONDUCT.md
+
+Scope of tedana
+```````````````
+tedana is a collection of tools, software and a community related to echo time
+(TE) dependent analyses. The umbrella of tedana covers a number of overlapping,
+but somewhat distinct, ideas related to multi-echo analysis. This scope includes
+collecting multi-echo data (Acquisition), combining those echoes together
+(Combination), with optional noise removal (Denoising), inspecting the outputs
+(Visualization) and answering multi-echo related questions (Community). In
+general, tedana accepts previously preprocessed data to produce outputs that
+are ready for further analyses. 
+
+Acquisition
+-----------
+
+While the development of multi-echo sequences is beyond the current scope
+of tedana, the tedana community is committed to providing guidelines on current
+multi-echo implementations. This will include both specific instructions for
+how to collect multi-echo data for multiple vendors as well as details about
+what types of data have been collected thus far. These details are subject to
+change, and are intended to provide users with an idea of what is possible,
+rather than definitive recommendations.
+
+Our focus is on functional MRI, including both magnitude and phase data,
+however we understand that quantitative mapping has the potential to aid in
+data processing. Thus, we believe that some details on non-functional MRI
+acquisitions, such as detailed T2* mapping, may fall within the scope of
+tedana.
+Acquisition related details can be found in the `tedana Documentation.`_
+
+.. _tedana Documentation.: https://tedana.readthedocs.io/en/latest/acquisition.html
+
+Combining echoes
+----------------
+
+An early step in processing data collected with multiple echoes is the
+combination of the data into a single time series. We currently implement
+multiple options to combine multi-echo data and will add more as they continue
+to be developed. This is an area of active development and interest.
+
+Denoising
+---------
+
+tedana was developed out of a package known as `multi-echo ICA, ME-ICA, or MEICA`_
+developed by Dr. Prantik Kundu. Though the usage of ICA for classification of
+signal vs noise components has continued in tedana, this is not a rule. The
+tedana community is open and encouraging of new denoising methods, whether or not they
+have a basis in ICA. 
+
+Specifically, we are interested in any method that seeks to use the information from multiple
+echoes to identify signal (defined here as BOLD signals arising from neural
+processing) and noise (defined here as changes unrelated to neural
+processing, such as motion, cardiac, respiration).
+
+tedana is primarily intended to work on volume data, that is, data that is
+still in structured voxel space. This is because several of the currently used denoising metrics rely on spatial continuity, and they have not yet been updated to consider continuity over cortical vertices.
+Therefore, surface-based denoising is not currently
+within the scope of tedana, but code could be written so that it is a
+possible option in the future.
+
+Currently tedana works on a single subject, run by run basis; however, methods
+that use information across multiple runs are welcome. 
+
+.. _`multi-echo ICA, ME-ICA, or MEICA`: https://github.com/ME-ICA/me-ica
+
+Visualization
+-------------
+
+As part of the processing stream, tedana provides figures and an 
+HTML-based report for inspecting results. These are intended to help
+users understand the outputs from tedana and diagnose problems. Though a
+comprehensive viewer (such as fsleyes) is outside of the scope of tedana, we
+will continue to improve the reports and add new information as needed.
+
+Community
+---------
+
+tedana is intended to be a community of multi-echo users. The primary resource
+is the github repository and related documentation. In addition, the tedana
+group will attempt to answer multi-echo related questions on NeuroStars 
+(`multi-echo tag <https://neurostars.org/tag/multi-echo>`_ or
+`tedana tag <https://neurostars.org/tag/tedana>`_). 
+
+What tedana isn’t
+-----------------
+
+While the list of things that do not fall under the scope of tedana are
+infinite, it is worth mentioning a few points:
+
+- tedana will not offer a GUI for usage 
+- it is intended to be either a stand
+  alone processing package or serve as a processing step as part of a larger
+  package (i.e. fmriprep or afni_proc.py). 
+- tedana will not provide basic preprocessing steps, such as motion correction
+  or slice timing correction. While these were previously part of the ME-ICA
+  pipeline, the sheer variety of possible choices, guidelines and data types
+  precludes including it within the tedana package.
+- tedana will not provide statistical analyses in the form of general linear models,
+  connectivity or decoding. Though multi-echo data is amenable to all methods
+  of analysis, these methods will not be included in the tedana package.
 
 tedana's development philosophy
---------------------------------------
+```````````````````````````````
 
 In contributing to any open source project,
 we have found that it is hugely valuable to understand the core maintainers' development philosophy.
@@ -65,7 +140,7 @@ These are:
 .. _exposing options to the user:
 
 Which options are available to users?
-`````````````````````````````````````
+-------------------------------------
 
 The ``tedana``  developers are committed to providing useful and interpretable outputs
 for a majority of use cases.
@@ -104,7 +179,7 @@ listed on the ``tedana`` :ref:`support_ref` page.
 .. _prioritizing project developments:
 
 Structuring project developments
-````````````````````````````````
+--------------------------------
 
 The ``tedana``  developers have chosen to structure ongoing development around specific goals.
 When implemented successfully, this focuses the direction of the project and helps new contributors
@@ -129,7 +204,7 @@ This allows us to:
 .. _backwards compatibility with meica:
 
 Is ``tedana`` backwards compatible with MEICA?
-``````````````````````````````````````````````
+----------------------------------------------
 
 The short answer is No.
 
@@ -158,7 +233,7 @@ If you'd like to use MEICA as has been previously published the code is availabl
 .. _future-proofing for continuous development:
 
 How does ``tedana`` future-proof its development?
-`````````````````````````````````````````````````
+-------------------------------------------------
 
 ``tedana``  is a reasonably young project that is run by volunteers.
 No one involved in the development is paid for their time.
@@ -179,7 +254,7 @@ applicable in the future as other needs arise.
 .. _when to release new software versions:
 
 When to release a new version
-`````````````````````````````
+-----------------------------
 
 In the broadest sense, we have adopted a "you know it when you see it" approach
 to releasing new versions of the software.
@@ -203,13 +278,13 @@ Any member of the ``tedana``  community can propose that a new version is releas
 They should do so by opening an issue recommending a new release and giving a
 1-2 sentence explanation of why the changes are sufficient to update the version.
 More information about what is required for a release to proceed is available
-in the :ref:`release checklist`.
+in the :ref:`release-checklist`.
 
 
-.. _release checklist:
+.. _release-checklist:
 
 Release Checklist
-"""""""""""""""""
+-----------------
 
 This is the checklist of items that must be completed when cutting a new release of tedana.
 These steps can only be completed by a project maintainer, but they are a good resource for