From 49815637c849fbb6ad4ae45790497071d03c7463 Mon Sep 17 00:00:00 2001 From: Ariel Rokem Date: Wed, 2 Sep 2026 08:51:13 -0400 Subject: [PATCH 1/5] WIP: Remove redundancies with homepage. --- docs/source/index.md | 79 +---------- docs/source/trx_specifications.md | 219 ------------------------------ 2 files changed, 7 insertions(+), 291 deletions(-) delete mode 100644 docs/source/trx_specifications.md diff --git a/docs/source/index.md b/docs/source/index.md index d5ce474f..c5f4dfc6 100644 --- a/docs/source/index.md +++ b/docs/source/index.md @@ -1,84 +1,19 @@ -# TRX: A community-oriented tractography file format +# TRX in Python -We propose **TRX**, a tractography file format designed to facilitate dataset -exchange, interoperability, and state-of-the-art analyses, acting as a -community-driven replacement for the myriad existing file formats. +This software library implements the TRX file format for +tractography in the Pythonprogramming language. ## Getting Started -New to TRX? Start here: +1. **Understand the format**: To understand the TRX file structure and learn Why TRX, please to the [TRX homepage](https://tee-ar-ex.github.io) +2. **Installation** +3. **Learn by example**: Follow our {doc}`auto_examples/index` to learn how to read, write, and manipulate TRX files +4. **Use the CLI tools**: Check out the {doc}`scripts` documentation for command-line operations -1. **Understand the format**: Read the {doc}`trx_specifications` to understand the TRX file structure -2. **Learn by example**: Follow our {doc}`auto_examples/index` to learn how to read, write, and manipulate TRX files -3. **Use the CLI tools**: Check out the {doc}`scripts` documentation for command-line operations - -````{grid} 2 - -```{grid-item-card} Tutorials -:link: auto_examples/index -:link-type: doc - -Learn how to work with TRX files through hands-on tutorials covering -reading/writing files, working with groups, and using metadata. -``` - -```{grid-item-card} TRX Specifications -:link: trx_specifications -:link-type: doc - -Complete technical specifications of the TRX file format including -header fields, array structures, and naming conventions. -``` -```` - -## Why TRX? - -File formats that store the results of computational tractography were typically -developed within specific software packages. This approach has facilitated a -myriad of applications, but this development approach has also generated -insularity within software packages, and has limited standardization. Moreover, -because tractography file formats were developed to solve immediate challenges, -only a limited breadth of applications within a single software package was -envisioned, sometimes also neglecting computational performance. Given the -growing interest in tractography methods and applications, and the increasing -size and complexity of datasets, a community-driven standardization of -tractography have become a priority. To address these challenges, our community -initiated a discussion to design a new file format and agreed to participate in -its conception, development, and, if successful, its adoption. - -The goal of TRX is to become the first, community-driven, standard amongst -tractography file formats. As with other file formats like NiFTI, we believe -that TRX will serve the community well and the growing computational needs of -our field. We encourage community members to consider early contributions to our -proposal so as to ensure the new standard will cover the needs of the wider -audience of software developers, toolboxes, and scientists. Our long-term plan -is to integrate TRX within the [Brain Imaging Data Structure (BIDS)](https://bids.neuroimaging.io/) ecosystem. - -## Acknowledgments - -Development of TRX is supported by [NIMH grant 1R01MH126699](https://reporter.nih.gov/search/D-c1NJBQFE-BkwP1Cxc2Lg/project-details/10253558). ```{toctree} :maxdepth: 2 -:caption: User Guide: -trx_specifications scripts -``` - -```{toctree} -:maxdepth: 2 -:caption: Tutorials: -auto_examples/index -``` - -```{toctree} -:maxdepth: 2 -:caption: Development: dev -``` - -```{toctree} -:maxdepth: 2 -:caption: API Reference: autoapi/index ``` diff --git a/docs/source/trx_specifications.md b/docs/source/trx_specifications.md deleted file mode 100644 index 016d15e6..00000000 --- a/docs/source/trx_specifications.md +++ /dev/null @@ -1,219 +0,0 @@ ---- -html_theme.sidebar_secondary.remove: ---- - -# TRX File Format Specifications - -This document contains the complete specifications for the TRX (Tractography File Format) -as defined by the TRX specification. TRX is a community-oriented tractography file format -designed to facilitate dataset exchange, interoperability, and state-of-the-art analyses. - -## General Properties - -**File Structure** - -- (Un)-Compressed Zip File or simple folder architecture -- File architecture describes the data -- Each file basename is the metadata's name -- Each file extension is the metadata's dtype -- Each file dimension is in the value between basename and metadata (1-dimension arrays do not have to follow this convention for readability) - -**Data Organization** - -- All arrays have a C-style memory layout (row-major) -- All arrays have a little-endian byte order -- Compression is optional: - - - Use `ZIP_STORE` for uncompressed storage - - Use `ZIP_DEFLATE` if compression is desired - - Compressed TRX files will have to be decompressed before being loaded - -## Header - -The header contains metadata for readability, run-time checks, and broader compatibility. -It is stored as a dictionary in JSON format with the following fields: - -**Required Fields:** - -```text -VOXEL_TO_RASMM : 4x4 transformation matrix (list of 4 lists, each containing 4 floats) -DIMENSIONS : Image dimensions (list of 3 uint16) -NB_STREAMLINES : Number of streamlines (uint32) -NB_VERTICES : Total number of vertices (uint64) -``` - -## Arrays - -### positions.{N}.float{16,32,64} - -- Written in world space (RASMM), similar to TCK files -- Should always be float16/32/64 (default recommended: float16) -- Stored as contiguous 3D array with shape (NB_VERTICES, 3) -- The {N} dimension specifier can be omitted for 1D arrays for readability - -### offsets.uint{32,64} - -- Should always be uint32 or uint64 -- Indicates the starting vertex index for each streamline (starts at 0) -- Streamline lengths can be calculated by: - - 1. Checking the header for total vertices count - 2. Using positions array size: `positions.shape[0] / 3` - 3. Calculating differences between consecutive elements: append total_vertices to offsets array and compute ediff1d - -### dpv (data_per_vertex) - -- Always of size (NB_VERTICES, 1) or (NB_VERTICES, N) -- Contains data associated with each vertex/point along streamlines -- Common uses: FA values, colors, curvature, local coordinate systems - -### dps (data_per_streamline) - -- Always of size (NB_STREAMLINES, 1) or (NB_STREAMLINES, N) -- Contains data associated with entire streamlines -- Common uses: bundle IDs, mean metrics, algorithm information - -## Groups - -Groups are tables of indices that allow sparse & overlapping representation -(clusters, connectomics, bundles). - -**Properties:** - -- All indices must be `0 <= id < NB_STREAMLINES` -- Datatype should be uint32 -- Allows efficient retrieval of predefined streamline subsets from memmaps -- Variables can have different sizes - -### dpg (data_per_group) - -- Each folder corresponds to name of a group -- Not all metadata have to be present in all groups -- Always of size (1,) or (N,) per group -- Contains group-specific metadata like volumes, mean values, color codes - -## Supported Data Types - -The TRX format supports the following data types: - -**Integer Types:** - -- `int8`, `int16`, `int32`, `int64` -- `uint8`, `uint16`, `uint32`, `uint64` - -**Floating Point Types:** - -- `float16`, `float32`, `float64` - -**Boolean Type:** - -- `bit` (for boolean data) - -## Example File Structure - -```text -OHBM_demo.trx -|-- dpg -| |-- AF_L -| | |-- mean_fa.float16 -| | |-- shuffle_colors.3.uint8 -| | +-- volume.uint32 -| |-- AF_R -| | |-- mean_fa.float16 -| | |-- shuffle_colors.3.uint8 -| | +-- volume.uint32 -| |-- CC -| | |-- mean_fa.float16 -| | |-- shuffle_colors.3.uint8 -| | +-- volume.uint32 -| |-- CST_L -| | +-- shuffle_colors.3.uint8 -| |-- CST_R -| | +-- shuffle_colors.3.uint8 -| |-- SLF_L -| | |-- mean_fa.float16 -| | |-- shuffle_colors.3.uint8 -| | +-- volume.uint32 -| +-- SLF_R -| |-- mean_fa.float16 -| |-- shuffle_colors.3.uint8 -| +-- volume.uint32 -|-- dpv -| |-- color_x.uint8 -| |-- color_y.uint8 -| |-- color_z.uint8 -| +-- fa.float16 -|-- dps -| |-- algo.uint8 -| |-- algo.json -| |-- clusters_QB.uint16 -| |-- commit_colors.3.uint8 -| +-- commit_weights.float32 -|-- groups -| |-- AF_L.uint32 -| |-- AF_R.uint32 -| |-- CC.uint32 -| |-- CST_L.uint32 -| |-- CST_R.uint32 -| |-- SLF_L.uint32 -| +-- SLF_R.uint32 -|-- header.json -|-- offsets.uint64 -+-- positions.3.float16 -``` - -## Naming Conventions - -**Files:** - -- Basename = metadata name -- Extension = data type -- Dimension specifiers between basename and extension (optional for 1D) - -**Examples:** - -- `positions.3.float16` - 3D position data as float16 -- `fa.float16` - 1D fractional anisotropy values as float16 -- `colors.3.uint8` - RGB color values as 8-bit unsigned integers -- `bundle_id.uint8` - Bundle identifiers as 8-bit unsigned integers - -## Memory and Performance Considerations - -**Memory Efficiency:** - -- Use float16 for positional data when precision allows -- Choose appropriate integer sizes for indices (uint32 for streamline indices) -- Consider compression for disk storage but expect decompression overhead - -**Performance:** - -- C-style memory layout enables efficient numpy operations -- Little-endian byte order ensures consistency across platforms -- Memory-mapped access for large datasets without full loading - -**Scalability:** - -- Support for arbitrarily large numbers of streamlines and vertices -- Group-based organization enables efficient subset operations -- Flexible metadata structure accommodates various analysis workflows - -## Compatibility and Integration - -TRX is designed for integration with existing neuroimaging ecosystems: - -**Current Support:** - -- Native support in trx-python library -- Conversion tools for common tractography formats (TCK, TRK, etc.) -- Integration with DIPY for advanced processing - -**Future Goals:** - -- Integration with Brain Imaging Data Structure (BIDS) ecosystem -- Support in major neuroimaging software packages -- Standardization across the tractography community - -For latest updates and community discussions, see: - -- [TRX Specification Repository](https://github.com/tee-ar-ex/trx-spec) -- [TRX Python Implementation](https://github.com/tee-ar-ex/trx-python) From c1a6aa1e1b1d337ced37256114e4359c3e907a4c Mon Sep 17 00:00:00 2001 From: Ariel Rokem Date: Wed, 2 Sep 2026 08:51:39 -0400 Subject: [PATCH 2/5] DOC: Adds installation instructions. --- docs/source/installation.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) create mode 100644 docs/source/installation.md diff --git a/docs/source/installation.md b/docs/source/installation.md new file mode 100644 index 00000000..f43ca5f6 --- /dev/null +++ b/docs/source/installation.md @@ -0,0 +1,16 @@ +--- +html_theme.sidebar_secondary.remove: +--- + +# Installing `trx-python` + +To install a release version, use the Python package manager: + + pip install trx-python + +To install from the recent development source, download the source from GitHub and then install with pip: + + git clone https://github.com/tee-ar-ex/trx-python && cd trx-python + pip install . + + From a0b58f12236c6770b4d8ea9c86419615e21d3360 Mon Sep 17 00:00:00 2001 From: Ariel Rokem Date: Wed, 2 Sep 2026 08:52:27 -0400 Subject: [PATCH 3/5] Adds link to installation page. --- docs/source/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/source/index.md b/docs/source/index.md index c5f4dfc6..de7b1624 100644 --- a/docs/source/index.md +++ b/docs/source/index.md @@ -5,8 +5,8 @@ tractography in the Pythonprogramming language. ## Getting Started -1. **Understand the format**: To understand the TRX file structure and learn Why TRX, please to the [TRX homepage](https://tee-ar-ex.github.io) -2. **Installation** +1. **Understand the format**: To understand the TRX file structure and learn Why TRX, please to the [TRX homepage](https://tee-ar-ex.github.io). +2. **Installation** To install the library, follow the instructions in the {doc}`installation` documentation page. 3. **Learn by example**: Follow our {doc}`auto_examples/index` to learn how to read, write, and manipulate TRX files 4. **Use the CLI tools**: Check out the {doc}`scripts` documentation for command-line operations From 291b9754e9fb47267f7f1c2f889cc2f5439ac783 Mon Sep 17 00:00:00 2001 From: Ariel Rokem Date: Wed, 2 Sep 2026 09:06:11 -0400 Subject: [PATCH 4/5] Include installation page in a toctree. --- docs/source/index.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/source/index.md b/docs/source/index.md index de7b1624..9f123e92 100644 --- a/docs/source/index.md +++ b/docs/source/index.md @@ -13,6 +13,7 @@ tractography in the Pythonprogramming language. ```{toctree} :maxdepth: 2 +installation scripts dev autoapi/index From 56b79d19df285d41bf11cbbb36d2f6ea1bc04824 Mon Sep 17 00:00:00 2001 From: Ariel Rokem Date: Wed, 2 Sep 2026 09:56:19 -0400 Subject: [PATCH 5/5] Fixes typo. --- docs/source/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/index.md b/docs/source/index.md index 9f123e92..bbe9ad39 100644 --- a/docs/source/index.md +++ b/docs/source/index.md @@ -5,7 +5,7 @@ tractography in the Pythonprogramming language. ## Getting Started -1. **Understand the format**: To understand the TRX file structure and learn Why TRX, please to the [TRX homepage](https://tee-ar-ex.github.io). +1. **Understand the format**: To understand the TRX file structure and learn Why TRX, please refer to the [TRX homepage](https://tee-ar-ex.github.io). 2. **Installation** To install the library, follow the instructions in the {doc}`installation` documentation page. 3. **Learn by example**: Follow our {doc}`auto_examples/index` to learn how to read, write, and manipulate TRX files 4. **Use the CLI tools**: Check out the {doc}`scripts` documentation for command-line operations