diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index ff8d811fb..47d534205 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,4 +1,4 @@ * [ ] fix #(issue number) * [ ] description of feature/fix * [ ] tests added/passed -* [ ] add an entry to the [latest changes](../docs/changes/latest.inc) +* [ ] add an entry for the latest changes diff --git a/.github/workflows/docs-preview.yml b/.github/workflows/docs-preview.yml index 8c98b4c35..5a1abce56 100644 --- a/.github/workflows/docs-preview.yml +++ b/.github/workflows/docs-preview.yml @@ -22,6 +22,7 @@ jobs: - name: Checkout source uses: actions/checkout@v3 with: + fetch-depth: 0 submodules: true - name: Set up Python 3.10 uses: actions/setup-python@v4 diff --git a/docs/Makefile b/docs/Makefile index a58f174d8..8b7100909 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -12,16 +12,34 @@ BUILDDIR ?= _build help: @$(SPHINXBUILD) --help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) -.PHONY: help Makefile +.PHONY: help Makefile clean local news _build_local _html clean: rm -rf $(BUILDDIR)/* rm -rf auto_examples/ # For local build -local: +local: news + make _build_local; STATUS=$$?; make news_cleanup; exit $$STATUS + +news: + @echo "Generating whats_new.rst" + cd ../ && towncrier build --keep + +news_cleanup: + @echo "Cleaning up whats_new.rst" + git restore --staged whats_new.rst + git restore whats_new.rst + +_build_local: sphinx-build "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) +html: news + make _html; STATUS=$$?; make news_cleanup; exit $$STATUS + +_html: + $(SPHINXBUILD) "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) + # Catch-all target: route all unknown targets to Sphinx using the new # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). %: Makefile diff --git a/docs/_static/css/custom.css b/docs/_static/css/custom.css index 518a7e367..be6522b82 100644 --- a/docs/_static/css/custom.css +++ b/docs/_static/css/custom.css @@ -14,4 +14,10 @@ #versions { display: none; overflow: hidden; +} + +/* Reduce font size of "What's New" section */ +#what-s-new li, +#what-s-new a { + font-size: medium; } \ No newline at end of file diff --git a/docs/changes/0.0.1.inc b/docs/changes/0.0.1.inc deleted file mode 100644 index 7c0e294cf..000000000 --- a/docs/changes/0.0.1.inc +++ /dev/null @@ -1,115 +0,0 @@ -v0.0.1 ------- - -Enhancements -~~~~~~~~~~~~ - -- Create the repository based on the mockup by `Fede Raimondo`_. - -- Implement :class:`junifer.testing.datagrabbers.SPMAuditoryTestingDatagrabber` datagrabber - (:gh:`52` by `Fede Raimondo`_). - -- Add comments to :class:`junifer.datagrabber.DataladDataGrabber` datagrabber and change to - use ``datalad-clone`` instead of ``datalad-install`` (:gh:`55` by `Benjamin Poldrack`_). - -- Add an example how to use junifer and julearn in one pipeline to extract features - and do machine learning (:gh:`40` by `Leonard Sasse`_, `Nicolas Nieto`_, and `Sami Hamdan`_). - -- Implement matrix storage in SQliteFeatureStorage (:gh:`42` by `Fede Raimondo`_). - -- Implement :class:`junifer.markers.FunctionalConnectivityParcels` marker for functional - connectivity using a parcellation (:gh:`41` by `Amir Omidvarnia`_ and `Kaustubh R. Patil`_). - -- Add documentation for the datagrabbers (by `Leonard Sasse`_, - `Nicolas Nieto`_, and `Sami Hamdan`_). - -- Implement coordinate register, list and load (:gh:`11` by `Fede Raimondo`_). - -- Add :class:`junifer.datagrabber.DataladAOMICID1000` datagrabber for AOMIC ID1000 dataset - including tests and creation of mock dataset for testing (:gh:`60` by `Vera Komeyer`_, `Xuan Li`_). - -- Add support to access other input in the data object in the ``compute`` method - (by `Fede Raimondo`_). - -- Implement :class:`junifer.markers.RSSETSMarker` marker (:gh:`51` by `Leonard Sasse`_, - `Nicolas Nieto`_, `Sami Hamdan`_). - -- Implement :class:`junifer.markers.SphereAggregation` marker (by `Fede Raimondo`_). - -- Implement :class:`junifer.datagrabber.DataladAOMICPIOP1` and - :class:`junifer.datagrabber.DataladAOMICPIOP2` datagrabbers for AOMIC PIOP1 and PIOP2 datasets - respectively and refactor :class:`junifer.datagrabber.DataladAOMICID1000` slightly - (:gh:`94` by `Leonard Sasse`_) - -- Implement :class:`junifer.configs.juseless.datagrabbers.JuselessDataladCamCANVBM` datagrabber - (:gh:`99` by `Leonard Sasse`_) - -- Implement :class:`junifer.configs.juseless.datagrabbers.JuselessDataladIXIVBM` CAT output - datagrabber for juseless (:gh:`48` by `Leonard Sasse`_). - -- Upgrade storage interface for storage-like objects (:gh:`84` by `Synchon Mandal`_). - -- Add missing type annotations (:gh:`74` by `Synchon Mandal`_). - -- Add ``junifer wtf`` to report environment details (:gh:`33` by `Synchon Mandal`_). - -- Add ``junifer selftest`` to report environment details (:gh:`9` by `Synchon Mandal`_). - -- Refactor markers ``on`` attribute and ``get_valid_inputs`` to verify that the marker can - be computed on the input data types (by `Fede Raimondo`_) - -- Implement :class:`junifer.configs.juseless.datagrabbers.JuselessDataladAOMICID1000VBM` - datagrabber for accessing AOMIC ID1000 VBM from juseless (:gh:`57` by `Felix Hoffstaedter`_ - and `Synchon Mandal`_) - -- Add test for :class:`junifer.datagrabber.DataladHCP1200` datagrabber (:gh:`93` by `Synchon Mandal`_). - -- Change documentation template to furo. Fix references and standardize documentation (:gh:`114` by `Fede Raimondo`_). - -- Add :class:`junifer.preprocess.fMRIPrepConfoundRemover` (:gh:`111` by `Fede Raimondo`_ and `Leonard Sasse`_). - -- Implement :class:`junifer.markers.CrossParcellationFC` marker (:gh:`85` by `Leonard Sasse`_ - and `Kaustubh R. Patil`_) - -- Add :class:`junifer.configs.juseless.datagrabbers.JuselessUCLA` datagrabber for the UCLA dataset - available on juseless (:gh:`118` by `Leonard Sasse`_). - -- Rename "atlas" to "parcellation" (:gh:`116` by `Fede Raimondo`_). - -- Refactor the :class:`junifer.datagrabber.BaseDataGrabber` class to allow for easier subclassing (:gh:`123` by `Fede Raimondo`_). - -- Allow custom aggregation method for :class:`junifer.markers.SphereAggregation` (:gh:`102` by `Synchon Mandal`_). - -- Add support for "masks" (:gh:`79` by `Fede Raimondo`_). - -- Allow :class:`junifer.markers.ParcelAggregation` to apply multiple parcellations at once (:gh:`131` by `Fede Raimondo`_). - -- Introduce a singleton decorator for marker computations (:gh:`151` by `Synchon Mandal`_). - -- Refactor :class:`junifer.pipeline.PipelineStepMixin` to improve its implementation and validation for pipeline steps - (:gh:`152` by `Synchon Mandal`_). - -- Implement :class:`junifer.markers.ReHoParcels` and :class:`junifer.markers.ReHoSpheres` markers (:gh:`36` by `Synchon Mandal`_). - -- Implement :class:`junifer.markers.AmplitudeLowFrequencyFluctuationParcels` and - :class:`junifer.markers.AmplitudeLowFrequencyFluctuationSpheres` markers (:gh:`35` by `Fede Raimondo`_). - -Bugs -~~~~ - -- Fix a bug in which a :class:`junifer.datagrabber.PatternDataGrabber` would now work with relative ``datadir`` paths. - (:gh:`96` by `Leonard Sasse`_, fixed in :gh:`98` by `Fede Raimondo`_). - -- Fix a bug in which :class:`junifer.datagrabber.DataladAOMICPIOP2` datagrabber did not use user input to - constrain elements based on tasks (:gh:`105` by `Leonard Sasse`_) - -- Fix a bug in which a datalad dataset could remove a user-cloned dataset (:gh:`53` by `Fede Raimondo`_) - -- Fix a bug in which CLI command would not work using elements with more than one field (by `Fede Raimondo`_). - -- Fix a bug in which the generated DAG for HTCondor will not work (:gh:`143` by `Fede Raimondo`_). - -API changes -~~~~~~~~~~~ - -- Change the ``single_output`` default parameter in storage classes from ``False`` to ``True`` (:gh:`134` by `Fede Raimondo`_). diff --git a/docs/changes/latest.inc b/docs/changes/latest.inc deleted file mode 100644 index 9eef40a05..000000000 --- a/docs/changes/latest.inc +++ /dev/null @@ -1,106 +0,0 @@ -.. NOTE: we are now using links to highlight new functions and classes. - Please follow the examples below like - :func:`julearn.api.run_cross_validation`, so the - whats_new page will have a link to the function/class documentation. - -.. NOTE: there are 3 separate sections for changes, based on type: - - "Enhancements" for new features - - "Bugs" for bug fixes - - "API changes" for backward-incompatible changes - -.. NOTE: add the contributors and reference to the github issue/PR at the end - Example: - - Implemented feature X (:gh:`151` by `Sami Hamdan`_). - -.. _current: - -Current (0.0.2.dev) -------------------- - -Enhancements -~~~~~~~~~~~~ - -- Allow :class:`junifer.testing.datagrabbers.PartlyCloudyTestingDataGrabber` to be accessible - via ``import junifer.testing.registry`` (:gh:`160` by `Synchon Mandal`_). - -- Update docstrings and fix typo in log message (:gh:`165` by `Synchon Mandal`_). - -- Add support for ``Power`` coordinates (:gh:`167` by `Synchon Mandal`_). - -- Add support for ``Dosenbach`` coordinates (:gh:`168` by `Synchon Mandal`_). - -- Organize functional connectivity markers in ``junifer.markers.functional_connectivity`` - (:gh:`107` by `Synchon Mandal`_). - -- Add :class:`junifer.markers.EdgeCentricFCParcels` and :class:`junifer.markers.EdgeCentricFCSpheres` - (:gh:`64` by `Leonard Sasse`_). - -- Change HCP datagrabber tests to decrease CI running time (:gh:`155` by `Fede Raimondo`_). - -- Add support for nilearn computed masks (``compute_epi_mask``, ``compute_brain_mask``, ``compute_background_mask``, - ``fetch_icbm152_brain_gm_mask``) (:gh:`175` by `Fede Raimondo`_). - -- Add fMRIPrep brain masks to the datagrabber patterns for all datagrabbers in the aomic sub-package - (:gh:`177` by `Leonard Sasse`_). - -- Add :class:`junifer.markers.TemporalSNRParcels` and :class:`junifer.markers.TemporalSNRSpheres` - (:gh:`163` by `Leonard Sasse`_). - -- Add support for HDF5 feature storage via :class:`junifer.storage.HDF5FeatureStorage` - (:gh:`147` by `Synchon Mandal`_). - -- Add ``pre_run`` parameter to ``_queue_condor`` (:gh:`188` by `Fede Raimondo`_). - -- Allow for empty spheres in :class:`junifer.external.nilearn.JuniferNiftiSpheresMasker`, that will result in NaNs (:gh:`190` by `Fede Raimondo`_). - -- Expose ``allow_overlap`` parameter in :class:`junifer.markers.SphereAggregation` and related markers (:gh:`190` by `Fede Raimondo`_). - -- Add aggregation function :func:`junifer.stats.count` that returns the number of elements in a given axis. This allows to count the number of voxels per sphere/parcel when used as ``method`` in markers (:gh:`190` by `Fede Raimondo`_). - -- Modify the behaviour of the ``collect`` parameter in HTCondor ``queue`` function to run a collect job even if some of the previous jobs fail. This is useful to collect the results of a pipeline even if some of the jobs fail (:gh:`190` by `Fede Raimondo`_). - -- Allow for empty parcels in :class:`junifer.markers.ParcelAggregation`, that will result in NaNs (:gh:`194` by `Fede Raimondo`_). - -- Improve metadata and data I/O for :class:`junifer.storage.HDF5FeatureStorage` (:gh:`196` by `Synchon Mandal`_). - -- Force datalad to be non-interactive on _queued_ jobs (:gh:`201` by `Fede Raimondo`_). - -- Add more documentation on registering parcellations, coordinates, and masks (:gh:`166` by `Leonard Sasse`_) - -- Expose a :func:`junifer.data.parcellations.merge_parcellations` function to merge a list of parcellations (:gh:`146` by `Leonard Sasse`_). - -- Add copy button to documentation code blocks (:gh:`205` by `Synchon Mandal`_). - -- Add func:`junifer.stats.select` as an aggregation function that allows to select a subset of elements (:gh:`204` by `Fede Raimondo`_). - -- Add ``time_method`` and ``time_method_params`` to :class:`junifer.markers.ParcelAggregation` and :class:`junifer.markers.SphereAggregation`, allowing to apply an aggregation on the time axis after the aggregation on the parcels and spheres respectively (:gh:`204` by `Fede Raimondo`_). - -Bugs -~~~~ - -- Fix ``junifer run`` to respect preprocess step specified in the pipeline (:gh:`159` by `Synchon Mandal`_). - -- Fix :class:`junifer.markers.AmplitudeLowFrequencyFluctuationParcels`, :class:`junifer.markers.AmplitudeLowFrequencyFluctuationSpheres` - :class:`junifer.markers.ReHoSpheres` and :class:`junifer.markers.ReHoParcels` pass the ``extra_input`` parameter (:gh:`187` by `Fede Raimondo`_). - -- Fix several markers that did not properly handle the ``extra_input`` parameter (:gh:`189` by `Fede Raimondo`_). - -- Fix an issue with datalad cache and locks in which the user-specific configuration might create a conflict in high throughput systems (:gh:`192` by `Fede Raimondo`_). - -- Fix a bug in which :func:`junifer.stats.count` will not be correctly applied across an axis (:gh:`195` by `Fede Raimondo`_). - -- Fix an issue with datalad cache and locks in which the overriden settings in Junifer were not propagated to subprocesses, resulting in using the default settings (:gh:`199` by `Fede Raimondo`_). - -- Fix a bug in which :class:`junifer.markers.ParcelAggregation` could yield duplicated column names if two or more parcels were used and label names were not unique (:gh:`194` by `Fede Raimondo`_). - -- Fix a bug in which :func:`junifer.data.masks.get_mask` fails for FunctionalConnectivityBase class, because of missing extra_input parameter (:gh:`200` by `Leonard Sasse`_) - -API changes -~~~~~~~~~~~ - -- Add ``confounds_format`` parameter to :class:`junifer.datagrabber.PatternDataGrabber` constructor for - improved handling of confounds specified via ``BOLD_confounds`` data type (:gh:`158` by `Synchon Mandal`_). - -- Rename ``store_table()`` to ``store_vector()`` for storage-like objects and adapt marker-like objects to - use ``"vector"`` in place of ``"table"`` for storage. Also, improve the logic of storing vectors - (:gh:`181` by `Synchon Mandal`_). \ No newline at end of file diff --git a/docs/changes/newsfragments/.gitignore b/docs/changes/newsfragments/.gitignore new file mode 100644 index 000000000..b722e9e13 --- /dev/null +++ b/docs/changes/newsfragments/.gitignore @@ -0,0 +1 @@ +!.gitignore \ No newline at end of file diff --git a/docs/changes/newsfragments/107.enh b/docs/changes/newsfragments/107.enh new file mode 100644 index 000000000..363c6885b --- /dev/null +++ b/docs/changes/newsfragments/107.enh @@ -0,0 +1 @@ +Organize functional connectivity markers in ``junifer.markers.functional_connectivity`` by `Synchon Mandal`_ \ No newline at end of file diff --git a/docs/changes/newsfragments/146.feature b/docs/changes/newsfragments/146.feature new file mode 100644 index 000000000..a81598ded --- /dev/null +++ b/docs/changes/newsfragments/146.feature @@ -0,0 +1 @@ +Expose a :func:`junifer.data.parcellations.merge_parcellations` function to merge a list of parcellations by `Leonard Sasse`_ \ No newline at end of file diff --git a/docs/changes/newsfragments/147.feature b/docs/changes/newsfragments/147.feature new file mode 100644 index 000000000..6165f99c1 --- /dev/null +++ b/docs/changes/newsfragments/147.feature @@ -0,0 +1 @@ +Add support for HDF5 feature storage via :class:`junifer.storage.HDF5FeatureStorage` by `Synchon Mandal`_ \ No newline at end of file diff --git a/docs/changes/newsfragments/155.enh b/docs/changes/newsfragments/155.enh new file mode 100644 index 000000000..99572b39d --- /dev/null +++ b/docs/changes/newsfragments/155.enh @@ -0,0 +1 @@ +Change HCP datagrabber tests to decrease CI running time by `Fede Raimondo`_ \ No newline at end of file diff --git a/docs/changes/newsfragments/158.change b/docs/changes/newsfragments/158.change new file mode 100644 index 000000000..bb85b938a --- /dev/null +++ b/docs/changes/newsfragments/158.change @@ -0,0 +1 @@ +Add ``confounds_format`` parameter to :class:`junifer.datagrabber.PatternDataGrabber` constructor for improved handling of confounds specified via ``BOLD_confounds`` data type by `Synchon Mandal`_ \ No newline at end of file diff --git a/docs/changes/newsfragments/159.bugfix b/docs/changes/newsfragments/159.bugfix new file mode 100644 index 000000000..49a22937d --- /dev/null +++ b/docs/changes/newsfragments/159.bugfix @@ -0,0 +1 @@ +Fix ``junifer run`` to respect preprocess step specified in the pipeline by `Synchon Mandal`_ \ No newline at end of file diff --git a/docs/changes/newsfragments/160.enh b/docs/changes/newsfragments/160.enh new file mode 100644 index 000000000..0cb1334b9 --- /dev/null +++ b/docs/changes/newsfragments/160.enh @@ -0,0 +1 @@ +Allow :class:`junifer.testing.datagrabbers.PartlyCloudyTestingDataGrabber` to be accessible via ``import junifer.testing.registry`` by `Synchon Mandal`_ \ No newline at end of file diff --git a/docs/changes/newsfragments/163.feature b/docs/changes/newsfragments/163.feature new file mode 100644 index 000000000..7713815d5 --- /dev/null +++ b/docs/changes/newsfragments/163.feature @@ -0,0 +1 @@ +Add :class:`junifer.markers.TemporalSNRParcels` and :class:`junifer.markers.TemporalSNRSpheres` by `Leonard Sasse`_ \ No newline at end of file diff --git a/docs/changes/newsfragments/165.enh b/docs/changes/newsfragments/165.enh new file mode 100644 index 000000000..65b572913 --- /dev/null +++ b/docs/changes/newsfragments/165.enh @@ -0,0 +1 @@ +Update docstrings and fix typo in log message by `Synchon Mandal`_ \ No newline at end of file diff --git a/docs/changes/newsfragments/166.doc b/docs/changes/newsfragments/166.doc new file mode 100644 index 000000000..0b90ed28e --- /dev/null +++ b/docs/changes/newsfragments/166.doc @@ -0,0 +1 @@ +Add more documentation on registering parcellations, coordinates, and masks by `Leonard Sasse`_ \ No newline at end of file diff --git a/docs/changes/newsfragments/167.feature b/docs/changes/newsfragments/167.feature new file mode 100644 index 000000000..c4cd95c1b --- /dev/null +++ b/docs/changes/newsfragments/167.feature @@ -0,0 +1 @@ +Add support for ``Power`` coordinates by `Synchon Mandal`_ \ No newline at end of file diff --git a/docs/changes/newsfragments/168.feature b/docs/changes/newsfragments/168.feature new file mode 100644 index 000000000..45f259326 --- /dev/null +++ b/docs/changes/newsfragments/168.feature @@ -0,0 +1 @@ +Add support for ``Dosenbach`` coordinates by `Synchon Mandal`_ \ No newline at end of file diff --git a/docs/changes/newsfragments/175.feature b/docs/changes/newsfragments/175.feature new file mode 100644 index 000000000..5043614a3 --- /dev/null +++ b/docs/changes/newsfragments/175.feature @@ -0,0 +1 @@ +Add support for nilearn computed masks (``compute_epi_mask``, ``compute_brain_mask``, ``compute_background_mask``, ``fetch_icbm152_brain_gm_mask``) by `Fede Raimondo`_ \ No newline at end of file diff --git a/docs/changes/newsfragments/177.enh b/docs/changes/newsfragments/177.enh new file mode 100644 index 000000000..3e491832c --- /dev/null +++ b/docs/changes/newsfragments/177.enh @@ -0,0 +1 @@ +Add fMRIPrep brain masks to the datagrabber patterns for all datagrabbers in the aomic sub-package by `Leonard Sasse`_ \ No newline at end of file diff --git a/docs/changes/newsfragments/181.change b/docs/changes/newsfragments/181.change new file mode 100644 index 000000000..2af2412ad --- /dev/null +++ b/docs/changes/newsfragments/181.change @@ -0,0 +1 @@ +Rename ``store_table()`` to ``store_vector()`` for storage-like objects and adapt marker-like objects to use ``"vector"`` in place of ``"table"`` for storage. Also, improve the logic of storing vectors by `Synchon Mandal`_ \ No newline at end of file diff --git a/docs/changes/newsfragments/187.bugfix b/docs/changes/newsfragments/187.bugfix new file mode 100644 index 000000000..3ddfdd4c7 --- /dev/null +++ b/docs/changes/newsfragments/187.bugfix @@ -0,0 +1 @@ +Fix :class:`junifer.markers.AmplitudeLowFrequencyFluctuationParcels`, :class:`junifer.markers.AmplitudeLowFrequencyFluctuationSpheres`, :class:`junifer.markers.ReHoSpheres` and :class:`junifer.markers.ReHoParcels` pass the ``extra_input`` parameter by `Fede Raimondo`_ \ No newline at end of file diff --git a/docs/changes/newsfragments/188.change b/docs/changes/newsfragments/188.change new file mode 100644 index 000000000..fff273933 --- /dev/null +++ b/docs/changes/newsfragments/188.change @@ -0,0 +1 @@ +Add ``pre_run`` parameter to ``_queue_condor`` by `Fede Raimondo`_ \ No newline at end of file diff --git a/docs/changes/newsfragments/189.bugfix b/docs/changes/newsfragments/189.bugfix new file mode 100644 index 000000000..bd5836a8d --- /dev/null +++ b/docs/changes/newsfragments/189.bugfix @@ -0,0 +1 @@ +Fix several markers that did not properly handle the ``extra_input`` parameter by `Fede Raimondo`_ \ No newline at end of file diff --git a/docs/changes/newsfragments/190.change b/docs/changes/newsfragments/190.change new file mode 100644 index 000000000..fd3333b23 --- /dev/null +++ b/docs/changes/newsfragments/190.change @@ -0,0 +1 @@ +Expose ``allow_overlap`` parameter in :class:`junifer.markers.SphereAggregation` and related markers by `Fede Raimondo`_ \ No newline at end of file diff --git a/docs/changes/newsfragments/190.enh b/docs/changes/newsfragments/190.enh new file mode 100644 index 000000000..0453d948a --- /dev/null +++ b/docs/changes/newsfragments/190.enh @@ -0,0 +1 @@ +Allow for empty spheres in :class:`junifer.external.nilearn.JuniferNiftiSpheresMasker`, that will result in NaNs. Also, modify the behaviour of the ``collect`` parameter in HTCondor ``queue`` function to run a collect job even if some of the previous jobs fail. This is useful to collect the results of a pipeline even if some of the jobs fail by `Fede Raimondo`_ \ No newline at end of file diff --git a/docs/changes/newsfragments/190.feature b/docs/changes/newsfragments/190.feature new file mode 100644 index 000000000..18386799f --- /dev/null +++ b/docs/changes/newsfragments/190.feature @@ -0,0 +1 @@ +Add aggregation function :func:`junifer.stats.count` that returns the number of elements in a given axis. This allows to count the number of voxels per sphere/parcel when used as ``method`` in markers by `Fede Raimondo`_ \ No newline at end of file diff --git a/docs/changes/newsfragments/192.bugfix b/docs/changes/newsfragments/192.bugfix new file mode 100644 index 000000000..743daf708 --- /dev/null +++ b/docs/changes/newsfragments/192.bugfix @@ -0,0 +1 @@ +Fix an issue with datalad cache and locks in which the user-specific configuration might create a conflict in high throughput systems by `Fede Raimondo`_ \ No newline at end of file diff --git a/docs/changes/newsfragments/194.bugfix b/docs/changes/newsfragments/194.bugfix new file mode 100644 index 000000000..561bb0686 --- /dev/null +++ b/docs/changes/newsfragments/194.bugfix @@ -0,0 +1 @@ +Fix a bug in which :class:`junifer.markers.ParcelAggregation` could yield duplicated column names if two or more parcels were used and label names were not unique by `Fede Raimondo`_ \ No newline at end of file diff --git a/docs/changes/newsfragments/194.enh b/docs/changes/newsfragments/194.enh new file mode 100644 index 000000000..f4d4123b9 --- /dev/null +++ b/docs/changes/newsfragments/194.enh @@ -0,0 +1 @@ +Allow for empty parcels in :class:`junifer.markers.ParcelAggregation`, that will result in NaNs by `Fede Raimondo`_ \ No newline at end of file diff --git a/docs/changes/newsfragments/195.bugfix b/docs/changes/newsfragments/195.bugfix new file mode 100644 index 000000000..f5bb6d7d6 --- /dev/null +++ b/docs/changes/newsfragments/195.bugfix @@ -0,0 +1 @@ +Fix a bug in which :func:`junifer.stats.count` will not be correctly applied across an axis by `Fede Raimondo`_ \ No newline at end of file diff --git a/docs/changes/newsfragments/196.enh b/docs/changes/newsfragments/196.enh new file mode 100644 index 000000000..02b0a3c8d --- /dev/null +++ b/docs/changes/newsfragments/196.enh @@ -0,0 +1 @@ +Improve metadata and data I/O for :class:`junifer.storage.HDF5FeatureStorage` by `Synchon Mandal`_ \ No newline at end of file diff --git a/docs/changes/newsfragments/199.bugfix b/docs/changes/newsfragments/199.bugfix new file mode 100644 index 000000000..c3b207315 --- /dev/null +++ b/docs/changes/newsfragments/199.bugfix @@ -0,0 +1 @@ +Fix an issue with datalad cache and locks in which the overriden settings in Junifer were not propagated to subprocesses, resulting in using the default settings by `Fede Raimondo`_ \ No newline at end of file diff --git a/docs/changes/newsfragments/200.bugfix b/docs/changes/newsfragments/200.bugfix new file mode 100644 index 000000000..f16beff4c --- /dev/null +++ b/docs/changes/newsfragments/200.bugfix @@ -0,0 +1 @@ +Fix a bug in which :func:`junifer.data.masks.get_mask` fails for FunctionalConnectivityBase class, because of missing extra_input parameter by `Leonard Sasse`_ \ No newline at end of file diff --git a/docs/changes/newsfragments/201.enh b/docs/changes/newsfragments/201.enh new file mode 100644 index 000000000..a650a15df --- /dev/null +++ b/docs/changes/newsfragments/201.enh @@ -0,0 +1 @@ +Force datalad to be non-interactive on _queued_ jobs by `Fede Raimondo`_ \ No newline at end of file diff --git a/docs/changes/newsfragments/203.doc b/docs/changes/newsfragments/203.doc new file mode 100644 index 000000000..7aea47778 --- /dev/null +++ b/docs/changes/newsfragments/203.doc @@ -0,0 +1 @@ +Migrate and document changelog creation and maintenance via ``towncrier`` by `Synchon Mandal`_ \ No newline at end of file diff --git a/docs/changes/newsfragments/205.doc b/docs/changes/newsfragments/205.doc new file mode 100644 index 000000000..1ef12cf48 --- /dev/null +++ b/docs/changes/newsfragments/205.doc @@ -0,0 +1 @@ +Add copy button to documentation code blocks by `Synchon Mandal`_ \ No newline at end of file diff --git a/docs/changes/newsfragments/64.feature b/docs/changes/newsfragments/64.feature new file mode 100644 index 000000000..cde4bc078 --- /dev/null +++ b/docs/changes/newsfragments/64.feature @@ -0,0 +1 @@ +Add :class:`junifer.markers.EdgeCentricFCParcels` and :class:`junifer.markers.EdgeCentricFCSpheres` by `Leonard Sasse`_ \ No newline at end of file diff --git a/docs/contribution.rst b/docs/contribution.rst index 6c947e26c..79e386a1f 100644 --- a/docs/contribution.rst +++ b/docs/contribution.rst @@ -8,61 +8,68 @@ Contributing to junifer Setting up the local development environment -------------------------------------------- -1. Fork the https://github.com/juaml/junifer repository on GitHub. If you +#. Fork the https://github.com/juaml/junifer repository on GitHub. If you have never done this before, `follow the official guide `_. -2. Clone your fork locally as described in the same guide. -3. Install your local copy into a Python virtual environment. You can `read +#. Clone your fork locally as described in the same guide but also add the + flag to sync the submodules as well by appending the following to the + clone commmand: + + .. code-block:: bash + + ... --recurse-submodules + +#. Install your local copy into a Python virtual environment. You can `read this guide to learn more `_ about them and how to create one. - .. code-block:: console + .. code-block:: bash pip install -e ".[dev]" -4. Create a branch for local development using the ``main`` branch as a +#. Create a branch for local development using the ``main`` branch as a starting point. Use ``fix``, ``refactor``, or ``feat`` as a prefix. - .. code-block:: console + .. code-block:: bash git checkout main git checkout -b / Now you can make your changes locally. -5. When making changes locally, it is helpful to ``git commit`` your work +#. When making changes locally, it is helpful to ``git commit`` your work regularly. On one hand to save your work and on the other hand, the smaller the steps, the easier it is to review your work later. Please use `semantic commit messages `_. - .. code-block:: console + .. code-block:: bash git add . git commit -m ": " -6. When you're done making changes, check that your changes pass our test suite. +#. When you're done making changes, check that your changes pass our test suite. This is all included with ``tox``. - .. code-block:: console + .. code-block:: bash tox You can also run all ``tox`` tests in parallel. As of ``tox 3.7``, you can run - .. code-block:: console + .. code-block:: bash tox --parallel -7. Push your branch to GitHub. +#. Push your branch to GitHub. - .. code-block:: console + .. code-block:: bash git push origin / -8. Open the link displayed in the message when pushing your new branch in order +#. Open the link displayed in the message when pushing your new branch in order to submit a pull request. Please follow the template presented to you in the web interface to complete your pull request. @@ -72,17 +79,38 @@ GitHub Pull Request guidelines Before you submit a pull request, check that it meets these guidelines: -1. The pull request should include tests in the respective ``tests`` directory. +#. The pull request should include tests in the respective ``tests`` directory. Except in rare circumstances, code coverage must not decrease (as reported by codecov which runs automatically when you submit your pull request). -2. If the pull request adds functionality, the docs should be +#. If the pull request adds functionality, the docs should be updated. Consider creating a Python file that demonstrates the usage in ``examples/`` directory. -3. The pull request should also include a short one-liner of your contribution - in ``docs/changes/latest.inc``. If it's your first contribution, also add - yourself to ``docs/changes/contributors.inc``. -4. The pull request will be tested against several Python versions. -5. Someone from the core team will review your work and guide you to a successful +#. Make sure to create a Draft Pull Request. If you are not sure how to do it, + check `here `_. +#. Note the pull request ID assigned after completing the previous step and create + a short one-liner file of your contribution named as ``.`` + in ``docs/changes/newsfragments/``, ```` being as per the following + convention: + + * API change : ``change`` + * Bug fix : ``bugfix`` + * Enhancement : ``enh`` + * Feature : ``feature`` + * Documentation improvement : ``doc`` + * Miscellaneous : ``misc`` + * Deprecation and API removal : ``removal`` + + For example, a basic documentation improvement can be recorded in a file + ``101.doc`` with the content: + + .. code-block:: + + Fixed a typo in intro by `junifer's biggest fan`_ + +#. If it's your first contribution, also add yourself to + ``docs/changes/contributors.inc``. +#. The pull request will be tested against several Python versions. +#. Someone from the core team will review your work and guide you to a successful contribution. @@ -95,7 +123,7 @@ tests that make sure that the code runs as intended. To run all tests -.. code-block:: console +.. code-block:: bash tox -e test @@ -105,7 +133,7 @@ Adding and building documentation Building the documentation requires some extra packages and can be installed by -.. code-block:: console +.. code-block:: bash pip install -e ".[docs]" diff --git a/docs/maintaining.rst b/docs/maintaining.rst index b2c771bfb..06be4c848 100644 --- a/docs/maintaining.rst +++ b/docs/maintaining.rst @@ -24,41 +24,61 @@ Releasing a new version ----------------------- Once the milestone is reached (all issues closed), it is time to do a new -release. +release. Make sure you have +`towncrier `_ installed +before proceeding. -1. Open a PR to update documentation: - - `docs/changes/latest.inc` should now be renamed to the version to be - released. - - `docs/whats_new.rst` must update the link to the new version. - -2. Merge PR - -3. Make sure you are in sync with the main branch. +#. Make sure you are in sync with the main branch. .. code-block:: bash git checkout main git pull --rebase origin main -4. Create tag (replace ``X.Y.Z`` with the proper version). +#. Run the following to check changelog is properly generated: + +.. code-block:: bash + + towncrier build --draft + +#. Then, run: + +.. code-block:: bash + + towncrier + +to generate the proper changelog that should be reflected in +``docs/whats_new.rst``. + +#. Commit the chages, make a PR and merge via a merge commit. + +#. Make sure you are in sync with the main branch. + +.. code-block:: bash + + git checkout main + git pull --rebase origin main + +#. Create tag (replace ``X.Y.Z`` with the proper version) on the merged PR's + merge commit. .. code-block:: bash git tag -a vX.Y.Z -m "Release X.Y.Z" -5. Check that the build system is creating the proper version +#. Check that the build system is creating the proper version .. code-block:: bash SETUPTOOLS_SCM_DEBUG=1 python -m build --source --binary --out-dir dist/ . -6. Push the tag +#. Push the tag .. code-block:: bash git push origin --follow-tags -7. Optional: bump the *MAJOR* or *MINOR* segment of next release (replace ``D.E.0`` with the proper version). +#. Optional: bump the *MAJOR* or *MINOR* segment of next release (replace ``D.E.0`` with the proper version). .. code-block:: bash diff --git a/docs/whats_new.rst b/docs/whats_new.rst index 944efe434..a6b9e50a8 100644 --- a/docs/whats_new.rst +++ b/docs/whats_new.rst @@ -1,9 +1,160 @@ +.. include:: links.inc +.. include:: changes/contributors.inc + .. _whats_new: What's new ========== -.. include:: changes/latest.inc -.. include:: changes/0.0.1.inc -.. include:: changes/contributors.inc -.. include:: links.inc +.. towncrier release notes start + +junifer 0.0.1 (2022-12-20) +-------------------------- + +API Changes +^^^^^^^^^^^ + +- Change the ``single_output`` default parameter in storage classes from + ``False`` to ``True`` by `Fede Raimondo`_ (:gh:`134`) + +Bugfixes +^^^^^^^^ + +- Fix a bug in which a :class:`junifer.datagrabber.PatternDataGrabber` would + now work with relative ``datadir`` paths (reported by `Leonard Sasse`_, + fixed by `Fede Raimondo`_) (:gh:`96`, :gh:`98`) + +- Fix a bug in which :class:`junifer.datagrabber.DataladAOMICPIOP2` datagrabber + did not use user input to constrain elements based on tasks by + `Leonard Sasse`_ (:gh:`105`) + +- Fix a bug in which a datalad dataset could remove a user-cloned dataset by + `Fede Raimondo`_ (:gh:`53`) + +- Fix a bug in which CLI command would not work using elements with more than + one field by `Fede Raimondo`_ + +- Fix a bug in which the generated DAG for HTCondor will not work by + `Fede Raimondo`_ (:gh:`143`) + +Improved Documentation +^^^^^^^^^^^^^^^^^^^^^^ + +- Add an example how to use ``junifer`` and ``julearn`` in one pipeline to + extract features and do machine learning by `Leonard Sasse`_, + `Nicolas Nieto`_, and `Sami Hamdan`_ (:gh:`40`) + +- Add documentation for the datagrabbers by `Leonard Sasse`_, + `Nicolas Nieto`_, and `Sami Hamdan`_ + +- Change documentation template to furo. Fix references and standardize + documentation by `Fede Raimondo`_ (:gh:`114`) + +Enhancements +^^^^^^^^^^^^ + +- Add comments to :class:`junifer.datagrabber.DataladDataGrabber` datagrabber + and change to use ``datalad-clone`` instead of ``datalad-install`` by + `Benjamin Poldrack`_ (:gh:`55`) + +- Upgrade storage interface for storage-like objects by `Synchon Mandal`_ + (:gh:`84`) + +- Add missing type annotations by `Synchon Mandal`_ (:gh:`74`) + +- Refactor markers ``on`` attribute and ``get_valid_inputs`` to verify that the + marker can be computed on the input data types by `Fede Raimondo`_ + +- Add test for :class:`junifer.datagrabber.DataladHCP1200` datagrabber by + `Synchon Mandal`_ (:gh:`93`) + +- Rename "atlas" to "parcellation" by `Fede Raimondo`_ (:gh:`116`) + +- Refactor the :class:`junifer.datagrabber.BaseDataGrabber` class to allow for + easier subclassing by `Fede Raimondo`_ (:gh:`123`) + +- Allow custom aggregation method for :class:`junifer.markers.SphereAggregation` + by `Synchon Mandal`_ (:gh:`102`) + +- Add support for "masks" by `Fede Raimondo`_ (:gh:`79`) + +- Allow :class:`junifer.markers.ParcelAggregation` to apply multiple + parcellations at once by `Fede Raimondo`_ (:gh:`131`) + +- Refactor :class:`junifer.pipeline.PipelineStepMixin` to improve its + implementation and validation for pipeline steps by `Synchon Mandal`_ + (:gh:`152`) + +Features +^^^^^^^^ + +- Implement :class:`junifer.testing.datagrabbers.SPMAuditoryTestingDatagrabber` + datagrabber by `Fede Raimondo`_ (:gh:`52`) + +- Implement matrix storage in SQliteFeatureStorage by `Fede Raimondo`_ + (:gh:`42`) + +- Implement :class:`junifer.markers.FunctionalConnectivityParcels` marker for + functional connectivity using a parcellation by `Amir Omidvarnia`_ and + `Kaustubh R. Patil`_ (:gh:`41`) + +- Implement coordinate register, list and load by `Fede Raimondo`_ (:gh:`11`) + +- Add :class:`junifer.datagrabber.DataladAOMICID1000` datagrabber for AOMIC + ID1000 dataset including tests and creation of mock dataset for testing by + `Vera Komeyer`_ and `Xuan Li`_ (:gh:`60`) + +- Add support to access other input in the data object in the ``compute`` method + by `Fede Raimondo`_ + +- Implement :class:`junifer.markers.RSSETSMarker` marker by `Leonard Sasse`_, + `Nicolas Nieto`_ and `Sami Hamdan`_ (:gh:`51`) + +- Implement :class:`junifer.markers.SphereAggregation` marker by + `Fede Raimondo`_ + +- Implement :class:`junifer.datagrabber.DataladAOMICPIOP1` and + :class:`junifer.datagrabber.DataladAOMICPIOP2` datagrabbers for AOMIC PIOP1 + and PIOP2 datasets respectively and refactor + :class:`junifer.datagrabber.DataladAOMICID1000` slightly by `Leonard Sasse`_ + (:gh:`94`) + +- Implement :class:`junifer.configs.juseless.datagrabbers.JuselessDataladCamCANVBM` + datagrabber by `Leonard Sasse`_ (:gh:`99`) + +- Implement :class:`junifer.configs.juseless.datagrabbers.JuselessDataladIXIVBM` + CAT output datagrabber for juseless by `Leonard Sasse`_ (:gh:`48`) + +- Add ``junifer wtf`` to report environment details by `Synchon Mandal`_ + (:gh:`33`) + +- Add ``junifer selftest`` to report environment details by `Synchon Mandal`_ + (:gh:`9`) + +- Implement :class:`junifer.configs.juseless.datagrabbers.JuselessDataladAOMICID1000VBM` + datagrabber for accessing AOMIC ID1000 VBM from juseless by `Felix Hoffstaedter`_ + and `Synchon Mandal`_ (:gh:`57`) + +- Add :class:`junifer.preprocess.fMRIPrepConfoundRemover` by `Fede Raimondo`_ + and `Leonard Sasse`_ (:gh:`111`) + +- Implement :class:`junifer.markers.CrossParcellationFC` marker by + `Leonard Sasse`_ and `Kaustubh R. Patil`_ (:gh:`85`) + +- Add :class:`junifer.configs.juseless.datagrabbers.JuselessUCLA` datagrabber + for the UCLA dataset available on juseless by `Leonard Sasse`_ (:gh:`118`) + +- Introduce a singleton decorator for marker computations by `Synchon Mandal`_ + (:gh:`151`) + +- Implement :class:`junifer.markers.ReHoParcels` and + :class:`junifer.markers.ReHoSpheres` markers by `Synchon Mandal`_ (:gh:`36`) + +- Implement :class:`junifer.markers.AmplitudeLowFrequencyFluctuationParcels` and + :class:`junifer.markers.AmplitudeLowFrequencyFluctuationSpheres` markers by + `Fede Raimondo`_ (:gh:`35`) + +Misc +^^^^ + +- Create the repository based on the mockup by `Fede Raimondo`_ diff --git a/pyproject.toml b/pyproject.toml index d0e2c6190..1f7863c65 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -70,6 +70,7 @@ docs = [ "numpydoc>=1.5.0,<1.6", "julearn==0.2.5", "sphinx-copybutton==0.5.1", + "towncrier==22.12.0", ] ################ @@ -96,3 +97,46 @@ extend-exclude = """ [tool.pytest.ini_options] minversion = "7.0" addopts = "--ignore=junifer/external/h5io -vv" + +[tool.towncrier] +directory = "docs/changes/newsfragments" +filename = "docs/whats_new.rst" +package = "junifer" +# to use gh_substitutions +issue_format = ":gh:`{issue}`" +# modify to have proper toctree +underlines = "-^~" +# set line length to 79 +wrap = true + +# Need to put default explicitly as custom is not combined with default + +[tool.towncrier.fragment.bugfix] +name = "Bugfixes" +showcontent = true + +[tool.towncrier.fragment.doc] +name = "Improved Documentation" +showcontent = true + +[tool.towncrier.fragment.feature] +name = "Features" +showcontent = true + +[tool.towncrier.fragment.misc] +name = "Misc" +showcontent = true + +[tool.towncrier.fragment.removal] +name = "Deprecations and Removals" +showcontent = true + +# Add custom towncrier fragment for enhancements +[tool.towncrier.fragment.enh] +name = "Enhancements" +showcontent = true + +# Add custom towncrier fragment for API changes +[tool.towncrier.fragment.change] +name = "API Changes" +showcontent = true \ No newline at end of file