From 38c0997cb9b501cb4abf1ee9d4faf5e679b6a964 Mon Sep 17 00:00:00 2001 From: Elizabeth DuPre Date: Thu, 1 Nov 2018 11:36:15 -0400 Subject: [PATCH 01/27] [DOC] RFC: Roadmap --- docs/index.rst | 1 + docs/roadmap.rst | 197 +++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 198 insertions(+) create mode 100644 docs/roadmap.rst diff --git a/docs/index.rst b/docs/index.rst index 326178cfe..d3eac653d 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -135,6 +135,7 @@ tedana is licensed under GNU Lesser General Public License version 2.1. approach outputs contributing + roadmap api Indices and tables diff --git a/docs/roadmap.rst b/docs/roadmap.rst new file mode 100644 index 000000000..5b503159e --- /dev/null +++ b/docs/roadmap.rst @@ -0,0 +1,197 @@ +The ``tedana`` Roadmap +====================== + +Project vision +-------------- + +ME-EPI processing is not well integrated into major preprocessing packages, +yielding duplicated and unmaintained code. +```tedana`` has been developed to address this need and will serve as a central repository +for standard ME-EPI denoising as well as a testing ground for novel ME-EPI denoising methods. +This will jointly reduce the external burden on pipeline maintainers, +facilitate increased ME-EPI adoption, and enable future development in ME-EPI denoising. + +Metrics of success and corresponding milestones +----------------------------------------------- + +We will know that we have been successful in creating ``tedana`` when we have succeeded in providing +several concrete deliverables, which can be broadly categorized into: + +1. *:ref:`Documentation`*, +2. *:ref:`Transparent and Reproducible Processing`*, +3. *:ref:`Testing`*, +4. *:ref:`Workflow Integrations`*, +5. *:ref:`Extensions and Improvements to ME-EPI processing`*, and +6. *:ref:`Developing a healthy community`* + +Each deliverable has been synthesized into a milestone that gives the ``tedana`` community a link +between the issues and the high level vision for the project. + +.. _Documentation: + +Documentation +````````````` +**Summary**: +One long-standing concern with ME-EPI denoising has been the availability of +documentation for the method outside of published scientific papers. +To address this, we have created `a ReadTheDocs site`_; +however, there are still several sections either explicitly marked as "# TODO" +or otherwise missing crucial information. + +We are committed to providing helpful documentation for all users of ``tedana``. +One metric of success, then, is to develop documentation that includes: + +1. Motivations for conducting echo time dependent analysis, +2. A collection of key ME-EPI references from the published literature, +3. Tutorials on how to use ``tedana``, +4. The different processing steps that are conducted in each workflow, +5. An up-to-date description of the API, +6. A transparent explanation of the different decisions that are made through the ```tedana`` pipeline, and +7. Where to seek support + +.. _a ReadTheDocs site: https://tedana.readthedocs.io + +**Associated Milestone**: +This milestone will close when the online documentation contains the minimum necessary information +to orient a complete newcomer to ME-EPI, both on the theoretical basis of the method as well as +the practical steps used in ME-EPI denoising. + +.. _Transparent and Reproducible Processing: + +Transparent and reproducible processing +``````````````````````````````````````` +**Summary**: +Alongside the lack of existing documentation, +there is a general unfamiliarity with how selection criteria are applied to individual data sets. +This lack of transparency, combined with the non-deterministic nature of the decomposition, +has generated significant uncertainty when interpreting results. + +In order to build and maintain confidence in ME-EPI processing, +any analysis software---including ``tedana``---must provide enough information such that +the user is empowered to conduct transparent and reproducible analyses. +This will permit clear reporting of the ME-EPI results in published studies +and facilitate a broader conversation in the scientific community on the nature of ME-EPI processing. + +We are therefore committed to making ``tedana`` analysis transparent and reproducible +such that we report back all processing steps applied to any individual data set, +including the specific selection criteria used in making denoising decisions. +This, combined with the reproducibility afforded by seeding all non-deterministic steps, +will enable both increased confidence and better reporting of ME-EPI results. + +A metric of success for ``tedana`` then, should be enhancements to the code such that +1. Non-deterministic steps are made reproducible by enabling access to a "seed value", and +2. The decision process for individual component data is made accessible to the end user. + +**Associated Milestone**: +This milestone will close when when the internal decision making process for +component selection is made accessible to the end user, +and an analysis can be reproduced by an independent researcher who has access to the same data. + +.. _Testing: + +Testing +``````` +**Summary**: +Historically, the lack of testing for ME-EPI analysis pipelines has prevented new +developers from engaging with the code for fear of silently breaking or otherwise degrading +the existing implementation. +Moving forward, we want to grow an active development community, +where developers feel empowered to explore new enhancements to the ``tedana`` code base. + +One means to ensure that new code does not introduce silent failures is through extensive testing. +We are therefore committed to implementing high test coverage at both +the unit test and integration test levels; +that is, both in testing individual functions and broader workflows, respectively. + +A metric of success should thus be: +1. Achieving 90% test coverage for unit tests, as well as +2. Three distinguishable integration tests over a range of possible acquisition conditions. + +**Milestone**: +This milestone will close when we have 90% test coverage for unit tests and +three distinguishable integration tests, +varying number of echos and acquisition type (i.e., task vs. rest). + +.. _Workflow Integrations: + +Workflow integration: AFNI +`````````````````````````` +**Summary**: +Currently, `afni_proc.py`_ distributes an older version of ``tedana``, +around which they have built a wrapper script, `tedana_wrapper.py`_, to ensure compatibility. +AFNI users at this point are therefore not accessing the latest version of ``tedana``. +We will grow our user base if ``tedana`` can be accessed through AFNI, +and we are therefore committed to supporting native integration of ``tedana`` in AFNI. + +.. _afni_proc.py: https://afni.nimh.nih.gov/pub/dist/doc/program_help/afni_proc.py.html +.. _tedana_wrapper.py: https://github.com/afni/afni/blob/a3288abefb66bc7c76e98fdf13425ab48651bf36/src/python_scripts/afni_python/tedana_wrapper.py + +One metric of success, therefore, will be if we can demonstrate sufficient stability and support +such that the ``afni_proc.py`` maintainers are willing to switch to ``tedana`` as the recommended +method of accessing ME-EPI denoising in AFNI. +We will aim to aid in this process by increasing compatibility between ``tedana`` +and the ```afni_proc.py`` workflow, eliminating the need for an additional wrapper script. +For example, ``tedana`` could directly accept BRIK/HEAD files, +facilitating interoperability with other AFNI pipelines. + +**Milestone**: + This milestone will close when ``tedana`` is stable enough such that the recommended default in + ``afni_proc.py`` is to access ME-EPI denoising via ``pip install tedana``, + rather than maintaining the alternative version that is currently used. + + +Workflow integration: BIDS +`````````````````````````` +**Summary**: +Currently, the BIDS ecosystem has limited support for ME-EPI processing. +We will grow our user base if ``tedana`` is integrated into existing BIDS Apps and +therefore accessible to members of the BIDS community. +One promising opportunity is if ``tedana`` can be used natively in `FMRIPrep`_. +Some of the work is not required at this repository, but other changes will need to happen here; +for example, making sure the outputs are BIDS compliant. + +A metric of success, then, will be +1. Fully integrating ``tedana`` into ``FMRIPrep``, and +2. Making ``tedana`` outputs compliant with the `BIDS derivatives specification`_. + +.. _FMRIPrep: https://github.com/poldracklab/fmriprep +.. _BIDS derivatives specification: https://docs.google.com/document/d/1Wwc4A6Mow4ZPPszDIWfCUCRNstn7d_zzaWPcfcHmgI4/edit + +**Milestone**: +This milestone will close when the denoising steps of ``tedana`` are stable enough +to integrate into ``FMRIPrep`` and the ```FMRIPrep`` project is updated to process ME-EPI scans. + +.. _Extensions and Improvements to ME-EPI processing: + +Method extensions & improvements +```````````````````````````````` +**Summary**: +Overall, each of the listed deliverables will support a broader goal: +to improve on ME-EPI processing itself. +This is an important research question and will advance the state-of-the-art in ME-EPI processing. + +A metric of success here would be +* *EITHER* integrating a new decomposition method, beyond ICA +* *OR* validating new selection criteria. + +**Milestone**: +This milestone will close when the codebase is stable enough to integrate novel methods +into ``tedana``, and that happens! + +.. _Developing a healthy community: + +Developing a healthy community +`````````````````````````````` +**Summary**: +In developing ``tedana``, we are committed to fostering a healthy community. +A healthy community is one in which the maintainers are happy and not overworked, +and which empowers users to contribute back to the project. +By making ``tedana`` stable and well-documented, with enough modularity to integrate improvements, +we will enable new contributors to feel that their work is welcomed. + +We therefore have one additional metric of success: +1. An outside contributor integrates an improvement to ME-EPI denoising. + +**Milestone**: +This milestone will probably never close, +but will serve to track issues related to building and supporting the ``tedana`` community. From a0968a1480ac487bc79004aefe496241149e4173 Mon Sep 17 00:00:00 2001 From: Elizabeth DuPre Date: Thu, 1 Nov 2018 13:04:12 -0400 Subject: [PATCH 02/27] [DOC] Explain contributing philosophy --- docs/contributing.rst | 181 +++++++++++++++++++++++++++++++++++------- 1 file changed, 151 insertions(+), 30 deletions(-) diff --git a/docs/contributing.rst b/docs/contributing.rst index caf9399f6..34cdad2a9 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -1,50 +1,171 @@ Contributing to tedana ====================== -This document explains how to set up a development environment for contributing -to tedana and code style conventions we follow within the project. -For a more general guide to the tedana development, please see our -`contributing guide`_. Please also follow our `code of conduct`_. +This document explains contributing to ``tedana`` at a very high level, +with a focus on project governance and development philosophy. +For a more practical guide to the tedana development, please see our +`contributing guide`_. .. _contributing guide: https://github.com/ME-ICA/tedana/blob/master/CONTRIBUTING.md -.. _code of conduct: https://github.com/ME-ICA/tedana/blob/master/CODE_OF_CONDUCT.md +Governance +---------- -Style Guide ------------ +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``. -Code -```` +```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. -Docstrings should follow `numpydoc`_ convention. We encourage extensive -documentation. +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. -The code itself should follow `PEP8`_ convention as much as possible, with at -most about 500 lines of code (not including docstrings) per script. +Code of conduct +``````````````` -.. _numpydoc: https://numpydoc.readthedocs.io/en/latest/format.html -.. _PEP8: https://www.python.org/dev/peps/pep-0008/ +All ``tedana`` community members are expected to follow our `code of conduct`_ +during any interaction with the project. +That includes---but is not limited to---online conversations, +in-person workshops or development sprints, and when giving talks about the software. -Pull Requests -````````````` +As is 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. -We encourage the use of standardized tags for categorizing pull requests. -When opening a pull request, please use one of the following prefixes: +.. _code of conduct: https://github.com/ME-ICA/tedana/blob/master/Code_of_Conduct.md - + **[ENH]** for enhancements - + **[FIX]** for bug fixes - + **[TST]** for new or updated tests - + **[DOC]** for new or updated documentation - + **[STY]** for stylistic changes - + **[RF]** for refactoring existing code +```tedana``'s development philosophy +-------------------------------------- -Pull requests should be submitted early and often! -If your pull request is not yet ready to be merged, please also include the **[WIP]** prefix. -This tells the development team that your pull request is a "work-in-progress", -and that you plan to continue working on it. +In contributing to any open source proect, +we have found that it is hugely valuable to understand the core maintainers's development philosophy. +In order to aid other contributors in onboarding to ``tedana`` development, +we have therefore laid out our shared opinion on several major decision points. +These are: + +#. :ref:`exposing options to the user`, +#. :ref:`prioritizing project developments`, +#. :ref:`future-proofing for continuous development`, and +#. :ref:`when to release new software versions` + + +.. _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. +In doing so, we have made a decision to embrace defaults which support the broadest base of users. +For example, the choice of a widely-accepted ICA cost function, +or a well-validated dimensionality reduction threshold for retaining PCA components. +These two parts of the ``tedana`` processing pipeline have huge impact on the results, +and which are difficult for individual researchers to form an opinion on. + +The ``tedana`` "opinionated approach" is therefore to provide reasonable defaults, +and to hide some options from the top level workflows. + +This decision has two key benefits: +1. By default, users should get high quality results from running the pipelines, and +2. The work required of the ``tedana`` developers to maintain the project is more focused and somewhat restricted. + +It is important to note that ``tedana`` is shipped under `an LGPL2 license`_ which means that +the code can---at all times---be cloned and re-used by anyone for any purpose. +"Power users" will always be able to access and extend all of the options available. +We encourage those users to feed back their work into ``tedana`` development, +particularly if they have good evidence for updating the default values. + +We understand that it is possible to build the software to provide more +options within the existing framework, but have chosen to focus on `the 80 percent use cases`_. + +You can provide feedback on this philosophy through any of the channels +listed on the ``tedana`` `get in touch`_ page. + +.. _an LGPL2 license: https://github.com/ME-ICA/tedana/blob/master/LICENSE +.. _the 80 percent use cases: https://en.wikipedia.org/wiki/Pareto_principle#In_software +.. _get in touch: https://github.com/ME-ICA/tedana/blob/master/CONTRIBUTING.md#joining-the-conversation + + +.. _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 prioritise what work needs to be completed. +We have outlined our goals for ``tedana`` in our :doc:`roadmap`, +which we encourage all new contributors to read and `give feedback`_ on. + +In order to more directly map between our :doc:`roadmap` and ongoing `project issues`_, +we have also created `milestones in the github repository`_. + +.. _give feedback: https://github.com/ME-ICA/tedana/blob/master/CONTRIBUTING.md#joining-the-conversation +.. _project issues: https://github.com/ME-ICA/tedana/issues +.. _milestones in the github repository: https://github.com/me-ica/tedana/milestones + +This allows us to + +1. Label individual issues as supporting specific aims and +2. Helps us to measure progress towards each aim's concrete deliverable(s). + + +.. _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. +In order to focus our limited time, we have made the decision to not let future possibilities limit +or overcomplicate the most immediately required features. +That is, to `not let the perfect be the enemy of the good`_. + +.. _not let the perfect be the enemy of the good: https://en.wikipedia.org/wiki/Perfect_is_the_enemy_of_good + +While this stance will almost certainly yield ongoing refactoring as the scope of the software expands, +the team's commitment to transparency, reproducibility, and extensive testing +mean that this work should be relatively manageable. + +We hope that the lessons we learn building something useful in the short term will be +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. + +To try to be more concrete, if a change to the project substantially changes the user's experience +of working with the ``tedana`` module, it would be helpful to release an updated version. +Additional functionality and bug fixes are very clear opportunities to release updated versions, +but there will be many other reasons to update the software as hosted on `PyPi`_. + +.. _PyPi: https://pypi.org/project/tedana/ + +To give two concrete examples of slightly less obvious cases: + +1. A substantial update to the documentation that makes ``tedana`` easier to use **would** count as +a substantial change to ``tedana`` and a new release should be considered. +2. In contrast, updating code coverage with additional unit tests does not affect the +**user's** experience with ``tedana`` and therefore does not require a new release. + +Any member of the ``tedana`` community can propose that a new version is released. +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`. + + +.. _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 From ef2f4d00b478a0e14e8711516eb2c9b5840a9f0d Mon Sep 17 00:00:00 2001 From: Elizabeth DuPre Date: Thu, 1 Nov 2018 13:38:43 -0400 Subject: [PATCH 03/27] [DOC] Update contributing guidelines --- CONTRIBUTING.md | 102 ++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 85 insertions(+), 17 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f9c381dc2..f4dc34c87 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,16 +1,20 @@ -# Contributing to tedana +# Contributing to `tedana` -Welcome to the tedana repository! We're excited you're here and want to contribute. +Welcome to the `tedana` repository! We're excited you're here and want to contribute. -These guidelines are designed to make it as easy as possible to get involved. If you have any questions that aren't discussed below, please let us know by opening an [issue][link_issues]! +These guidelines are designed to make it as easy as possible to get involved. +If you have any questions that aren't discussed below, please let us know by opening an [issue][link_issues]! -Before you start you'll need to set up a free [GitHub][link_github] account and sign in. Here are some [instructions][link_signupinstructions]. +Before you start you'll need to set up a free [GitHub][link_github] account and sign in. +Here are some [instructions][link_signupinstructions]. Already know what you're looking for in this guide? Jump to the following sections: + * [Joining the conversation](#joining-the-conversation) -* [Understanding issue labels](#issue-labels) +* [Understanding issues, milestones, and project boards](#explaining-issues-milestones-and-project-boards) * [Making a change](#making-a-change) -* [Recognizing contributions](#recognizing-contributions) +* [Structuring contributions](#style-guide) +* [Recognizing contributors](#recognizing-contributions) ## Joining the conversation @@ -18,7 +22,36 @@ Already know what you're looking for in this guide? Jump to the following sectio Most of our discussions will take place on open [issues][link_issues]. We also maintain a [gitter chat room][link_gitter] for more informal conversations and general project updates. -There is significant cross-talk between these two spaces, and we look forward to hearing from you in either venue! As a reminder, we expect all contributions to `tedana` to adhere to our [code of conduct][link_coc]. +There is significant cross-talk between these two spaces, and we look forward to hearing from you in either venue! +As a reminder, we expect all contributions to `tedana` to adhere to our [code of conduct][link_coc]. + +## Explaining issues, milestones and project boards + +Every project on GitHub uses [issues][link_issues], [milestones][link_milestones], +and [project boards][link_project_boards] slightly differently. + +The following outlines how the ``tedana`` developers think about these different tools. + +* **Issues** are individual pieces of work that need to be completed to move the project forwards. +A general guideline: if you find yourself tempted to write a great big issue that +is difficult to describe as one unit of work, please consider splitting it into two or more issues. + + Issues are assigned [labels](#issue-labels) which explain how they relate to the overall project's + goals and immediate next steps. + +* **Milestones** are the link between the issues and the high level strategy for the ``tedana`` project. +Contributors new and old are encouraged to take a look at the milestones to see how we are progressing +towards ``tedana``'s shared vision. + + Issues are assigned to these milestones by the maintainers. + If you feel that an issue should be assigned to a specific milestone but the maintainers have not done so, just ask! + We might have just missed it, or we might not (yet) see how it aligns with the overall project structure. + These conversations are important to have, and we are excited to hear your perspective! + +* The **project board** is an automated [Kanban board][link_kanban] to keep track of what is currently underway +(in progress), what has been completed (done), and what remains to be done for a specific release. +The ``tedana`` maintainers use this board to keep an eye on how tasks are progressing week by week. + ### Issue labels @@ -35,7 +68,9 @@ The current list of labels are [here][link_labels] and include: * [![Enhancement](https://img.shields.io/badge/-enhancement-84b6eb.svg)][link_enhancement] *These issues are asking for enhancements to be added to the project.* - Please try to make sure that your enhancement is distinct from any others that have already been requested or implemented. If you find one that's similar but there are subtle differences please reference the other request in your issue. + Please try to make sure that your enhancement is distinct from any others that have already been requested or implemented. + If you find one that's similar but there are subtle differences please reference the other request in your issue. + ## Making a change @@ -57,13 +92,41 @@ Make sure to [keep your fork up to date][link_updateupstreamwiki] with the maste Try to keep the changes focused. We've found that working on a [new branch][link_branches] makes it easier to keep your changes targeted. -When you're creating your pull request, please make sure to review the tedana [style conventions][link_styleguide]. +When you're creating your pull request, please make sure to review the tedana [style conventions](#style-guide). **4. Submit a [pull request][link_pullrequest].** -A member of the development team will review your changes to confirm that they can be merged into the main codebase. +A member of the development team will review your changes to confirm that they can be merged into the main code base. +When opening the pull request, we ask that you follow some [specific conventions](#pull-requests). +We outline these below. + +### Pull Requests + +To improve understanding pull requests "at a glance", we encourage the use of several standardized tags. +When opening a pull request, please use at least one of the following prefixes: + +* **[ENH]** for enhancements +* **[FIX]** for bug fixes +* **[TST]** for new or updated tests +* **[DOC]** for new or updated documentation +* **[STY]** for stylistic changes +* **[RF]** for refactoring existing code -## Recognizing contributions +Pull requests should be submitted early and often! +If your pull request is not yet ready to be merged, please also include the **[WIP]** prefix. +This tells the development team that your pull request is a "work-in-progress", +and that you plan to continue working on it. + +## Style Guide + +Docstrings should follow [numpydoc][link_numpydoc] convention. +We encourage extensive documentation. + +The code itself should follow [PEP8][link_pep8] convention +whenever possible, with at most about 500 lines of code (not including docstrings) per script. + + +## Recognizing contributors We welcome and recognize all contributions from documentation to testing to code development. You can see a list of current contributors in the [contributors tab][link_contributors]. @@ -79,22 +142,27 @@ You're awesome. :wave::smiley: [link_github]: https://github.com/ [link_tedana]: https://github.com/ME-ICA/tedana [link_signupinstructions]: https://help.github.com/articles/signing-up-for-a-new-github-account -[link_react]: https://github.com/blog/2119-add-reactions-to-pull-requests-issues-and-comments + [link_issues]: https://github.com/ME-ICA/tedana/issues +[link_milestones]: https://github.com/ME-ICA/tedana/milestones/ +[link_project_boards]: https://github.com/ME-ICA/tedana/projects [link_gitter]: https://gitter.im/me-ica/tedana [link_coc]: https://github.com/ME-ICA/tedana/blob/master/Code_of_Conduct.md -[link_labels]: https://github.com/ME-ICA/tedana/labels -[link_discussingissues]: https://help.github.com/articles/discussing-projects-in-issues-and-pull-requests +[link_labels]: https://github.com/ME-ICA/tedana/labels [link_bugs]: https://github.com/ME-ICA/tedana/labels/bug [link_helpwanted]: https://github.com/ME-ICA/tedana/labels/help%20wanted [link_enhancement]: https://github.com/ME-ICA/tedana/labels/enhancement +[link_kanban]: https://en.wikipedia.org/wiki/Kanban_board [link_pullrequest]: https://help.github.com/articles/creating-a-pull-request/ [link_fork]: https://help.github.com/articles/fork-a-repo/ [link_pushpullblog]: https://www.igvita.com/2011/12/19/dont-push-your-pull-requests/ -[link_branches]: https://help.github.com/articles/creating-and-deleting-branches-within-your-repository/ -[link_styleguide]: http://tedana.readthedocs.io/en/latest/contributing.html [link_updateupstreamwiki]: https://help.github.com/articles/syncing-a-fork/ -[link_stemmrolemodels]: https://github.com/KirstieJane/STEMMRoleModels +[link_branches]: https://help.github.com/articles/creating-and-deleting-branches-within-your-repository/ + +[link_numpydoc]: https://numpydoc.readthedocs.io/en/latest/format.html +[link_pep8]: https://www.python.org/dev/peps/pep-0008/ + [link_contributors]: https://github.com/ME-ICA/tedana/graphs/contributors +[link_stemmrolemodels]: https://github.com/KirstieJane/STEMMRoleModels From ae294f536d2c5bbcdc11107eda504cccca3a63bb Mon Sep 17 00:00:00 2001 From: Elizabeth DuPre Date: Thu, 1 Nov 2018 14:41:04 -0400 Subject: [PATCH 04/27] [DOC] Update philosophy to reference support page --- docs/contributing.rst | 18 ++++-------------- 1 file changed, 4 insertions(+), 14 deletions(-) diff --git a/docs/contributing.rst b/docs/contributing.rst index 38d9f19bb..748b4921f 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -11,14 +11,9 @@ For a more practical guide to the tedana development, please see our Governance ---------- -<<<<<<< HEAD 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``. -======= -Style Guide -=========== ->>>>>>> upstream/master ```tedana`` is currently supported by a small group of five core developers. Even with only five members involved in decision making processes, @@ -87,11 +82,10 @@ We understand that it is possible to build the software to provide more options within the existing framework, but have chosen to focus on `the 80 percent use cases`_. You can provide feedback on this philosophy through any of the channels -listed on the ``tedana`` `get in touch`_ page. +listed on the ``tedana`` :doc:`support` page. .. _an LGPL2 license: https://github.com/ME-ICA/tedana/blob/master/LICENSE .. _the 80 percent use cases: https://en.wikipedia.org/wiki/Pareto_principle#In_software -.. _get in touch: https://github.com/ME-ICA/tedana/blob/master/CONTRIBUTING.md#joining-the-conversation .. _prioritizing project developments: @@ -101,14 +95,14 @@ 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 prioritise what work needs to be completed. +helps new contributors prioritize what work needs to be completed. We have outlined our goals for ``tedana`` in our :doc:`roadmap`, -which we encourage all new contributors to read and `give feedback`_ on. +which we encourage all contributors to read and give feedback on. +Feedback can be provided through any of the channels listed on our :doc:`support` page. In order to more directly map between our :doc:`roadmap` and ongoing `project issues`_, we have also created `milestones in the github repository`_. -.. _give feedback: https://github.com/ME-ICA/tedana/blob/master/CONTRIBUTING.md#joining-the-conversation .. _project issues: https://github.com/ME-ICA/tedana/issues .. _milestones in the github repository: https://github.com/me-ica/tedana/milestones @@ -170,11 +164,7 @@ More information about what is required for a release to proceed is available in .. _release checklist: Release Checklist -<<<<<<< HEAD """"""""""""""""" -======= -================= ->>>>>>> upstream/master 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 From 3e47616877cc228fbcf611800683fe8b97f8000f Mon Sep 17 00:00:00 2001 From: Elizabeth DuPre Date: Thu, 1 Nov 2018 14:44:25 -0400 Subject: [PATCH 05/27] [DOC] Update index.rst --- docs/index.rst | 12 ++++-------- 1 file changed, 4 insertions(+), 8 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index d313472dc..9a3ec949b 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -43,19 +43,15 @@ multi-echo functional magnetic resonance imaging (fMRI) data. About ----- +.. image:: https://user-images.githubusercontent.com/7406227/40031156-57b7cbb8-57bc-11e8-8c51-5b29f2e86a48.png + :target: http://tedana.readthedocs.io/ + ``tedana`` originally came about as a part of the `ME-ICA`_ pipeline. The ME-ICA pipeline originally performed both pre-processing and TE-dependent analysis of multi-echo fMRI data; however, ``tedana`` now assumes that you're working with data which has been previously preprocessed. -If you're in need of a preprocessing pipeline, we recommend -`fmriprep`_, which has been tested -for compatibility with multi-echo fMRI data and ``tedana``. - -.. image:: https://user-images.githubusercontent.com/7406227/40031156-57b7cbb8-57bc-11e8-8c51-5b29f2e86a48.png - :target: http://tedana.readthedocs.io/ .. _ME-ICA: https://github.com/me-ica/me-ica -.. _fmriprep: https://github.com/poldracklab/fmriprep/ Citations --------- @@ -134,9 +130,9 @@ tedana is licensed under GNU Lesser General Public License version 2.1. usage approach outputs - support contributing roadmap + support api Indices and tables From 7d5d7089f8822ea668d415c75bf6d98a21f7cf33 Mon Sep 17 00:00:00 2001 From: Elizabeth DuPre Date: Fri, 2 Nov 2018 17:15:26 -0400 Subject: [PATCH 06/27] Address Yarik's review comments --- CONTRIBUTING.md | 6 ++++-- docs/contributing.rst | 2 +- docs/roadmap.rst | 2 +- 3 files changed, 6 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f4dc34c87..d16b856ca 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -25,7 +25,7 @@ We also maintain a [gitter chat room][link_gitter] for more informal conversatio There is significant cross-talk between these two spaces, and we look forward to hearing from you in either venue! As a reminder, we expect all contributions to `tedana` to adhere to our [code of conduct][link_coc]. -## Explaining issues, milestones and project boards +## Understanding issues, milestones and project boards Every project on GitHub uses [issues][link_issues], [milestones][link_milestones], and [project boards][link_project_boards] slightly differently. @@ -110,7 +110,9 @@ When opening a pull request, please use at least one of the following prefixes: * **[TST]** for new or updated tests * **[DOC]** for new or updated documentation * **[STY]** for stylistic changes -* **[RF]** for refactoring existing code +* **[REF]** for refactoring existing code +* **[BRK]** for changes which break existing builds or tests +* **[WIP]** for changes which are not yet ready to be merged Pull requests should be submitted early and often! If your pull request is not yet ready to be merged, please also include the **[WIP]** prefix. diff --git a/docs/contributing.rst b/docs/contributing.rst index 748b4921f..629d4c10b 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -32,7 +32,7 @@ during any interaction with the project. That includes---but is not limited to---online conversations, in-person workshops or development sprints, and when giving talks about the software. -As is stated in the code, severe or repeated violations by community members may result in exclusion +As it is 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 diff --git a/docs/roadmap.rst b/docs/roadmap.rst index 5b503159e..2c8136157 100644 --- a/docs/roadmap.rst +++ b/docs/roadmap.rst @@ -98,7 +98,7 @@ the existing implementation. Moving forward, we want to grow an active development community, where developers feel empowered to explore new enhancements to the ``tedana`` code base. -One means to ensure that new code does not introduce silent failures is through extensive testing. +One means to ensure that new code does not introduce bugs is through extensive testing. We are therefore committed to implementing high test coverage at both the unit test and integration test levels; that is, both in testing individual functions and broader workflows, respectively. From ce6bf75a841adbc81dcea8559d6918083d05a964 Mon Sep 17 00:00:00 2001 From: Kirstie Whitaker Date: Sat, 3 Nov 2018 21:07:09 +0000 Subject: [PATCH 07/27] Add a sentence about multiple tags for PRs Also added an example of combining labels. --- docs/contributing.rst | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/docs/contributing.rst b/docs/contributing.rst index 3cfae82db..955ae0150 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -34,9 +34,14 @@ When opening a pull request, please use one of the following prefixes: + **[TST]** for new or updated tests + **[DOC]** for new or updated documentation + **[STY]** for stylistic changes - + **[RF]** for refactoring existing code + + **[REF]** for refactoring existing code + + **[WIP]** for works in progress Pull requests should be submitted early and often! If your pull request is not yet ready to be merged, please also include the **[WIP]** prefix. This tells the development team that your pull request is a "work-in-progress", and that you plan to continue working on it. + +You can also combine the tags above, for example if you are updating both a test and +the documentation: **[TST, DOC]**. If you're still working on the pull request that +prefix would be **[WIP, TST, DOC]**. \ No newline at end of file From 6fb02704f7262466d21c1f06d30dc989b9095d3d Mon Sep 17 00:00:00 2001 From: Kirstie Whitaker Date: Sat, 3 Nov 2018 21:11:15 +0000 Subject: [PATCH 08/27] Update gitignore to exclude vscode settings --- .gitignore | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.gitignore b/.gitignore index 1ea329bd2..3934ae3c8 100644 --- a/.gitignore +++ b/.gitignore @@ -101,3 +101,6 @@ ENV/ # mypy .mypy_cache/ + +# vscode +.vscode \ No newline at end of file From ebab1a841f5829d628dc6891081be9e2ef0bd16f Mon Sep 17 00:00:00 2001 From: Kirstie Whitaker Date: Sat, 3 Nov 2018 21:13:46 +0000 Subject: [PATCH 09/27] Add a couple more comments to the pull request template Totally fine to reject this change if you think its too verbose :) --- .github/pull_request_template.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 9423f5f5e..0aabface7 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -9,8 +9,12 @@ See here for more information and a list of available options: http://tedana.readthedocs.io/en/latest/contributing.html#pull-requests --> + Closes # . + Changes proposed in this pull request: - From 5697e68abc3da9acac5a6e59c1755d27a90ea7c4 Mon Sep 17 00:00:00 2001 From: Kirstie Whitaker Date: Sat, 3 Nov 2018 21:19:50 +0000 Subject: [PATCH 10/27] Add a sentence about multiple tags for PRs Also added an example of combining labels. --- CONTRIBUTING.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d16b856ca..fa60c73fc 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,6 @@ # Contributing to `tedana` -Welcome to the `tedana` repository! We're excited you're here and want to contribute. +Welcome to the `tedana` repository! We're excited you're here and want to contribute. These guidelines are designed to make it as easy as possible to get involved. If you have any questions that aren't discussed below, please let us know by opening an [issue][link_issues]! @@ -119,6 +119,10 @@ If your pull request is not yet ready to be merged, please also include the **[W This tells the development team that your pull request is a "work-in-progress", and that you plan to continue working on it. +You can also combine the tags above, for example if you are updating both a test and +the documentation: **[TST, DOC]**. If you're still working on the pull request that +prefix would be **[WIP, TST, DOC]**. + ## Style Guide Docstrings should follow [numpydoc][link_numpydoc] convention. From e6b529627539afb34e770a7a50968b857fa0f7b9 Mon Sep 17 00:00:00 2001 From: Kirstie Whitaker Date: Sat, 3 Nov 2018 21:30:30 +0000 Subject: [PATCH 11/27] Add links to milestones Also standardised how they're referred to between the different milesones :) --- docs/roadmap.rst | 29 +++++++++++++++++++++-------- 1 file changed, 21 insertions(+), 8 deletions(-) diff --git a/docs/roadmap.rst b/docs/roadmap.rst index 2c8136157..985fc84ea 100644 --- a/docs/roadmap.rst +++ b/docs/roadmap.rst @@ -51,11 +51,13 @@ One metric of success, then, is to develop documentation that includes: .. _a ReadTheDocs site: https://tedana.readthedocs.io -**Associated Milestone**: +**Associated Milestone**: `#6`_ This milestone will close when the online documentation contains the minimum necessary information to orient a complete newcomer to ME-EPI, both on the theoretical basis of the method as well as the practical steps used in ME-EPI denoising. +.. _#6: https://github.com/ME-ICA/tedana/milestone/6 + .. _Transparent and Reproducible Processing: Transparent and reproducible processing @@ -82,11 +84,13 @@ A metric of success for ``tedana`` then, should be enhancements to the code such 1. Non-deterministic steps are made reproducible by enabling access to a "seed value", and 2. The decision process for individual component data is made accessible to the end user. -**Associated Milestone**: +**Associated Milestone**: `#4`_ This milestone will close when when the internal decision making process for component selection is made accessible to the end user, and an analysis can be reproduced by an independent researcher who has access to the same data. +.. _#4: https://github.com/ME-ICA/tedana/milestone/4 + .. _Testing: Testing @@ -107,11 +111,13 @@ A metric of success should thus be: 1. Achieving 90% test coverage for unit tests, as well as 2. Three distinguishable integration tests over a range of possible acquisition conditions. -**Milestone**: +**Associated Milestone**: `#7`_ This milestone will close when we have 90% test coverage for unit tests and three distinguishable integration tests, varying number of echos and acquisition type (i.e., task vs. rest). +.. _#7: https://github.com/ME-ICA/tedana/milestone/7 + .. _Workflow Integrations: Workflow integration: AFNI @@ -134,11 +140,12 @@ and the ```afni_proc.py`` workflow, eliminating the need for an additional wrapp For example, ``tedana`` could directly accept BRIK/HEAD files, facilitating interoperability with other AFNI pipelines. -**Milestone**: - This milestone will close when ``tedana`` is stable enough such that the recommended default in +**Associated Milestone**: `#8`_ +This milestone will close when ``tedana`` is stable enough such that the recommended default in ``afni_proc.py`` is to access ME-EPI denoising via ``pip install tedana``, rather than maintaining the alternative version that is currently used. +.. _#8: https://github.com/ME-ICA/tedana/milestone/8 Workflow integration: BIDS `````````````````````````` @@ -157,10 +164,12 @@ A metric of success, then, will be .. _FMRIPrep: https://github.com/poldracklab/fmriprep .. _BIDS derivatives specification: https://docs.google.com/document/d/1Wwc4A6Mow4ZPPszDIWfCUCRNstn7d_zzaWPcfcHmgI4/edit -**Milestone**: +**Associated Milestone**: `#9`_ This milestone will close when the denoising steps of ``tedana`` are stable enough to integrate into ``FMRIPrep`` and the ```FMRIPrep`` project is updated to process ME-EPI scans. +.. _#9: https://github.com/ME-ICA/tedana/milestone/9 + .. _Extensions and Improvements to ME-EPI processing: Method extensions & improvements @@ -174,10 +183,12 @@ A metric of success here would be * *EITHER* integrating a new decomposition method, beyond ICA * *OR* validating new selection criteria. -**Milestone**: +**Associated Milestone**: `#10`_ This milestone will close when the codebase is stable enough to integrate novel methods into ``tedana``, and that happens! +.. _#10: https://github.com/ME-ICA/tedana/milestone/10 + .. _Developing a healthy community: Developing a healthy community @@ -192,6 +203,8 @@ we will enable new contributors to feel that their work is welcomed. We therefore have one additional metric of success: 1. An outside contributor integrates an improvement to ME-EPI denoising. -**Milestone**: +**Associated Milestone**: `#5`_ This milestone will probably never close, but will serve to track issues related to building and supporting the ``tedana`` community. + +.. _#5: https://github.com/ME-ICA/tedana/milestone/5 From 32cbb260a94084a2e8f45c2a22b8d244fd0e4948 Mon Sep 17 00:00:00 2001 From: Kirstie Whitaker Date: Sat, 3 Nov 2018 21:46:07 +0000 Subject: [PATCH 12/27] Add opinion about not being backwards compatible --- docs/contributing.rst | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/docs/contributing.rst b/docs/contributing.rst index 52cbf4e6c..6b8a978c5 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -132,6 +132,29 @@ mean that this work should be relatively manageable. We hope that the lessons we learn building something useful in the short term will be applicable in the future as other needs arise. +.. _backwards compatibility with meica: + +Is ``tedana`` backwards compatible with MEICA? +`````````````````````````````````````````````` + +The short answer is no. + +There are two main reasons why. One is that the tool originally used to run the independent +component analysis core to the MEICA method (`mdp`_) is no longer supported. In November 2018 +the developers made the decision to switch to `scikit learn`_ to perform these analyses. Scikit +learn is well supported and under long term development. ``tedana`` will be more stable and +have better performance going forwards as a result of this switch, but it also means that +exactly reproducing MEICA analyses is not possible. + +The other reason is a choice of the core developers to look forwards rather than maintaining +an older codebase. As is described `above`_, ``tedana`` is developed by a small team of +volunteers and they have to allocate their time accordingly. If you'd like to use MEICA as has +been previously published the code is available on `github`_ and freely available under a LGPL2 +license. + +.. _mdp: http://mdp-toolkit.sourceforge.net +.. _scikit learn: http://scikit-learn.org/stable +.. _github: https://github.com/ME-ICA/me-ica .. _when to release new software versions: From d0c1bc54c7daefa1e3fb18730c7c19b8fc151822 Mon Sep 17 00:00:00 2001 From: Kirstie Whitaker Date: Mon, 5 Nov 2018 22:35:29 +0000 Subject: [PATCH 13/27] Update link to pull request documentation --- .github/pull_request_template.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 0aabface7..31c476e0a 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -6,7 +6,7 @@ If there is other information that would be helpful to include, please don't hes Please also label your pull request with the relevant tags. See here for more information and a list of available options: -http://tedana.readthedocs.io/en/latest/contributing.html#pull-requests +https://github.com/ME-ICA/tedana/blob/master/CONTRIBUTING.md#pull-requests --> From f58c230a1632af6d6a104ee74a1f9a5cb157ae38 Mon Sep 17 00:00:00 2001 From: Kirstie Whitaker Date: Mon, 5 Nov 2018 22:49:17 +0000 Subject: [PATCH 14/27] Move sections around and add to TOC Also fix a couple of typos & make sure all new sentences start on new lines --- docs/contributing.rst | 55 +++++++++++++++++++++++-------------------- 1 file changed, 30 insertions(+), 25 deletions(-) diff --git a/docs/contributing.rst b/docs/contributing.rst index 6b8a978c5..36413a2eb 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -40,14 +40,15 @@ from collective decision-making and rejection of future contributions to the ``t ```tedana``'s development philosophy -------------------------------------- -In contributing to any open source proect, -we have found that it is hugely valuable to understand the core maintainers'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. In order to aid other contributors in onboarding to ``tedana`` development, we have therefore laid out our shared opinion on several major decision points. These are: #. :ref:`exposing options to the user`, #. :ref:`prioritizing project developments`, +#. :ref:`backwards compatibility with meica`, #. :ref:`future-proofing for continuous development`, and #. :ref:`when to release new software versions` @@ -112,6 +113,33 @@ This allows us to 2. Helps us to measure progress towards each aim's concrete deliverable(s). +.. _backwards compatibility with meica: + +Is ``tedana`` backwards compatible with MEICA? +`````````````````````````````````````````````` + +The short answer is no. + +There are two main reasons why. One is that the tool originally used to run the independent +component analysis core to the MEICA method (`mdp`_) is no longer supported. +In November 2018 the developers made the decision to switch to `scikit learn`_ to perform +these analyses. +Scikit learn is well supported and under long term development. +``tedana`` will be more stable and have better performance going forwards as a result of +this switch, but it also means that exactly reproducing MEICA analyses is not possible. + +The other reason is a choice of the core developers to look forwards rather than maintaining +an older codebase. +As described in the :ref:`governance` section, ``tedana`` is developed by a small team of +volunteers and they have to allocate their time accordingly. +If you'd like to use MEICA as has been previously published the code is available on + `github`_ and freely available under a LGPL2 license. + +.. _mdp: http://mdp-toolkit.sourceforge.net +.. _scikit learn: http://scikit-learn.org/stable +.. _github: https://github.com/ME-ICA/me-ica + + .. _future-proofing for continuous development: How does ``tedana`` future-proof its development? @@ -132,29 +160,6 @@ mean that this work should be relatively manageable. We hope that the lessons we learn building something useful in the short term will be applicable in the future as other needs arise. -.. _backwards compatibility with meica: - -Is ``tedana`` backwards compatible with MEICA? -`````````````````````````````````````````````` - -The short answer is no. - -There are two main reasons why. One is that the tool originally used to run the independent -component analysis core to the MEICA method (`mdp`_) is no longer supported. In November 2018 -the developers made the decision to switch to `scikit learn`_ to perform these analyses. Scikit -learn is well supported and under long term development. ``tedana`` will be more stable and -have better performance going forwards as a result of this switch, but it also means that -exactly reproducing MEICA analyses is not possible. - -The other reason is a choice of the core developers to look forwards rather than maintaining -an older codebase. As is described `above`_, ``tedana`` is developed by a small team of -volunteers and they have to allocate their time accordingly. If you'd like to use MEICA as has -been previously published the code is available on `github`_ and freely available under a LGPL2 -license. - -.. _mdp: http://mdp-toolkit.sourceforge.net -.. _scikit learn: http://scikit-learn.org/stable -.. _github: https://github.com/ME-ICA/me-ica .. _when to release new software versions: From 4e10b47cef9e552a9fc7d8759027c7275b2991fa Mon Sep 17 00:00:00 2001 From: Kirstie Whitaker Date: Mon, 5 Nov 2018 22:49:33 +0000 Subject: [PATCH 15/27] Add link to closing issues docs --- .github/pull_request_template.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 31c476e0a..6877bd0db 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -9,7 +9,10 @@ See here for more information and a list of available options: https://github.com/ME-ICA/tedana/blob/master/CONTRIBUTING.md#pull-requests --> - + Closes # .