Pipeline functions

plotSnapshot(
    simulation_paths::Vector{String},
    request::Dict{Symbol,Vector{String}},
    plot_functions::Vector{<:Function};
    <keyword arguments>
)::Nothing

Generate one figure per snapshot, for one or more simulations.

Some of the features are:

• It can produce scatter plots, line plots, histograms, and heatmaps.
• It can generate an animation of the results.
• It transparently manages units; you only have to indicate the final unit of each axis.

Arguments

• simulation_paths::Vector{String}: Paths to the simulation directories, set in the code variable OutputDir.

• request::Dict{Symbol,Vector{String}}: Dictionary with the shape cell/particle type -> [block, block, ...], where the possible types are the keys of PARTICLE_INDEX, and the possible quantities are the keys of QUANTITIES. Which data blocks are needed depends on the provided functions da_functions.

• plot_functions::Vector{<:Function}: Vector of plotting functions from Makie. This sets the type of plot for each simulation. The supported functions are:

  • scatter! -> Scatter plot.
  • lines! -> Line plot.
  • scatterlines! -> Scatter plot with lines between the markers.
  • hist! -> Histogram.
  • heatmap! -> Heatmap.
  • arrows2d! -> Vector field.
  • barplot! -> Bar plots.
  • band! -> Band plots.
  • errorbars! -> Error bars.

• pf_kwargs::Vector{<:NamedTuple}=[(;)]: Vector of keyword arguments for the functions in plot_functions.

plotSnapshot configuration

• output_path::String=".": Path to the output folder.
• base_filename::String="snapshot": Every file will be named base_filename-XXXoutput_format where XXX is the snapshot number.
• output_format::String=".png": File format for the figure. All formats supported by Makie can be used, namely .pdf, .svg and .png.
• show_progress::Bool=true: If a progress bar will be shown.

Data manipulation options

• slice::IndexType=(:): Slice of the simulation, i.e. which snapshots will be read. It can be an integer (a single snapshot), a vector of integers (several snapshots), an UnitRange (e.g. 5:13), an StepRange (e.g. 5:2:13) or (:) (all snapshots). It works over the longest possible list of snapshots among the simulations (grouped by the number in the file names). Out of bounds indices are ignored.

• filter_function::Function=filterNothing: A function with the signature:

  filter_function(data_dict) -> indices

  where

  • data_dict::Dict: A dictionary with the following shape:

    • :sim_data -> ::Simulation (see Simulation).
    • :snap_data -> ::Snapshot (see Snapshot).
    • :gc_data -> ::GroupCatalog (see GroupCatalog).
    • cell/particle type -> (block -> data of block, block -> data of block, ...).
    • cell/particle type -> (block -> data of block, block -> data of block, ...).
    • cell/particle type -> (block -> data of block, block -> data of block, ...).
    • ...
    • groupcat type -> (block -> data of block, block -> data of block, ...).
    • groupcat type -> (block -> data of block, block -> data of block, ...).
    • groupcat type -> (block -> data of block, block -> data of block, ...).
    • ...

  • indices::Dict: A dictionary with the following shape:

    • cell/particle type -> idxs::IndexType
    • cell/particle type -> idxs::IndexType
    • cell/particle type -> idxs::IndexType
    • ...

• da_functions::Vector{<:Function}=[getNothing]: Vector of data analysis functions. See the required signature and examples in ./src/analysis/data_analysis.jl.

• da_args::Vector{<:Tuple}=[()]: Vector of positional arguments for the data analysis functions.

• da_kwargs::Vector{<:NamedTuple}=[(;)]: Vector of keyword arguments for the data analysis functions.

• post_processing::Function=getNothing: Post processing function. See the required signature and examples in ./src/plotting/post_processing.jl.

• pp_args::Tuple=(): Positional arguments for the post processing function.

• pp_kwargs::NamedTuple=(;): Keyword arguments for the post processing function.

• transform_box::Bool=false: If a translation and rotation (in that order) will be applied to the simulation box, affecting the positions and velocities of all the cells and particles. If active, it is applied AFTER the filter_function.

