tardis.visualization.plot_util module

Utility functions to be used in plotting.

tardis.visualization.plot_util.axis_label_in_latex(label_text, unit, only_text=True)

Get axis label for plotly plots that can show units in latex.

Parameters:

label_textstr

Text to show on label, may be expressed in latex

unitastropy.units

Unit of the label which needs to be expressed in latex

only_textbool

If label_text is expressed purely in text (i.e. without using latex) or not. Default value is True

Returns:

str

Latex string for label renderable by plotly

tardis.visualization.plot_util.create_wavelength_mask(packet_data, packets_mode, packet_wvl_range, df_key, column_name)

Create mask for packets based on wavelength range.

Parameters:

packets_modestr

‘virtual’ or ‘real’ packets mode

packet_wvl_rangeastropy.Quantity or None

Wavelength range to filter packets

df_keystr

Key for the dataframe in packet_data (‘packets_df’ or ‘packets_df_line_interaction’)

column_namestr

Column name to filter on (‘nus’ or ‘last_line_interaction_in_nu’)

Returns:

np.array

Boolean mask for packets in the specified wavelength range

tardis.visualization.plot_util.expand_species_list(species_list)

Expand a species list into a fully-resolved list of species strings.

This includes: - Expanding ion ranges like ‘Si I - V’ into [‘Si I’, ‘Si II’, …, ‘Si V’] - Keeping individual ions or elements as-is

Parameters:

species_listlist of str

List of species requested by the user.

Returns:

full_species_listlist of str

Expanded list of species strings in ‘Element Ion’ format.

Raises:

ValueError

If any digit is found in the input (species must use Roman numerals).

tardis.visualization.plot_util.extract_and_process_packet_data(simulation, packets_mode)

Extract and process packet data from the simulation object.

This includes converting the packet data into a DataFrame and appending processed line interaction information.

Parameters:

simulationtardis.simulation.BaseSimulation

Full TARDIS simulation object containing transport state, plasma, and atomic data.

packets_modestr

Type of packets to extract: - ‘virtual’: Use virtual packet tracker. - ‘real’: Use emitted real packets.

Returns:

dict

Dictionary containing raw packet data, the full DataFrame packets_df, and a filtered packets_df_line_interaction with line interaction info.

tardis.visualization.plot_util.extract_and_process_packet_data_hdf(hdf, packets_mode)

Extract and process packet data from an HDF file.

This function retrieves packet data from an HDF file and processes it based on the specified packet mode (either “virtual” or “real”). The extracted data is organized into a dictionary and further processed to include line interaction information.

Parameters:

hdfh5py.File or dict-like

The HDF file object containing the simulation data.

packets_modestr

The mode of packets to process. Can be “virtual” for virtual packets or any other value for real packets.

Returns:

dict

A dictionary containing the processed packet data.

Raises:

KeyError

If required keys are missing in the HDF file.

ValueError

If an invalid packets_mode is provided.

tardis.visualization.plot_util.extract_spectrum_data_hdf(hdf, packets_mode)

Extract spectrum data from HDF5.

Parameters:

hdfh5py.File

Open HDF5 file containing simulation output.

packets_modestr

Packet mode to extract spectrum data for (e.g., ‘real’, ‘virtual’).

Returns:

dict

Dictionary containing: - “spectrum_delta_frequency” : Quantity

Frequency bin width in Hz.

• “spectrum_frequency_bins”Quantity

  Frequency bin edges in Hz.

• “spectrum_luminosity_density_lambda”Quantity

  Luminosity density in erg / s / Å.

• “spectrum_wavelength”Quantity

  Wavelength values in Å.

tardis.visualization.plot_util.get_hex_color_strings(length, name='jet')

Generate a list of hex color strings from a discrete colormap.

Parameters:

lengthint

Number of discrete colors to extract from the colormap.

namestr, optional

Name of the Matplotlib colormap to use (default is ‘jet’).

Returns:

list of str

List of hex color strings ([‘#ff0000’, ‘#00ff00’, ‘#0000ff’])

tardis.visualization.plot_util.get_mid_point_idx(arr)

Get index of the middle point of a sorted array (ascending or descending).

The values in array may not be evenly distributed so it picks the middle point not by index but by their values.

Parameters:

arrnp.array

Returns:

int

tardis.visualization.plot_util.get_spectrum_data(packets_mode, sim)

Get spectrum data from simulation based on mode.

Parameters:

packets_modestr

Packet mode to extract spectrum data for (e.g., ‘real’, ‘virtual’).

simSimulation

Simulation object containing the spectrum solver and data.

Returns:

dict

Dictionary containing: - “spectrum_delta_frequency” : Quantity

Frequency bin width in Hz.

• “spectrum_frequency_bins”Quantity

  Frequency bin edges in Hz.

• “spectrum_luminosity_density_lambda”Quantity

  Luminosity density in erg / s / Å.

• “spectrum_wavelength”Quantity

  Wavelength values in Å.

tardis.visualization.plot_util.parse_species_list_util(species_list)

Parse user-requested species list and create list of species IDs to be used.

The function interprets element or ion names and ion ranges, converting them into (Z, ion) tuples, where Z is the atomic number and ion is the zero-based ionization stage.

Parameters:

species_listlist of str

List of species that the user wants to show in distinct colors. Species can be given as: - An ion (e.g. ‘Fe II’) - An element (e.g. ‘Ca’) - A range of ions (e.g. ‘Si I - V’) - A combination of the above (e.g. [‘Si II’, ‘Fe I - III’, ‘Ca’])

Returns:

species_mapped_resultdict

Dictionary mapping (Z, ion) to lists of (Z, ion) tuples.

species_list_resultlist of tuple

Flattened list of all (Z, ion) tuples to be used.

elements_with_shared_colorlist of int

Atomic numbers of elements that should be grouped by color.

full_species_listlist of str

Expanded list of user-requested species in string format.

Examples

‘Fe II’ -> [(26, 1)] ‘Ca’ -> [(20, 0), (20, 1), …, (20, 19)] ‘Si I-V’ -> [(14, 0), (14, 1), (14, 2), (14, 3), (14, 4)]

tardis.visualization.plot_util.process_line_interactions(packet_data, lines_df)

Add line interaction metadata to the packet DataFrame.

Filters packets that experienced a line interaction and computes: - Atomic number of the last interaction (out). - Species ID (Z * 100 + ion number).

Parameters:

packet_datadict

Dictionary containing a ‘packets_df’ DataFrame.

lines_dfpandas.DataFrame

DataFrame with ‘atomic_number’ and ‘ion_number’ indexed by line ID.

tardis.visualization.plot_util.to_rgb255_string(color_tuple)

Convert a matplotlib RGBA tuple to a generic RGB 255 string.

Parameters:

color_tupletuple

Matplotlib RGBA tuple of float values in closed interval [0, 1]

Returns:

str

RGB string of format rgb(r,g,b) where r,g,b are integers between 0 and 255 (both inclusive)