# FEDI Testing Directory

This directory contains example files used for testing FEDI command-line tools. These files are referenced by the automated test suite (`FEDI.utils.fedi_testing_commands`) to verify that all FEDI commands work correctly.

## Files

### `gradient_table_example.txt`

**Description:** Example gradient table file containing unitary diffusion gradient directions and b-value shell assignments.

**Format:** Tab-delimited text file with the following structure:
- Header lines (starting with `#`) containing metadata and copyright information
- Data rows starting with `#shell` header line
- Each data row contains: `shell_number`, `u_x`, `u_y`, `u_z`
  - `shell_number`: Integer indicating which b-value shell (1, 2, etc.)
  - `u_x`, `u_y`, `u_z`: Unit vector components of the gradient direction

**Source:** Generated from the online Q-space sampling script at http://www.emmanuelcaruyer.com/q-space-sampling.php

**Usage:** Used by `fedi_dmri_qweights` to test gradient scheme processing and conversion to Siemens scanner format.

**Example:**
```
#shell	u_x	u_y	u_z
2	0.625	0.776	0.076
2	0.745	-0.623	0.237
1	0.234	-0.093	-0.968
```

---

### `example_Transform_v1_0GenericAffine.mat`
### `example_Transform_v2_0GenericAffine.mat`
### `example_Transform_v3_0GenericAffine.mat`

**Description:** Example ANTs transformation matrix files in MATLAB format. These are affine transformation matrices used for b-vector rotation.

**Format:** MATLAB `.mat` file containing:
- `AffineTransform_double_3_3`: A 4×4 transformation matrix stored as a flattened array (16 elements)
  - The first 9 elements represent the 3×3 rotation matrix
  - The remaining elements include translation and homogeneous coordinates

**Usage:** Used by `fedi_dmri_rotate_bvecs` to test b-vector rotation using ANTs transformation matrices.

**Naming Convention:** 
- `Transform_v{volume_index}_{suffix}`
- Example: `Transform_v1_0GenericAffine.mat` corresponds to volume index 1
- The test suite renames these to `Transform_v0`, `Transform_v1`, `Transform_v2` to match expected naming

**Note:** These are example files for testing purposes. In real usage, transformation matrices are typically generated by ANTs registration tools (e.g., `antsRegistration`) during motion correction or registration workflows.

---

## Usage in Tests

These example files are automatically used by the FEDI test suite:

1. **`fedi_dmri_qweights`**: Uses `gradient_table_example.txt` with b-values 500 and 1000 to test gradient scheme processing.

2. **`fedi_dmri_rotate_bvecs`**: Uses the example transform files (`example_Transform_v1/2/3_0GenericAffine.mat`) to test b-vector rotation. The test extracts volumes 1, 2, and 3 from the test data and applies the corresponding transformations.

## Running Tests

To run the automated test suite that uses these files:

```bash
python -m FEDI.utils.fedi_testing_commands
```

The test suite will:
1. Generate synthetic test data (saved to `~/.fedi_test_data/`)
2. Run all FEDI commands using the example files from this directory
3. Verify that outputs are created correctly

## File Locations

- **Test data generation**: `~/.fedi_test_data/` (user's home directory)
- **Example files**: This directory (`testing/`)
- **Test outputs**: `~/.fedi_test_data/` (preserved for inspection)

## References

- Gradient table format: Caruyer, E., Lenglet, C., Sapiro, G., and Deriche, R. "Design of multishell sampling schemes with uniform coverage in diffusion MRI." Magnetic Resonance in Medicine 69, no. 6 (2013): 1534-1540.
- ANTs transformation format: Advanced Normalization Tools (ANTs) - https://github.com/ANTsX/ANTs

