KAHIBARO
Text-Based Output
Table of Contents
CSV
Text based output is often the most convenient way to quickly inspect results and to connect GATE with external tools. Among text formats, CSV is the simplest option and is widely supported.
In GATE, several actors and digitizers can write their results directly to CSV files. For example, a singles actor or a dose actor can be configured so that each event, hit, or voxel is written as a row in a table, with columns for quantities such as energy, position, and time. The exact configuration of actors is discussed in earlier chapters, so here the focus remains on how to think about CSV output and how to use it effectively once it has been produced.
A typical CSV file contains a header row followed by data rows. The header defines the column names. Columns often correspond to physical quantities, for example energy in keV, positions in mm, and times in ns. When you configure actors, it is important to make sure that the meaning and units of each column are well documented. This can be done by choosing descriptive variable names in the GATE configuration and by keeping a short text description in a separate README file associated with the simulation.
A simple CSV layout for singles might look like this:
| column name | Description | Example unit |
|---|---|---|
| eventID | Event index | dimensionless |
| time | Detection time | ns |
| energy | Deposited or detected energy | keV or MeV |
| px | Detector x position | mm |
| py | Detector y position | mm |
| pz | Detector z position | mm |
| detID | Detector or crystal identifier | dimensionless |
CSV is line oriented. This makes it easy to inspect small files in a text editor or spreadsheet software. However, it is not compressed by default and stores numerical values as text instead of binary floating point numbers. Large simulations can therefore produce very large CSV files and reading them may become slow and memory intensive.
To handle CSV output efficiently, it is common to process files in chunks. In Python, for instance, one can read the file in smaller parts, compute basic statistics, then discard intermediate arrays to limit memory usage. CSV is also a convenient interchange format if collaborators use different tools, such as R, MATLAB, or Excel.
There are several recommendations that help keep CSV output manageable and unambiguous. First, avoid writing unnecessary columns, especially if they repeat constant values. Second, use a consistent column order and naming convention across simulations so that analysis scripts do not have to change every time. Third, always record the units used for each column, either in the header or in an accompanying text file.
Because text representation can lose some numerical precision, one should be aware that very small differences may appear when CSV data are read back into floating point arrays. For most medical physics applications this is not a practical problem, but it is good to know that text based formats cannot be perfectly lossless for arbitrary floating point values.
Finally, CSV is well suited for summary data, such as reduced lists of events, spectra, or dose statistics. When the full detailed event record is required for millions of events, binary formats such as ROOT or NumPy based formats are usually more suitable. A common workflow is to use GATE to write ROOT files, then convert selected branches or derived quantities into smaller CSV files for quick inspection and sharing.
When configuring CSV output, always verify:
- The meaning and units of each column are clearly defined.
- Only the necessary quantities are written, to avoid excessively large files.
- Column names and ordering are kept consistent across similar simulations.
NumPy-compatible formats
NumPy compatible text formats sit between human readable CSV and binary formats such as .npy and .npz. For beginners, the most important idea is that text files from GATE can be arranged so that they can be loaded directly into NumPy arrays with simple commands, without manual parsing.
NumPy provides functions such as numpy.loadtxt and numpy.genfromtxt that expect a regular tabular layout, similar to CSV. If GATE writes a plain text file where each row has the same number of numerical values, separated by spaces or commas, then NumPy can usually read it directly. In practice, CSV produced by GATE is already NumPy compatible in this sense, as long as the file does not contain irregular lines or non-numeric content in the data section.
When you design text output in GATE with NumPy based analysis in mind, it helps to be explicit about separators and headers. For example, using a single delimiter, such as a comma, for all files simplifies the analysis code. If there is a header row with column names, NumPy can be instructed to skip it, so it does not interfere with the numerical data. This enables a workflow where text output from GATE becomes an immediate input to scientific Python scripts.
From the NumPy perspective, one-dimensional arrays can represent simple lists of values, such as energy deposits per event, while two dimensional arrays are used when each event or voxel corresponds to a row with several attributes. For example, a phase space actor might produce a table where each row contains position coordinates, direction cosines, energy, and weight. Once loaded into NumPy, one can extract columns by index and compute histograms, means, or other statistics.
A typical use case is to convert detailed results into NumPy arrays, then save them in a more compact binary format. NumPy offers the .npy format for a single array and .npz for multiple arrays stored together. These formats are not text based, but it is common to treat text output from GATE as an intermediate step, then convert to binary files to speed up repeated analysis. The advantage is that the original text file remains as an easily inspectable record, while the binary copy accelerates future computations.
Another common pattern is to write text files that separate metadata from numerical tables. For example, the first few lines might contain comments beginning with a special character, describing simulation details, date, and parameter values, followed by regular rows of numbers. NumPy functions can ignore comment lines automatically. This results in a file that is both readable to humans and easy to parse in Python.
The table below summarizes how typical text layouts relate to NumPy loading:
| Text layout type | Example separator | Header row | NumPy loading strategy |
|---|---|---|---|
| Simple CSV | Comma | Yes | Skip header row, use default delimiter |
| Space separated table | Space | No | Direct load, default delimiter |
| Commented header | Any | Comments | Use comment character, skip commented lines |
For large simulations, purely text based workflows can become slow. Reading millions of lines from disk and converting them to floating point numbers is more expensive than reading binary data directly. For this reason, NumPy compatible text formats are especially useful for moderate data volumes, for example when testing configurations, developing analysis scripts, or extracting reduced data for teaching and demonstration.
When precision and performance are critical, it is often better to read ROOT files with dedicated libraries, then export only the necessary subset of data into NumPy arrays. Still, understanding NumPy compatible text formats is a valuable first step because they make the connection between GATE and simple Python analysis tools transparent.
For NumPy compatible text output:
- Use a consistent delimiter (commas or spaces) throughout the file.
- Keep exactly one data row format, with the same number of values per line.
- Place any non numerical information into comment or header lines that NumPy can skip.
Views: 11