• translation::Union{Symbol,NTuple{2,Int},Int}=:zero: Type of translation (only relevant if transform_box = true). The options are:

  • :zero -> No translation is applied.
  • :global_cm -> Sets the center of mass of the whole system (after filtering) as the new origin.
  • :{component} -> Sets the center of mass of the given component (e.g. :stars, :gas, :halo, etc, after filtering) as the new origin. It can be any of the keys of PARTICLE_INDEX.
  • (halo_idx, subhalo_rel_idx) -> Sets the position of the potential minimum for the subhalo_rel_idx::Int subhalo (of the halo_idx::Int halo), as the new origin.
  • (halo_idx, 0) -> Sets the center of mass of the halo_idx::Int halo, as the new origin.
  • subhalo_abs_idx -> Sets the center of mass of the subhalo_abs_idx::Int as the new origin.

• rotation::Union{Symbol,NTuple{2,Int},Int}=:zero: Type of rotation (only relevant if transform_box = true). The options are:

  • :zero -> No rotation is applied.
  • :global_am -> Sets the angular momentum of the whole system as the new z axis.
  • :stellar_am -> Sets the stellar angular momentum as the new z axis.
  • :stellar_pa -> Sets the stellar principal axis as the new coordinate system.
  • :stellar_subhalo_pa -> Sets the principal axis of the stars in the main subhalo as the new coordinate system.
  • (halo_idx, subhalo_rel_idx) -> Sets the principal axis of the stars in subhalo_rel_idx::Int subhalo (of the halo_idx::Int halo), as the new coordinate system.
  • (halo_idx, 0) -> Sets the principal axis of the stars in the halo_idx::Int halo, as the new coordinate system.
  • subhalo_abs_idx -> Sets the principal axis of the stars in the subhalo_abs_idx::Int subhalo as the new coordinate system.

• smooth::Int=0: The result of da_functions will be smoothed out using smooth bins. Set it to 0 if you want no smoothing. Only valid for scatter!, lines!, and scatterlines! plots.

• x_unit::Unitful.Units=Unitful.NoUnits: Target unit for the x axis. The values will be converted accordingly. Use the default value of Unitful.NoUnits for dimensionless quantities.

• y_unit::Unitful.Units=Unitful.NoUnits: Target unit for the y axis. The values will be converted accordingly. Use the default value of Unitful.NoUnits for dimensionless quantities.

• x_exp_factor::Int=0: Numerical exponent to scale down the x axis, e.g. if x_exp_factor = 10 the values will be divided by $10^{10}$. The default is no scaling.

• y_exp_factor::Int=0: Numerical exponent to scale down the y axis, e.g. if y_exp_factor = 10 the values will be divided by $10^{10}$. The default is no scaling.

• x_trim::NTuple{2,<:Real}=(-Inf, Inf): The data will be trim down so the x coordinates fit within x_trim, in the units given by x_unit.

• y_trim::NTuple{2,<:Real}=(-Inf, Inf): The data will be trim down so the y coordinates fit within y_trim, in the units given by y_unit. This option does not affect histograms.

• x_edges::Bool=false: Set it to true if you want to keep the borders of x_trim.

• y_edges::Bool=false: Set it to true if you want to keep the borders of y_trim.

• x_func::Function=identity: Function to be applied to the values of the x axis. It must be a pure function with the signature x_func(x_values::Vector{Float64})::Vector{Float64}. The output must have the same length as the input. This function will be applied regardless of units and possible domain problems (use x_trim to solve incompatibilities), and that it will not be reflected in the automatic labeling.

• y_func::Function=identity: Function to be applied to the values of the y axis. It must be a pure function with the signature y_func(y_values::Vector{Float64})::Vector{Float64}. The output must have the same length as the input. This function will be applied regardless of units and possible domain problems (use y_trim to solve incompatibilities), and that it will not be reflected in the automatic labeling.

Axes options

