.. DO NOT EDIT. .. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY. .. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE: .. "auto_examples/plot_dps_dpv.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_dps_dpv.py: Data Per Vertex and Data Per Streamline ======================================== This tutorial demonstrates how to work with metadata in TRX files. TRX supports two types of metadata: - **Data Per Vertex (dpv)**: Information attached to each point along streamlines - **Data Per Streamline (dps)**: Information attached to entire streamlines By the end of this tutorial, you will know how to: - Access dpv and dps data in a TRX file - Understand the data shapes and organization - Use metadata for filtering and analysis .. GENERATED FROM PYTHON SOURCE LINES 21-35 Understanding DPV and DPS ------------------------- **Data Per Vertex (dpv):** - Attached to each individual point (vertex) in all streamlines - Shape: (NB_VERTICES, 1) for scalar data or (NB_VERTICES, N) for vector data - Common uses: FA values at each point, RGB colors, local orientations **Data Per Streamline (dps):** - Attached to entire streamlines (one value per streamline) - Shape: (NB_STREAMLINES, 1) for scalar data or (NB_STREAMLINES, N) for vector data - Common uses: bundle ID, mean FA, streamline length, tracking algorithm ID .. GENERATED FROM PYTHON SOURCE LINES 37-41 Loading a TRX file with metadata -------------------------------- Let's load a TRX file and explore its metadata. .. GENERATED FROM PYTHON SOURCE LINES 41-60 .. code-block:: Python import os import numpy as np from trx.fetcher import fetch_data, get_home, get_testing_files_dict from trx.trx_file_memmap import load # 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(f"Loaded TRX with {len(trx)} streamlines") print(f"Total vertices: {trx.header['NB_VERTICES']}") .. rst-class:: sphx-glr-script-out .. code-block:: none Loaded TRX with 13 streamlines Total vertices: 104 .. GENERATED FROM PYTHON SOURCE LINES 61-65 Exploring Data Per Vertex (dpv) ------------------------------- Let's see what dpv data is available. .. GENERATED FROM PYTHON SOURCE LINES 65-76 .. code-block:: Python print("Data Per Vertex keys:", list(trx.data_per_vertex.keys())) # Examine each dpv field for key in trx.data_per_vertex: data = trx.data_per_vertex[key] print(f"\n {key}:") print(f" Shape: {data._data.shape}") print(f" Dtype: {data._data.dtype}") print(f" Sample values: {data._data[:3].flatten()}") .. rst-class:: sphx-glr-script-out .. code-block:: none Data Per Vertex keys: ['color_y', 'color_z', 'color_x'] color_y: Shape: (104, 1) Dtype: float32 Sample values: [20. 20. 20.] color_z: Shape: (104, 1) Dtype: float32 Sample values: [60. 60. 60.] color_x: Shape: (104, 1) Dtype: float32 Sample values: [220. 220. 220.] .. GENERATED FROM PYTHON SOURCE LINES 77-82 Accessing dpv for a specific streamline --------------------------------------- The dpv data is organized to match the streamlines. You can access the dpv values for a specific streamline using the same indices. .. GENERATED FROM PYTHON SOURCE LINES 82-93 .. code-block:: Python if len(trx.data_per_vertex) > 0: first_dpv_key = list(trx.data_per_vertex.keys())[0] dpv_data = trx.data_per_vertex[first_dpv_key] # Get dpv values for the first streamline first_streamline_dpv = dpv_data[0] print(f"DPV '{first_dpv_key}' for first streamline:") print(f" Shape: {first_streamline_dpv.shape}") print(f" Values: {first_streamline_dpv.flatten()}") .. rst-class:: sphx-glr-script-out .. code-block:: none DPV 'color_y' for first streamline: Shape: (8, 1) Values: [20. 20. 20. 20. 20. 20. 20. 20.] .. GENERATED FROM PYTHON SOURCE LINES 94-98 Exploring Data Per Streamline (dps) ----------------------------------- Now let's examine the dps data. .. GENERATED FROM PYTHON SOURCE LINES 98-109 .. code-block:: Python print("Data Per Streamline keys:", list(trx.data_per_streamline.keys())) # Examine each dps field for key in trx.data_per_streamline: data = trx.data_per_streamline[key] print(f"\n {key}:") print(f" Shape: {data.shape}") print(f" Dtype: {data.dtype}") print(f" First 5 values: {data[:5].flatten()}") .. rst-class:: sphx-glr-script-out .. code-block:: none Data Per Streamline keys: ['random_coord'] random_coord: Shape: (13, 3) Dtype: float32 First 5 values: [ 7. 1. 5. 2. 4. 5. 9. 8. 10. 4. 6. 3. 6. 3. 5.] .. GENERATED FROM PYTHON SOURCE LINES 110-115 DPS for filtering streamlines ----------------------------- A common use case is filtering streamlines based on dps values. For example, selecting streamlines with high FA values. .. GENERATED FROM PYTHON SOURCE LINES 115-128 .. code-block:: Python if len(trx.data_per_streamline) > 0: # Use the first dps key for demonstration first_dps_key = list(trx.data_per_streamline.keys())[0] dps_data = trx.data_per_streamline[first_dps_key] # Calculate some statistics print(f"\nStatistics for '{first_dps_key}':") print(f" Min: {np.min(dps_data):.4f}") print(f" Max: {np.max(dps_data):.4f}") print(f" Mean: {np.mean(dps_data):.4f}") print(f" Std: {np.std(dps_data):.4f}") .. rst-class:: sphx-glr-script-out .. code-block:: none Statistics for 'random_coord': Min: 0.0000 Max: 10.0000 Mean: 5.3077 Std: 2.6617 .. GENERATED FROM PYTHON SOURCE LINES 129-148 File structure for dpv and dps ------------------------------ In the TRX format, dpv and dps are stored in separate directories: .. code-block:: text my_tractogram.trx/ |-- dpv/ | |-- fa.float16 # FA values per vertex | |-- colors.3.uint8 # RGB colors (3 values per vertex) | +-- curvature.float32 # Curvature per vertex |-- dps/ | |-- bundle_id.uint8 # Bundle assignment per streamline | |-- length.uint16 # Length per streamline | +-- mean_fa.float32 # Mean FA per streamline +-- ... The filename format is: ``name.dtype`` or ``name.dimension.dtype`` .. GENERATED FROM PYTHON SOURCE LINES 150-155 Working with multi-dimensional data ----------------------------------- Both dpv and dps can have multiple dimensions. For example, RGB colors have 3 values per vertex. .. GENERATED FROM PYTHON SOURCE LINES 155-170 .. code-block:: Python print("\nDemonstrating multi-dimensional data:") # Check for any multi-dimensional dpv for key in trx.data_per_vertex: data = trx.data_per_vertex[key] if len(data._data.shape) > 1 and data._data.shape[1] > 1: print(f" {key}: {data._data.shape[1]}D data per vertex") # Check for any multi-dimensional dps for key in trx.data_per_streamline: data = trx.data_per_streamline[key] if len(data.shape) > 1 and data.shape[1] > 1: print(f" {key}: {data.shape[1]}D data per streamline") .. rst-class:: sphx-glr-script-out .. code-block:: none Demonstrating multi-dimensional data: random_coord: 3D data per streamline .. GENERATED FROM PYTHON SOURCE LINES 171-177 Relationship between dpv and streamlines ---------------------------------------- It's important to understand how dpv data maps to individual streamlines. Each streamline's dpv values can be accessed using the streamline's vertex indices. .. GENERATED FROM PYTHON SOURCE LINES 177-189 .. code-block:: Python # Get vertex counts for first few streamlines print("\nVertex distribution for first 5 streamlines:") for i in range(min(5, len(trx))): streamline = trx.streamlines[i] print(f" Streamline {i}: {len(streamline)} vertices") # Total vertices should match total_from_streamlines = sum(len(trx.streamlines[i]) for i in range(len(trx))) print(f"\nTotal vertices from streamlines: {total_from_streamlines}") print(f"Total vertices in header: {trx.header['NB_VERTICES']}") .. rst-class:: sphx-glr-script-out .. code-block:: none Vertex distribution for first 5 streamlines: Streamline 0: 8 vertices Streamline 1: 8 vertices Streamline 2: 8 vertices Streamline 3: 8 vertices Streamline 4: 8 vertices Total vertices from streamlines: 104 Total vertices in header: 104 .. GENERATED FROM PYTHON SOURCE LINES 190-203 Summary ------- In this tutorial, you learned how to: - Access dpv data using ``trx.data_per_vertex[key]`` - Access dps data using ``trx.data_per_streamline[key]`` - Understand the shape conventions for scalar and vector data - Use metadata for statistical analysis - Understand the file structure for dpv and dps The TRX format's metadata system is designed for flexibility, allowing you to attach any kind of information to vertices or streamlines. .. rst-class:: sphx-glr-timing **Total running time of the script:** (0 minutes 0.009 seconds) .. _sphx_glr_download_auto_examples_plot_dps_dpv.py: .. only:: html .. container:: sphx-glr-footer sphx-glr-footer-example .. container:: sphx-glr-download sphx-glr-download-jupyter :download:`Download Jupyter notebook: plot_dps_dpv.ipynb ` .. container:: sphx-glr-download sphx-glr-download-python :download:`Download Python source code: plot_dps_dpv.py ` .. container:: sphx-glr-download sphx-glr-download-zip :download:`Download zipped: plot_dps_dpv.zip ` .. only:: html .. rst-class:: sphx-glr-signature `Gallery generated by Sphinx-Gallery `_