.. DO NOT EDIT. .. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY. .. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE: .. "auto_examples/plot_read_write_trx.py" .. LINE NUMBERS ARE GIVEN BELOW. .. only:: html .. note:: :class: sphx-glr-download-link-note :ref:`Go to the end ` to download the full example code. .. rst-class:: sphx-glr-example-title .. _sphx_glr_auto_examples_plot_read_write_trx.py: Reading and Writing TRX Files ============================== This tutorial demonstrates how to read and write TRX files using trx-python. TRX is a tractography file format designed for efficient storage and access of brain fiber tract streamline data. By the end of this tutorial, you will know how to: - Load a TRX file from disk - Inspect the contents of a TRX file - Access streamlines and metadata - Save a TRX file to disk - Create a TRX file from scratch .. GENERATED FROM PYTHON SOURCE LINES 21-26 Loading a TRX file ------------------ Let's start by loading an existing TRX file. First, we need to download some test data. .. GENERATED FROM PYTHON SOURCE LINES 26-43 .. code-block:: Python import os import tempfile from trx.fetcher import fetch_data, get_home, get_testing_files_dict from trx.trx_file_memmap import load, save # Download test data fetch_data(get_testing_files_dict(), keys="gold_standard.zip") trx_home = get_home() trx_path = os.path.join(trx_home, "gold_standard", "gs.trx") # Load the TRX file trx = load(trx_path) print("TRX file loaded successfully!") .. rst-class:: sphx-glr-script-out .. code-block:: none TRX file loaded successfully! .. GENERATED FROM PYTHON SOURCE LINES 44-49 Inspecting TRX file contents ---------------------------- The TrxFile object has several key attributes that you can inspect. Let's look at what's inside our loaded file. .. GENERATED FROM PYTHON SOURCE LINES 49-53 .. code-block:: Python # Print a summary of the TRX file print(trx) .. rst-class:: sphx-glr-script-out .. code-block:: none VOXEL_TO_RASMM: [[3.969615 -0.245576 0.007596 12.082228] [0.491151 1.969615 -0.122788 22.164438] [0.030384 0.245576 0.992404 37.917774] [0.000000 0.000000 0.000000 1.000000]] DIMENSIONS: [ 5 10 20] VOX_SIZES: [4.00 2.00 1.00] VOX_ORDER: RAS streamline_count: 13 vertex_count: 104 data_per_vertex keys: ['color_y', 'color_z', 'color_x'] data_per_streamline keys: ['random_coord'] groups keys: [] copy_safe: True .. GENERATED FROM PYTHON SOURCE LINES 54-55 The header contains essential metadata about the tractogram: .. GENERATED FROM PYTHON SOURCE LINES 55-62 .. code-block:: Python print("Header information:") print(f" Number of streamlines: {trx.header['NB_STREAMLINES']}") print(f" Number of vertices: {trx.header['NB_VERTICES']}") print(f" Image dimensions: {trx.header['DIMENSIONS']}") print(f" Voxel to RASMM affine:\n{trx.header['VOXEL_TO_RASMM']}") .. rst-class:: sphx-glr-script-out .. code-block:: none Header information: Number of streamlines: 13 Number of vertices: 104 Image dimensions: [ 5 10 20] Voxel to RASMM affine: [[ 3.9696155e+00 -2.4557561e-01 7.5961235e-03 1.2082228e+01] [ 4.9115121e-01 1.9696155e+00 -1.2278780e-01 2.2164438e+01] [ 3.0384494e-02 2.4557561e-01 9.9240386e-01 3.7917774e+01] [ 0.0000000e+00 0.0000000e+00 0.0000000e+00 1.0000000e+00]] .. GENERATED FROM PYTHON SOURCE LINES 63-68 Accessing streamlines --------------------- Streamlines are the core data in a TRX file. Each streamline is a sequence of 3D points representing a fiber tract in the brain. .. GENERATED FROM PYTHON SOURCE LINES 68-77 .. code-block:: Python print(f"Number of streamlines: {len(trx)}") print(f"Total number of vertices: {len(trx.streamlines._data)}") # Access the first streamline first_streamline = trx.streamlines[0] print(f"\nFirst streamline has {len(first_streamline)} points") print(f"First 3 points of the first streamline:\n{first_streamline[:3]}") .. rst-class:: sphx-glr-script-out .. code-block:: none Number of streamlines: 13 Total number of vertices: 104 First streamline has 8 points First 3 points of the first streamline: [[11.149319 21.579943 37.600685] [11.153116 21.518549 38.096886] [11.02653 22.56475 37.723473]] .. GENERATED FROM PYTHON SOURCE LINES 78-82 Accessing metadata ------------------ TRX files can contain additional data per vertex (dpv) and per streamline (dps). .. GENERATED FROM PYTHON SOURCE LINES 82-87 .. code-block:: Python print("Data per vertex (dpv) keys:", list(trx.data_per_vertex.keys())) print("Data per streamline (dps) keys:", list(trx.data_per_streamline.keys())) print("Groups:", list(trx.groups.keys())) .. rst-class:: sphx-glr-script-out .. code-block:: none Data per vertex (dpv) keys: ['color_y', 'color_z', 'color_x'] Data per streamline (dps) keys: ['random_coord'] Groups: [] .. GENERATED FROM PYTHON SOURCE LINES 88-92 Selecting a subset of streamlines --------------------------------- You can easily select a subset of streamlines using indices or slicing. .. GENERATED FROM PYTHON SOURCE LINES 92-103 .. code-block:: Python # Select first 5 streamlines subset = trx[:5] print(f"Subset has {len(subset)} streamlines") # Select specific streamlines by indices (ensure indices are valid) max_idx = len(trx) - 1 indices = [0, min(2, max_idx), min(5, max_idx)] selected = trx.select(indices) print(f"Selected {len(selected)} streamlines") .. rst-class:: sphx-glr-script-out .. code-block:: none Subset has 5 streamlines WARNING:root:Keeping dpg despite affecting the group items. Selected 3 streamlines .. GENERATED FROM PYTHON SOURCE LINES 104-109 Saving a TRX file ----------------- You can save a TRX file back to disk. The file can be saved as a compressed or uncompressed zip archive, or as a directory. .. GENERATED FROM PYTHON SOURCE LINES 109-121 .. code-block:: Python with tempfile.TemporaryDirectory() as tmpdir: # Save as TRX file (zip archive) output_path = os.path.join(tmpdir, "output.trx") save(trx, output_path) print(f"Saved TRX file to: {output_path}") print(f"File size: {os.path.getsize(output_path)} bytes") # Reload to verify reloaded = load(output_path) print(f"Reloaded TRX has {len(reloaded)} streamlines") .. rst-class:: sphx-glr-script-out .. code-block:: none Saved TRX file to: /tmp/tmpyoezlpp6/output.trx File size: 3881 bytes Reloaded TRX has 13 streamlines .. GENERATED FROM PYTHON SOURCE LINES 122-127 Creating a TRX file from an existing one ---------------------------------------- A common workflow is to create a new TRX file based on an existing one, preserving the spatial reference information. .. GENERATED FROM PYTHON SOURCE LINES 127-134 .. code-block:: Python # Create a deepcopy of the loaded TRX file trx_copy = trx.deepcopy() print(f"Created copy with {len(trx_copy)} streamlines") print(f"Header preserved: DIMENSIONS = {trx_copy.header['DIMENSIONS']}") .. rst-class:: sphx-glr-script-out .. code-block:: none Created copy with 13 streamlines Header preserved: DIMENSIONS = [ 5 10 20] .. GENERATED FROM PYTHON SOURCE LINES 135-149 Summary ------- In this tutorial, you learned how to: - Load TRX files using ``load()`` - Inspect header information and streamline data - Access data per vertex (dpv) and data per streamline (dps) - Select subsets of streamlines - Save TRX files using ``save()`` - Create copies of TRX files using ``deepcopy()`` The TRX format is designed for memory efficiency through memory-mapping, making it suitable for large tractography datasets. .. rst-class:: sphx-glr-timing **Total running time of the script:** (0 minutes 0.274 seconds) .. _sphx_glr_download_auto_examples_plot_read_write_trx.py: .. only:: html .. container:: sphx-glr-footer sphx-glr-footer-example .. container:: sphx-glr-download sphx-glr-download-jupyter :download:`Download Jupyter notebook: plot_read_write_trx.ipynb ` .. container:: sphx-glr-download sphx-glr-download-python :download:`Download Python source code: plot_read_write_trx.py ` .. container:: sphx-glr-download sphx-glr-download-zip :download:`Download zipped: plot_read_write_trx.zip ` .. only:: html .. rst-class:: sphx-glr-signature `Gallery generated by Sphinx-Gallery `_