• xaxis_label::AbstractString="auto_label": Label for the x axis. It can contain the string auto_label, which will be replaced by: xaxis_var_name [10^x_exp_factor x_unit]. If a LaTeXString with auto_label inside is used, it is recommended that each section around auto_label is delimited with a $ $ pair.
• yaxis_label::AbstractString="auto_label": Label for the y axis. It can contain the string auto_label, which will be replaced by: yaxis_var_name [10^y_exp_factor y_unit]. If a LaTeXString with auto_label inside is used, it is recommended that each section around auto_label is delimited with a $ $ pair.
• xaxis_var_name::AbstractString="x": Name of the variable for the x axis.
• yaxis_var_name::AbstractString="y": Name of the variable for the y axis.
• xaxis_scale_func::Function=identity: Scaling function for the x axis. The options are the scaling functions accepted by Makie: log10, log2, log, sqrt, Makie.logit, Makie.Symlog10, Makie.pseudolog10, and identity.
• yaxis_scale_func::Function=identity: Scaling function for the y axis. The options are the scaling functions accepted by Makie: log10, log2, log, sqrt, Makie.logit, Makie.Symlog10, Makie.pseudolog10, and identity.

Plotting options

• save_figures::Bool=true: If every figure will be saved as an image.

• backup_results::Bool=false: If the values to be plotted will be backup in a JLD2 file.

• theme::Attributes=Theme(): Plot theme that will take precedence over DEFAULT_THEME.

• sim_labels::Union{Vector{<:Union{AbstractString,Nothing}},Nothing}=nothing: Labels for the plot legend, one per simulation. Set it to nothing if you don't want a legend.

• title::Union{Symbol,<:AbstractString}="": Title for the figure. If left empty, no title is printed. It can also be set to one of the following options:

  • :physical_time -> Physical time since the Big Bang.
  • :lookback_time -> Physical time left to reach the last snapshot.
  • :scale_factor -> Scale factor (only relevant for cosmological simulations).
  • :redshift -> Redshift (only relevant for cosmological simulations).

• colorbar::Bool=false: If a colorbar will be added to heatmaps. Only relevant for when plot_functions is heatmap!.

Animation options

• animation::Bool=false: If an animation will be created.
• animation_filename::String="animation.mp4": Filename for the animation, including its extension. All formats supported by Makie can be used, namely .mkv, .mp4, .webm and .gif.
• framerate::Int=15: Frame rate of the animation.

plotTimeSeries(
    simulation_paths::Vector{String},
    plot_functions::Vector{<:Function};
    <keyword arguments>
)::Tuple{Makie.Axis,Figure}

Generate one figure per simulation.

Some of the features are:

• It can produce scatter and line plots.
• It transparently manages units; you only have to indicate the final unit of each axis.

Arguments

• simulation_paths::Vector{String}: Paths to the simulation directories, set in the code variable OutputDir.

• plot_functions::Vector{<:Function}: Vector of plotting functions from Makie. This sets the type of plot for each simulation. The supported functions are:

  • scatter! -> Scatter plot.
  • lines! -> Line plot.
  • scatterlines! -> Scatter plot with lines between the markers.

• pf_kwargs::Vector{<:NamedTuple}=[(;)]: Vector of keyword arguments for the functions in plot_functions.

plotTimeSeries configuration

• output_path::String=".": Path to the output folder.
• filename::String="time_series": Filename for the figure, without the extension.
• output_format::String=".png": File format for the figure. All formats supported by Makie can be used, namely .pdf, .svg and .png.
• show_progress::Bool=true: If a progress bar will be shown.

Data manipulation options

