1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
|
# trx-python
[](https://github.com/tee-ar-ex/trx-python/actions/workflows/test.yml)
[](https://github.com/tee-ar-ex/trx-python/actions/workflows/codeformat.yml)
[](https://codecov.io/gh/tee-ar-ex/trx-python)
[](https://badge.fury.io/py/trx-python)
A Python implementation of the TRX file format for tractography data.
For details, please visit the [documentation](https://tee-ar-ex.github.io/trx-python/).
## Installation
### From PyPI
```bash
pip install trx-python
```
### From Source
```bash
git clone https://github.com/tee-ar-ex/trx-python.git
cd trx-python
pip install .
```
## Quick Start
### Loading and Saving Tractograms
```python
from trx.io import load, save
# Load a tractogram (supports .trx, .trk, .tck, .vtk, .fib, .dpy)
trx = load("tractogram.trx")
# Save to a different format
save(trx, "output.trk")
```
### Command-Line Interface
TRX-Python provides a unified CLI (`trx`) for common operations:
```bash
# Show all available commands
trx --help
# Display TRX file information (header, groups, data keys, archive contents)
trx info data.trx
# Convert between formats
trx convert input.trk output.trx
# Concatenate tractograms
trx concatenate tract1.trx tract2.trx merged.trx
# Validate a TRX file
trx validate data.trx
```
Individual commands are also available for backward compatibility:
```bash
trx_info data.trx
trx_convert_tractogram input.trk output.trx
trx_concatenate_tractograms tract1.trx tract2.trx merged.trx
trx_validate data.trx
```
## Development
We use [spin](https://github.com/scientific-python/spin) for development workflow.
### First-Time Setup
```bash
# Clone the repository (or your fork)
git clone https://github.com/tee-ar-ex/trx-python.git
cd trx-python
# Install with all dependencies
pip install -e ".[all]"
# Set up development environment (fetches upstream tags)
spin setup
```
### Common Commands
```bash
spin setup # Set up development environment
spin install # Install in editable mode
spin test # Run all tests
spin test -m memmap # Run tests matching pattern
spin lint # Run linting (ruff)
spin lint --fix # Auto-fix linting issues
spin docs # Build documentation
spin clean # Clean temporary files
```
Run `spin` without arguments to see all available commands.
### Code Quality
We use [ruff](https://docs.astral.sh/ruff/) for linting and formatting:
```bash
# Check for issues
spin lint
# Auto-fix issues
spin lint --fix
# Format code
ruff format .
```
### Pre-commit Hooks
```bash
# Install hooks
pre-commit install
# Run on all files
pre-commit run --all-files
```
## Temporary Directory
The TRX file format uses memory-mapped files to limit RAM usage. When dealing with large files, several gigabytes may be required on disk.
By default, temporary files are stored in:
- Linux/macOS: `/tmp`
- Windows: `C:\WINDOWS\Temp`
To change the directory:
```bash
# Use a specific directory (must exist)
export TRX_TMPDIR=/path/to/tmp
# Use current working directory
export TRX_TMPDIR=use_working_dir
```
Temporary folders are automatically cleaned, but if the code crashes unexpectedly, ensure folders are deleted manually.
## Troubleshooting
If the `trx` command is not working as expected, run `trx --debug` to print diagnostic information about the Python interpreter, package location, and whether all required and optional dependencies are installed.
## Documentation
Full documentation is available at https://tee-ar-ex.github.io/trx-python/
To build locally:
```bash
spin docs --open
```
## Contributing
We welcome contributions! Please see our [Contributing Guide](https://tee-ar-ex.github.io/trx-python/contributing.html) for details.
## License
BSD License - see [LICENSE](LICENSE) for details.
|
