USAGE:(1)

✨ NAME ✨

okay so bestie, welcome to USAGE:(1) 💖 — this is the manual page for usage: tff_generate_trx_from_scratch [-h] [--positions POSITIONS]. Yeah the name is a whole vibe, it's literally a usage string wearing a manpage as a little outfit. We move.

---

🌸 DESCRIPTION 🌸

Here's the synopsis, no cap, every flag present and accounted for:

usage: tff_generate_trx_from_scratch [-h] [--positions POSITIONS]
       [--offsets OFFSETS] [--positions_csv POSITIONS]
       [--space {RASMM,VOXMM,VOX}]
       [--origin {NIFTI,TRACKVIS}]
       [--positions_dtype {float16,float32,float64}]
       [--offsets_dtype {uint32,uint64}]
       [--dpv FILE DTYPE] [--dps FILE DTYPE]
       [--groups FILE DTYPE] [--dpg GROUP FILE DTYPE]
       [--verify_invalid] [-f] reference OUT_TRACTOGRAM

So what does it do? It generates a TRX file out of a whole lil collection of CSV, TXT or NPY files 🎀 — and you do that by individually specifying positions, offsets, data_per_vertex, data_per_streamlines, groups and data_per_group. And every single file has to have its data type specified by you, the user. No autodetection fairy is coming to save you, bestie, you're the main character here 👑

A reference file must be provided (NIFTI, okay?), and the option --verify_invalid will remove invalid streamlines — meaning the ones hanging outside of the bounding box in VOX space. Rude of them but okay. 🚪

⚠️ real talk: All dimensions (nbr_vertices and nbr_streamlines) and groups/dpg must match. Otherwise the script will (likely) crash. Not "might get a lil weird" — crash. The "(likely)" is doing so much heavy lifting there it's practically a gym influencer. 💀

Every instance of --dps, --dpv, --groups requires 2 arguments (FILE, DTYPE). --dpg requires 3 arguments (GROUP, FILE, DTYPE). And the choice of DTYPE are:

• (u)int8, (u)int16, (u)int32, (u)int64
• float16, float32, float64
• bool

---

🦋 Example command 🦋

She's long, she's gorgeous, she ate:

tff_generate_trx_from_scratch.py fa.nii.gz generated.trx -f
    --positions test_npy/positions.npy
    --positions_dtype float16
    --offsets test_npy/offsets.npy
    --offsets_dtype uint32
    --dpv test_npy/dpv_cx.npy uint8
    --dpv test_npy/dpv_cy.npy uint8
    --dpv test_npy/dpv_cz.npy uint8
    --dps test_npy/dps_algo.npy uint8
    --dps test_npy/dps_cw.npy float64
    --groups test_npy/g_AF_L.npy int32
    --groups test_npy/g_AF_R.npy int32
    --dpg g_AF_L test_npy/dpg_AF_L_mean_fa.npy float32
    --dpg g_AF_R test_npy/dpg_AF_R_mean_fa.npy float32
    --dpg g_AF_L test_npy/dpg_AF_L_volume.npy float32

---

👑 POSITIONAL ARGUMENTS 👑

These two are mandatory, they're the moment, they're non-negotiable:

• reference — Reference anatomy for tck/vtk/fib/dpy file support (.nii or .nii.gz). Basically the anatomical blueprint the whole thing gets aligned to 🧠
• OUT_TRACTOGRAM — Output filename. Format must be one of trk, tck, vtk, fib, dpy, trx. Pick your fighter, but pick one that's on the list. No freestyling 💅

---

💅 OPTIONS 💅

• -h, --help — show this help message and exit. The classic. The icon. The "I got lost and I'm not ashamed" button 🫶
• --verify_invalid — Verify that the positions are all valid. None outside of the bounding box in VOX space. Requires Dipy (due to use of SFT). She's thorough and she needs her dependency, respect her 🌈
• -f — Force overwriting of the output files. Careful babe, this is the "yes I really mean it, delete the old one" flag. She does not ask twice, she just overwrites. 🔥

---

🦋 POSITIONS OPTIONS 🦋

• --positions POSITIONS — Binary file containing the streamlines coordinates. Must be Nx3 (.npy) ✨
• --offsets OFFSETS — Binary file containing the streamlines offsets (.npy) 📍
• --positions_csv POSITIONS — CSV file containing the streamlines coordinates. Rows for each streamlines organized as x1,y1,z1, x2,y2,z2,...,xN,yN,zN 🎀
• --space {RASMM,VOXMM,VOX} — Space in which the coordinates are declared. [RASMM] is the default. Non-default option requires Dipy 🌌
• --origin {NIFTI,TRACKVIS} — Origin in which the coordinates are declared. [NIFTI] is the default. Non-default option requires Dipy 🧭

---

🍓 DATA TYPE OPTIONS 🍓

• --positions_dtype {float16,float32,float64} — Specify the datatype for positions for trx. [float32] is the default 💖
• --offsets_dtype {uint32,uint64} — Specify the datatype for offsets for trx. [uint64] is the default 💖

---

💜 STREAMLINES METADATA OPTIONS 💜

• --dpv FILE DTYPE — Binary file containing data_per_vertex. Must have NB_VERTICES as first dimension (.npy) 🦋
• --dps FILE DTYPE — Binary file containing data_per_vertex. Must have NB_STREAMLINES as first dimension (.npy) 🦋

ngl the original text says data_per_vertex here even though this flag is the data_per_streamlines one — I'm just the messenger, I report the lore exactly as it was handed to me 🙈

• --groups FILE DTYPE — Binary file containing a sparse group (indices). Indices should be lower than NB_STREAMLINES (.npy) 🌸
• --dpg GROUP FILE DTYPE — Binary file containing data_per_group. Must have (1,) as first dimension (.npy) 🌸

---

💀 AND THEN THE PAGE JUST... DOES THIS 💀

There's a second, lonely little usage fragment hanging out in there, exactly like this:

[--offsets OFFSETS]
       [--positions_csv POSITIONS] [--space {RASMM,VOXMM,VOX}] [--origin
       {NIFTI,TRACKVIS}] [--positions_dtype {float16,float32,float64}]
       [--offsets_dtype {uint32,uint64}] [--dpv FILE DTYPE] [--dps FILE
       DTYPE] [--groups FILE DTYPE] [--dpg GROUP FILE DTYPE]
       [--verify_invalid] [-f] reference OUT_TRACTOGRAM

And then, because the vibes weren't chaotic enough, the error message is just sitting there at the bottom:

tff_generate_trx_from_scratch: error: the following arguments are required: reference, OUT_TRACTOGRAM

Translation: if you forget reference or OUT_TRACTOGRAM, she's gonna yell at you. Just give her both, it's not that deep 💖

---

and that's the whole page bestie, you ate that reading, go generate some tractograms ✨

Sign-off, as is tradition: this page is usage: tff_generate_trx_from_..., dated September 2025, and it answers to the name USAGE:(1). 🎀💅🦋