• slice::IndexType=(:): Slice of the simulation, i.e. which snapshots will be read. It can be an integer (a single snapshot), a vector of integers (several snapshots), an UnitRange (e.g. 5:13), an StepRange (e.g. 5:2:13) or (:) (all snapshots). It works over the longest possible list of snapshots among the simulations (grouped by the number in the file names). Out of bounds indices are ignored.
• da_functions::Vector{<:Function}=[getNothing]: Vector of data analysis functions. See the required signature and examples in ./src/analysis/data_analysis.jl.
• da_args::Vector{<:Tuple}=[()]: Vector of positional arguments for the data analysis functions.
• da_kwargs::Vector{<:NamedTuple}=[(;)]: Vector of keyword arguments for the data analysis functions.
• post_processing::Function=getNothing: Post processing function. See the required signature and examples in ./src/plotting/post_processing.jl.
• pp_args::Tuple=(): Positional arguments for the post processing function.
• pp_kwargs::NamedTuple=(;): Keyword arguments for the post processing function.
• x_unit::Unitful.Units=Unitful.NoUnits: Target unit for the x axis. The values will be converted accordingly. Use the default value of Unitful.NoUnits for dimensionless quantities.
• y_unit::Unitful.Units=Unitful.NoUnits: Target unit for the y axis. The values will be converted accordingly. Use the default value of Unitful.NoUnits for dimensionless quantities.
• x_exp_factor::Int=0: Numerical exponent to scale down the x axis, e.g. if x_exp_factor = 10 the values will be divided by $10^{10}$. The default is no scaling.
• y_exp_factor::Int=0: Numerical exponent to scale down the y axis, e.g. if y_exp_factor = 10 the values will be divided by $10^{10}$. The default is no scaling.
• x_trim::NTuple{2,<:Real}=(-Inf, Inf): The data will be trim down so the x coordinates fit within x_trim, in the units given by x_unit.
• y_trim::NTuple{2,<:Real}=(-Inf, Inf): The data will be trim down so the y coordinates fit within y_trim, in the units given by y_unit.
• x_edges::Bool=false: Set it to true if you want to keep the borders of x_trim.
• y_edges::Bool=false: Set it to true if you want to keep the borders of y_trim.
• x_func::Function=identity: Function to be applied to the values of the x axis. It must be a pure function with the signature x_func(x_values::Vector{Float64})::Vector{Float64}. The output must have the same length as the input. This function will be applied regardless of units and possible domain problems (use x_trim to solve incompatibilities), and that it will not be reflected in the automatic labeling.
• y_func::Function=identity: Function to be applied to the values of the y axis. It must be a pure function with the signature y_func(y_values::Vector{Float64})::Vector{Float64}. The output must have the same length as the input. This function will be applied regardless of units and possible domain problems (use y_trim to solve incompatibilities), and that it will not be reflected in the automatic labeling.

Axes options

• xaxis_label::AbstractString="auto_label": Label for the x axis. It can contain the string auto_label, which will be replaced by: xaxis_var_name [10^x_exp_factor x_unit]. If a LaTeXString with auto_label inside is used, it is recommended that each section around auto_label is delimited with a $ $ pair.
• yaxis_label::AbstractString="auto_label": Label for the y axis. It can contain the string auto_label, which will be replaced by: yaxis_var_name [10^y_exp_factor y_unit]. If a LaTeXString with auto_label inside is used, it is recommended that each section around auto_label is delimited with a $ $ pair.
• xaxis_var_name::AbstractString="x": Name of the variable for the x axis.
• yaxis_var_name::AbstractString="y": Name of the variable for the y axis.
• xaxis_scale_func::Function=identity: Scaling function for the x axis. The options are the scaling functions accepted by Makie: log10, log2, log, sqrt, Makie.logit, Makie.Symlog10, Makie.pseudolog10, and identity.
• yaxis_scale_func::Function=identity: Scaling function for the y axis. The options are the scaling functions accepted by Makie: log10, log2, log, sqrt, Makie.logit, Makie.Symlog10, Makie.pseudolog10, and identity.

Plotting options

• save_figures::Bool=true: If the plot will be saved as an image.
• backup_results::Bool=false: If the values to be plotted will be backup in a JLD2 file.
• theme::Attributes=Theme(): Plot theme that will take precedence over DEFAULT_THEME.
• sim_labels::Union{Vector{<:Union{AbstractString,Nothing}},Nothing}=nothing: Labels for the plot legend, one per simulation. Set it to nothing if you don't want a legend.
• title::AbstractString="": Title for the figure. If left empty, no title will be printed.

Returns

• The Axis and Figure objects.