Update documentation (#8)

Author: tsalo

README.md

@@ -1,74 +1,74 @@
-# ConFixel: Moved to ModelArrayIO
+# ModelArrayIO
 
-ConFixel has moved beyond fixels and handles a lot of other modalities.
-It also got optimized!
-[Going forward, ConFixel is now ModelArrayIO.](https://pennlinc.github.io/ModelArrayIO/). 
-This repository will be left here because the URL is in the publication.
+**ModelArrayIO** is a Python package that converts between neuroimaging formats (fixel `.mif`, voxel NIfTI, CIFTI-2 dscalar) and the HDF5 (`.h5`) layout used by the R package [ModelArray](https://pennlinc.github.io/ModelArray/). It can also write ModelArray statistical results back to imaging formats.
 
+**Relationship to ConFixel:** The earlier project [**ConFixel**](https://github.com/PennLINC/ConFixel) is superseded by ModelArrayIO. The ConFixel repository is retained for history (including links from publications) and will be archived; new work should use this repository.
 
-`ConFixel` is companion converter software for [ModelArray](https://pennlinc.github.io/ModelArray/) for converting data back and forth from the HDF5 file format.
+Documentation for installation and usage: [ModelArrayIO on GitHub](https://github.com/PennLINC/ModelArrayIO#installation) (this README). For conda, HDF5 libraries, and installing the ModelArray R package, see the ModelArray vignette [Installation](https://pennlinc.github.io/ModelArray/articles/installations.html).
 
 <p align="center">
 
 ![Overview](overview_structure.png)
 
 </p>
 
-`ConFixel` software includes three converters: `ConFixel` for fixel-wise data (`.mif`), `ConVoxel` for voxel-wise data (NIfTI) and `ConCIFTI` for CIFTI-2 dscalar files. Each converter converts between the original image format and the HDF5 file format (`.h5`) that ModelArray uses.
+ModelArrayIO provides three converter areas, each with import and export commands:
 
-Below lists the commands in each converter. After [installation](#installation), these commands can be directly called in a terminal console.
+After [installation](#installation), these commands are available in your terminal:
 
-* `ConFixel` converter for fixel-wise data (MRtrix image format `.mif`):
-    * `.mif` --> `.h5`: command `confixel`
-    * `.h5` --> `.mif`: command `fixelstats_write`
-* `ConVoxel` converter for voxel-wise data (NIfTI):
-    * NIfTI --> `.h5`: command `convoxel`
-    * `.h5` --> NIfTI: command `volumestats_write`
-* `ConCIFTI` converter for greyordinate-wise data (CIFTI-2):
-    * CIFTI-2 --> `.h5`: command `concifti`
-    * `.h5` --> CIFTI-2: command `ciftistats_write`
+* **Fixel-wise** data (MRtrix `.mif`):
+    * `.mif` → `.h5`: `confixel` (CLI name kept for compatibility with earlier ConFixel workflows)
+    * `.h5` → `.mif`: `fixelstats_write`
+* **Voxel-wise** data (NIfTI):
+    * NIfTI → `.h5`: `convoxel`
+    * `.h5` → NIfTI: `volumestats_write`
+* **Greyordinate-wise** data (CIFTI-2):
+    * CIFTI-2 → `.h5`: `concifti`
+    * `.h5` → CIFTI-2: `ciftistats_write`
 
 ## Installation
 ### Install dependent software MRtrix (only required for fixel-wise data `.mif`)
-When converting fixel-wise data's format (`.mif`), converter `ConFixel` uses function `mrconvert` from MRtrix, so please make sure MRtrix has been installed. If it's not installed yet, please refer to [MRtrix's webpage](https://www.mrtrix.org/download/) for how to install it. Type `mrview` in the terminal to check whether MRtrix installation is successful.
+For fixel-wise `.mif` conversion, the `confixel` / `fixelstats_write` tools use MRtrix `mrconvert`. Install MRtrix from [MRtrix’s webpage](https://www.mrtrix.org/download/) if needed. Run `mrview` in the terminal to verify the installation.
 
-If your input data is voxel-wise data or CIFTI (greyordinate-wise) data, you can skip this step.
+If your data are voxel-wise or CIFTI only, you can skip this step.
 
-### Install `ModelArrayIO` software
-Before installing ModelArrayIO software, you may want to create a conda environment  - see [here](https://pennlinc.github.io/ModelArray/articles/installations.html) for more. If you installed MRtrix in a conda environment, you can directly install ConFixel software in that environment.
+### Install ModelArrayIO
+You may want a conda environment first—see [ModelArray: Installation](https://pennlinc.github.io/ModelArray/articles/installations.html). If MRtrix is installed in that environment, install ModelArrayIO in the same environment.
 
-You can install `ModelArrayIO` software from `GitHub`:
+Install from GitHub:
 
 ``` console
 git clone https://github.com/PennLINC/ModelArrayIO.git
 cd ModelArrayIO
 pip install .   # build via pyproject.toml
 ```
 
-If you are a developer, and if there is any update in the source code locally, you may update the installation with an editable install:
+Editable install for development:
 
 ``` console
 # From the repository root
 pip install -e .
 ```
 
-Alternatively, if you have `hatch` installed, you can build wheels/sdist locally:
+With `hatch` installed, you can build wheels/sdist locally:
 
 ``` console
 hatch build
 pip install dist/*.whl
 ```
 
 ## How to use
-We provide [walkthrough for how to use `ConFixel` for fixel-wise data](notebooks/walkthrough_fixel-wise_data.md), and [walkthrough for `ConVoxel` for voxel-wise data](notebooks/walkthrough_voxel-wise_data.md).
+We provide a [walkthrough for fixel-wise data](notebooks/walkthrough_fixel-wise_data.md) (`confixel` / `fixelstats_write`) and a [walkthrough for voxel-wise data](notebooks/walkthrough_voxel-wise_data.md) (`convoxel` / `volumestats_write`).
 
-As `ConFixel` software is usually used together with [ModelArray](https://pennlinc.github.io/ModelArray/), we also provide [a combined walkthrough](https://pennlinc.github.io/ModelArray/articles/walkthrough.html) of ConFixel + ModelArray with example fixel-wise data.
+Together with [ModelArray](https://pennlinc.github.io/ModelArray/), see the [combined walkthrough](https://pennlinc.github.io/ModelArray/articles/walkthrough.html) with example fixel-wise data (ModelArray + ModelArrayIO).
+
+CLI help:
 
-You can also refer to `--help` for additional information:
 ``` console
 confixel --help
 ```
-You can replace `confixel` with other commands in ConFixel.
+
+Use the same pattern for `convoxel`, `concifti`, `fixelstats_write`, `volumestats_write`, and `ciftistats_write`.
 
 ## Storage backends: HDF5 and TileDB
 

notebooks/README.md

@@ -1,4 +1,4 @@
 # Walkthrough for different imaging data types
 
-* [Walkthrough for fixel-wise data conversion](walkthrough_fixel-wise_data.md) using converter `ConFixel`
-* [Walkthrough for voxel-wise data conversion](walkthrough_voxel-wise_data.md) using converter `ConVoxel`
+* [Walkthrough for fixel-wise data conversion](walkthrough_fixel-wise_data.md) (`confixel` / `fixelstats_write` in ModelArrayIO)
+* [Walkthrough for voxel-wise data conversion](walkthrough_voxel-wise_data.md) (`convoxel` / `volumestats_write` in ModelArrayIO)

notebooks/walkthrough_fixel-wise_data.md

@@ -1,6 +1,6 @@
 # Walkthrough for fixel-wise data conversion
 
-For fixel-wise data, we use converter `ConFixel` to convert between fixel-wise data format `.mif` and the HDF5 file format (`.h5`) that ModelArray uses. At this point, we expect you have followed the [Installation guide](../README.md#installation) and installed `ConFixel` software and dependent software `MRtrix` which is needed for fixel-wise data.
+For fixel-wise data, use the **`confixel`** command (from the **ModelArrayIO** Python package) to convert between MRtrix `.mif` files and the HDF5 file format (`.h5`) that ModelArray uses. This guide assumes you followed the [installation guide](../README.md#installation), installed **ModelArrayIO**, and installed **MRtrix** for fixel-wise workflows.
 
 ## Prepare data
 
@@ -57,10 +57,10 @@ Notes:
     * File names in column `source_file` in CSV file v.s. the actual file names on disk;
     * Scalar name e.g., "FD" in column `scalar_name` in CSV file v.s. what you will specify when using functions in `ModelArray`;
 
-For this case, when running ConFixel creating hdf5 fixel-wise data, argument **--relative-root** should be "/home/username/myProject/data"
+For this case, when running `confixel` to create HDF5 fixel-wise data, argument **--relative-root** should be "/home/username/myProject/data"
 
 
-## Run ConFixel
+## Run `confixel` and `fixelstats_write`
 ### Convert .mif files to an HDF5 (.h5) file
 Using above described scenario as an example, for FD dataset:
 ``` console
@@ -72,7 +72,6 @@ confixel \
     --relative-root /home/username/myProject/data \
     --output-hdf5 FD.h5
 ```
-<!-- ^ above is tested -->
 
 Now you should get the HDF5 file "FD.h5" in folder "/home/username/myProject/data". You may use [ModelArray](https://pennlinc.github.io/ModelArray/) to perform statistical analysis.
 
@@ -100,16 +99,11 @@ confixel --help
 fixelstats_write --help
 ```
 
-<!--TODO: after update please test out: use conda + terminal command `confixel` and `fixelstats_write`; Still using case above as an example -->
-<!-- fixelstats_write: can be tested out with existing results; otherwise have to run for all fixels.. -->
-
 
 ## Other notes
-### ConFixel: convert from `.h5` to `.mif`
+### Export from `.h5` to `.mif` (`fixelstats_write`)
 #### Existing output folder and output images
 ⚠️ ⚠️ WARNING ⚠️ ⚠️
-* If there are existing images in the output folder and they have the same filenames as those to be saved, the existing images won't be overwritten. This is because in function `confixel.fixels.nifti2_to_mif()`, we did not turn on `-force` in `mrconvert` (i.e., output files won't be overwritten).
-* In addition, if the output folder already exists, `ConFixel` will not delete it or create a new one. You will only get a message saying "WARNING: Output directory exists". Therefore, any existing files in the output folder will be kept as it is.
-* So, if the output folder already exists, you may consider manually deleting it before using `ConFixel` to save new images.
-
-<!--- TODO: above words: to be confirmed! --->
+* If there are existing images in the output folder and they have the same filenames as those to be saved, the existing images won't be overwritten. This is because in `modelarrayio.fixels.nifti2_to_mif()`, we did not turn on `-force` in `mrconvert` (i.e., output files won't be overwritten).
+* In addition, if the output folder already exists, `fixelstats_write` will not delete it or create a new one. You will only get a message saying "WARNING: Output directory exists". Therefore, any existing files in the output folder will be kept as it is.
+* So, if the output folder already exists, you may consider manually deleting it before using `fixelstats_write` to save new images.

notebooks/walkthrough_voxel-wise_data.md

@@ -1,11 +1,11 @@
 # Walkthrough for voxel-wise data conversion
 
-For voxel-wise data, we use converter `ConVoxel`. In general, `ConVoxel` is very similar to converter `ConFixel`.
+For voxel-wise data, use the **`convoxel`** command from **ModelArrayIO**. In general, the voxel workflow is very similar to the fixel workflow (`confixel`).
 
 ## Prepare data
 To convert (a list of) voxel-wise data from NIfTI format to .h5 format, you need to prepare a cohort CSV file that provides basic information for all NIfTI files you want to include. We recommend that, for each scalar (e.g. FA), prepare one .csv file, and thus getting one .h5 file.
 
-In addition, different from converter `ConFixel`, you also need to provide these image files:
+In addition, unlike the fixel pipeline, you also need to provide these image files:
 * one group mask: Only voxels within the group mask will be kept during conversion to .h5 file.
 * subject-specific masks (i.e., individual masks): This takes the inconsistent boundary of subject-specific images into account. After conversion, for each subject's scalar mage, voxels outside the subject-specific mask will be set to `NaN`. `ModelArray` will then check if each voxel has sufficient number of subjects to get reliable statistics (see argument `num.subj.lthr.abs` and `num.subj.lthr.rel` in Model fitting functions, e.g., [`ModelArray.lm()`](https://pennlinc.github.io/ModelArray/reference/ModelArray.lm.html)).
     * If you don't have subject-specific masks, that's fine; you can use group mask instead (see below for how to achieve this in .csv file).
@@ -56,13 +56,13 @@ Notes:
     * File names in columns `source_file` and `source_mask_file` in CSV file v.s. the actual file names on disk;
     * Scalar name e.g., "FA" in column `scalar_name` in CSV file v.s. what you will specify when using functions in `ModelArray`;
 
-For this case, when running ConVoxel, argument `--relative-root` should be `/home/username/myProject/data`
+For this case, when running `convoxel`, argument `--relative-root` should be `/home/username/myProject/data`
 
-## Run ConVoxel
+## Run `convoxel` and `volumestats_write`
 ### Convert NIfTI files to an HDF5 (.h5) file
 Using above described scenario as an example, for FA dataset:
 ``` console
-# first, activate conda environment where `ConFixel` is installed: `conda activate <env_name>`
+# first, activate conda environment where ModelArrayIO is installed: `conda activate <env_name>`
 convoxel \
     --group-mask-file group_mask.nii.gz \
     --cohort-file cohort_FA.csv \
@@ -76,7 +76,7 @@ Now you should get the HDF5 file "FA.h5" in folder "/home/username/myProject/dat
 After running `ModelArray` and getting statistical results in FA.h5 file (say, the analysis name is called "mylm"), you can use `volumestats_write` to convert results into a list of NIfTI files in a folder specified by you.
 
 ``` console
-# first, activate conda environment where software `ConFixel` is installed: `conda activate <env_name>`
+# first, activate conda environment where ModelArrayIO is installed: `conda activate <env_name>`
 volumestats_write \
     --group-mask-file group_mask.nii.gz \
     --cohort-file cohort_FA.csv \
@@ -99,12 +99,12 @@ volumestats_write --help
 ```
 
 ## Other notes
-### ConVoxel: convert from `.h5` to NIfTI
+### `volumestats_write`: convert from `.h5` to NIfTI
 #### Existing output folder and output images
 ⚠️ ⚠️ WARNING ⚠️ ⚠️
-* If the output folder already exists, `ConVoxel` will not delete it or create a new one. You will only get a message saying "WARNING: Output directory exists". Therefore, if there were existing files in the output folder, and they are not part of the current list of images to be saved (e.g., results to be saved were changed, but the output folder name was not changed), these files will be kept as it is and won't be deleted.   <!--- confirmed with toy data, 3/9/2023 -->
-    * However, for existing files which are still part of the current list to be saved, they will be replaced. This is different from current implementation of `ConFixel` converter for fixel-wise data.   <!--- confirmed with toy data, 3/9/2023 -->
-* So to avoid confusion and better for version controls, if the output folder already exists, you might consider manually deleting it before using `ConVoxel` to save new images.
+* If the output folder already exists, `volumestats_write` will not delete it or create a new one. You will only get a message saying "WARNING: Output directory exists". Therefore, if there were existing files in the output folder, and they are not part of the current list of images to be saved (e.g., results to be saved were changed, but the output folder name was not changed), these files will be kept as it is and won't be deleted.
+    * However, for existing files which are still part of the current list to be saved, they will be replaced. This differs from the fixel-wise `fixelstats_write` behavior (which does not overwrite existing `.mif` outputs via `mrconvert` without `-force`).
+* So to avoid confusion and better for version controls, if the output folder already exists, you might consider manually deleting it before using `volumestats_write` to save new images.
 
 
 ### Image of number of observations used

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "modelarrayio"
-description = "ConFixel (python) is companion converter software for ModelArray for converting data back and forth from the HDF5 file format"
+description = "ModelArrayIO: convert fixel, voxel, and greyordinate neuroimaging data to/from HDF5 for the ModelArray R package"
 readme = "README.md"
 requires-python = ">=3.11"
 license = { file = "LICENSE" }
@@ -42,6 +42,7 @@ doc = [
   "sphinx>=6.2.1",
   "myst-parser>=2",
   "sphinx-argparse",
+  "sphinx-copybutton",
   "sphinx_rtd_theme",
   "sphinxcontrib-apidoc",
   "sphinxcontrib-bibtex",

test/data_voxel_toy/README.md

@@ -1,6 +1,6 @@
-This is a toy voxel-wise dataset for testing ConVoxel.
+This is a toy voxel-wise dataset for testing ModelArrayIO’s voxel pipeline (`convoxel` / `volumestats_write`).
 * It was generated using scripts in [ModelArray_tests](https://github.com/PennLINC/ModelArray_tests) GitHub repository.
-  * Using scripts in folder `testdata_ConFixel` there.
+  * Using scripts in folder `testdata_ConFixel` there (historical folder name from the ConFixel era).
 * It includes n=20 voxel-wise data with individual masks and a group mask.
   * Each voxel-wise image has random values in a center ball, and may or may not have values around this ball, making individual masks different among all subjects.
   * The values are between 0-1.