sage_analysis.GalaxyAnalysis

class sage_analysis.GalaxyAnalysis(sage_parameter_fnames: List[str], plot_toggles: Optional[Dict[str, bool]] = None, sage_output_formats: Optional[List[str]] = None, labels: Optional[List[str]] = None, first_files_to_analyze: Optional[List[int]] = None, last_files_to_analyze: Optional[List[int]] = None, num_sage_output_files: Optional[List[int]] = None, output_format_data_classes_dict: Optional[Dict[str, Any]] = None, random_seeds: Optional[List[int]] = None, history_redshifts: Optional[Dict[str, Union[List[float], str]]] = None, calculation_functions: Optional[Dict[str, Tuple[Callable, Dict[str, Any]]]] = None, plot_functions: Optional[Dict[str, Tuple[Callable, Dict[str, Any]]]] = None, galaxy_properties_to_analyze: Optional[Dict[str, Dict[str, Union[str, List[str]]]]] = None, plots_that_need_smf: Optional[List[str]] = None, IMFs: Optional[List[str]] = None)[source]

Handles the ingestion, analysis, and plotting of SAGE galaxy outputs.

__init__(sage_parameter_fnames: List[str], plot_toggles: Optional[Dict[str, bool]] = None, sage_output_formats: Optional[List[str]] = None, labels: Optional[List[str]] = None, first_files_to_analyze: Optional[List[int]] = None, last_files_to_analyze: Optional[List[int]] = None, num_sage_output_files: Optional[List[int]] = None, output_format_data_classes_dict: Optional[Dict[str, Any]] = None, random_seeds: Optional[List[int]] = None, history_redshifts: Optional[Dict[str, Union[List[float], str]]] = None, calculation_functions: Optional[Dict[str, Tuple[Callable, Dict[str, Any]]]] = None, plot_functions: Optional[Dict[str, Tuple[Callable, Dict[str, Any]]]] = None, galaxy_properties_to_analyze: Optional[Dict[str, Dict[str, Union[str, List[str]]]]] = None, plots_that_need_smf: Optional[List[str]] = None, IMFs: Optional[List[str]] = None)[source]
Parameters:

  • sage_parameter_fnames (list of strings) – The name of the SAGE parameter files that are to be analyzed. These are the .ini files used to generate the galaxy files. The length of this variable is equal to the number of models to be analyzed.

  • plot_toggles (dict [str, bool], optional) – Specifies which properties should be analyzed and plotted.

    If not specified, uses

    default_plot_toggles = {
    "SMF" : True,
    "BMF" : True,
    "GMF" : True,
    "BTF" : True,
    "sSFR" : True,
    "gas_fraction" : True,
    "metallicity" : True,
    "bh_bulge" : True,
    "quiescent" : True,
    "bulge_fraction" : True,
    "baryon_fraction" : True,
    "reservoirs" : True,
    "spatial" : True,
    "SMF_history": False,
    "SFRD_history": False,
    "SMD_history": False,
}

  • sage_output_formats (list of strings, optional) – The output formats of each SAGE model being analyzed. Each value here MUST have a corresponding entry in output_format_data_classes_dict. The length of this variable is equal to the number of models to be analyzed.

    If not specified, will use the OutputFormat entry from the respective SAGE parameter file.

  • labels (list of strings, optional) – The labels to be used in the legend for each model. The length of this variable is equal to the number of models to be analyzed.

    If not specified, will use the FileNameGalaxies entry from the respective SAGE parameter file.

  • first_files_to_analyze, last_files_to_analyze (list of ints, optional-ish) – The output SAGE files to be analyzed. This is an inclusive range, with the output files analyzed ranging from [first_file_to_analyze, last_file_to_analyze] for each model. The length of this variable is equal to the number of models to be analyzed.

    If the corresponding entry in sage_output_format is sage_binary (whether passed explicitly or read from sage_file), these two variables MUST be specified. Otherwise, if not specified, will analyze ALL output HDF5 files.

  • num_sage_output_files (list of ints, optional-ish) – Specifies the number of output files that were generated by running SAGE. This will generally be equal to the number of processors used to run SAGE and can be different to the range specified by [first_file_to_analyze, last_file_to_analyze].

    If the corresponding entry in sage_output_format is sage_binary (whether passed explicitly or read from sage_file), this MUST be specified. Otherwise, this variable is NOT used.

  • output_format_data_classes_dict (dict [string, class], optional) – A dictionary that maps the output format name to the corresponding data class. Each value in sage_output_formats MUST have an entry in this dictionary.

    If not specified, will use a default value output_format_data_classes_dict = {"sage_binary": SageBinaryData , "sage_hdf5": SageHdf5Data }.

  • random_seeds (list of ints, optional) – The values to seed the random number generator for each model. If the value is None, then the generator is seeded using the np.random.seed() method. The length of this variable is equal to the number of models to be analyzed.

    If not specified, uses None for each model (i.e., no predetermined seed).

  • history_redshifts (dict [string, string or list of floats], optional) – Specifies which redshifts should be analyzed for properties and plots that are tracked over time. The keys here MUST have the same name as in plot_toggles.

    If the value of the entry is "All", then all snapshots will be analyzed. Otherwise, will search for the closest snapshots to the requested redshifts.

    If not specified, uses

    history_redshifts = {
    "SMF_history": "All",
    "SMD_history": "All",
    "SFRD_history": "All",
}

  • calculation_functions (dict [string, tuple(function, dict[string, variable])], optional) – A dictionary of functions that are used to compute the properties of galaxies being analyzed. Here, the string is the name of the plot toggle (e.g., "SMF"), the value is a tuple containing the function itself (e.g., calc_SMF()), and another dictionary which specifies any optional keyword arguments to that function with keys as the name of variable (e.g., "calc_sub_populations") and values as the variable value (e.g., True).

    The functions in this dictionary are called for all files analyzed and MUST have a signature func(model, gals, snapshot, optional_keyword_arguments). This dict can be generated using generate_func_dict().

    If not specified, will use the functions found in example_calcs, filtered to ensure that only those functions necessary to plot the plots specified by plot_toggles are run.

  • plot_functions (dict [string, tuple(function, dict[string, variable])], optional) – A dictionary of functions that are used to plot the properties of galaxies being analyzed. Here, the string is the name of the function (e.g., "plot_SMF"), the value is a tuple containing the function itself (e.g., plot_SMF()), and another dictionary which specifies any optional keyword arguments to that function with keys as the name of variable (e.g., "plot_sub_populations") and values as the variable value (e.g., True).

    The functions in this dictionary are called for all files analyzed and MUST have a signature func(models, snapshots, plot_helper, optional_keyword_arguments). This dict can be generated using generate_func_dict().

    If not specified, will use the functions found in example_plots, filtered to ensure that only those functions necessary to plot the plots specified by plot_toggles are run.

  • galaxy_properties_to_analyze (dict [string, dict[str, float or str or list of strings]], optional) – The galaxy properties that are used when running calculation_functions. The properties initialized here will be accessible through model.properties["property_name"].

    This variable is a nested dictionary with the outer dictionary specifying the name of the bins (if the properties will be binned), or a unique name otherwise.

    The inner dictionary has a number of fields that depend upon the type of property. We support properties being either binned against a property (e.g., the stellar or halo mass functions are binned on stellar/halo mass), plotted as x-vs-y scatter plots (e.g., specific star formation rate vs stellar mass for 1000 galaxies), or as a single value (e.g., the stellar mass density).

    For binned against a property, the key/value pairs are: "type": "binned", bin_low: The lower bound of the bin (float), bin_high: The upper bound of the bin (float), bin_width: The width of the bin (float), property_names: A list of strings denoting the properties to be initialised. The bin values are all initialized as 0.0.

    For properties to be plotted as x-vs-y scatter plots, the key/value pairs are: "type": "scatter", property_names: A list of strings denoting the properties to be initialised. All properties are initialized as empty lists.

    For properties that are single values, the key/value pairs are: "type": "single", property_names: A list of strings denoting the properties to be initialised. All properties are initialized with a value of 0.0.

    If not specified, uses

    default_galaxy_properties_to_analyze = {
    "stellar_mass_bins": {
        "type": "binned",
        "bin_low": 8.0,
        "bin_high": 12.0,
        "bin_width": 0.1,
        "property_names": [
            "SMF", "red_SMF", "blue_SMF", "BMF", "GMF",
            "centrals_MF", "satellites_MF", "quiescent_galaxy_counts",
            "quiescent_centrals_counts", "quiescent_satellites_counts",
            "fraction_bulge_sum", "fraction_bulge_var",
            "fraction_disk_sum", "fraction_disk_var", "SMF_history",
        ],
    },
    "halo_mass_bins": {
        "type": "binned",
        "bin_low": 10.0,
        "bin_high": 14.0,
        "bin_width": 0.1,
        "property_names": ["fof_HMF"] + [f"halo_{component}_fraction_sum"
            for component in ["baryon", "stars", "cold", "hot", "ejected", "ICS", "bh"]
        ],
    },
    "scatter_properties": {
        "type": "scatter",
        "property_names": [
            "BTF_mass", "BTF_vel", "sSFR_mass", "sSFR_sSFR",
            "gas_frac_mass", "gas_frac", "metallicity_mass",
            "metallicity", "bh_mass", "bulge_mass", "reservoir_mvir",
            "reservoir_stars", "reservoir_cold", "reservoir_hot",
            "reservoir_ejected", "reservoir_ICS", "x_pos",
            "y_pos", "z_pos"
        ],
    },
    "single_properties": {
        "type": "single",
        "property_names": ["SMD_history", "SFRD_history"],
    },
}

  • plots_that_need_smf (list of strings, optional) – The plot toggles that require the stellar mass function to be properly computed and analyzed. For example, plotting the quiescent fraction of galaxies requires knowledge of the total number of galaxies. The strings here must EXACTLY match the keys in plot_toggles.

    If not specified, uses a default value of ["SMF", "quiescent", "bulge_fraction", "SMF_history"].

  • IMFs (list of strings, optional, {"Chabrier", "Salpeter"}) – The initial mass functions used during the analysis of the galaxies. This is used to shift the observational data points. The length of this variable is equal to the number of models to be analyzed.

    If not specified, uses a "Chabrier" IMF for each model.
analyze_galaxies(snapshots: Optional[List[List[Union[str, int]]]] = None, redshifts: Optional[List[List[Union[float, str]]]] = None, analyze_history_snapshots: bool = True) → None[source]

Analyses the galaxies of the initialized models. These attributes will be updated directly, with the properties accessible via GalaxyAnalysis.models[<model_num>].properties[<snapshot>][<property_name>].

Also, all snapshots required to track the properties over time (as specified by _history_snaps_to_loop) will be analyzed, unless analyze_history_snapshots is False.

Parameters:

  • snapshots (nested list of ints or string, optional) – The snapshots to analyze for each model. If both this variable and redshifts are not specified, uses the highest snapshot (i.e., lowest redshift) as dictated by the redshifts attribute from the parameter file read for each model.

    If an entry if "All", then all snapshots for that model will be analyzed.

    The length of the outer list MUST be equal to num_models.

    Notes

    If analyze_history_snapshots is True, then the snapshots iterated over will be the unique combination of the snapshots required for history snapshots and those specified by this variable.

    Warning

    Only ONE of snapshots and redshifts can be specified.

  • redshifts (nested list of ints, optional) – The redshift to analyze for each model. If both this variable and snapshots are not specified, uses the highest snapshot (i.e., lowest redshift) as dictated by the redshifts attribute from the parameter file read for each model.

    The snapshots selected for analysis will be those that result in the redshifts closest to those requested. If an entry if "All", then all snapshots for that model will be analyzed.

    The length of the outer list MUST be equal to num_models.

    Notes

    If analyze_history_snapshots is True, then the snapshots iterated over will be the unique combination of the snapshots required for history snapshots and those specified by this variable.

    Warning

    Only ONE of snapshots and redshifts can be specified.

  • analyze_history_snapshots (bool, optional) – Specifies whether the snapshots required to analyze the properties tracked over time (e.g., stellar mass or star formation rate density) should be iterated over. If not specified, then only snapshot will be analyzed.

Notes

If you wish to analyze different properties to when you initialized an instance of GalaxyAnalysis, you MUST re-initialize another instance. Otherwise, the properties will be non-zeroed and not initialized correctly.

ValueError
Thrown if BOTH snapshots and redshifts are specified.
generate_plots(snapshots: Optional[List[List[Union[str, int]]]] = None, redshifts: Optional[List[List[Union[float, str]]]] = None, plot_helper: Optional[sage_analysis.plot_helper.PlotHelper] = None) → Optional[List[matplotlib.figure.Figure]][source]

Generates the plots for the models being analyzed. The plots to be created are defined by the values of plot_toggles specified when an instance of GalaxyAnalysis was initialized. If you wish to analyze different properties or create different plots, you MUST initialize another instance of GalaxyAnalysis with the new values for plot_toggles (ensuring that values of calcuations_functions and plot_functions are updated if using non-default values for plot_toggles).

This method should be run after analysing the galaxies using :py:method:`~analyze_galaxies`.

Parameters:

  • snapshots (nested list of ints or string, optional) – The snapshots to plot for each model. If both this variable and redshifts are not specified, uses the highest snapshot (i.e., lowest redshift) as dictated by the redshifts attribute from the parameter file read for each model.

    If an entry if "All", then all snapshots for that model will be analyzed.

    The length of the outer list MUST be equal to num_models.

    For properties that aren’t analyzed over redshift, the snapshots for each model will be plotted on each figure. For example, if we are plotting a single model, setting this variable to [[63, 50]] will give results for snapshot 63 and 50 on each figure. For some plots (e.g., those properties that are scatter plotted), this is undesirable and one should instead iterate over single snapshot values instead.

    Notes

    If analyze_history_snapshots is True, then the snapshots iterated over will be the unique combination of the snapshots required for history snapshots and those specified by this variable.

    Warning

    Only ONE of snapshots and redshifts can be specified.

  • redshifts (nested list of ints, optional) – The redshift to plot for each model. If both this variable and snapshots are not specified, uses the highest snapshot (i.e., lowest redshift) as dictated by the redshifts attribute from the parameter file read for each model.

    The snapshots selected for analysis will be those that result in the redshifts closest to those requested. If an entry if "All", then all snapshots for that model will be analyzed.

    The length of the outer list MUST be equal to num_models.

    Warning

    Only ONE of snapshots and redshifts can be specified.

  • plot_helper (PlotHelper, optional) – A helper class that contains attributes and methods to assist with plotting. In particular, the path where the plots will be saved and the output format. Refer to ../user/plot_helper for more information on how to initialize this class and its use.

    If not specified, then will initialize a default instance of PlotHelper. Refer to the PlotHelper documentation for a list of default attributes.
Returns:
history_redshifts

Specifies which redshifts should be analyzed for properties and plots that are tracked over time. The keys here MUST correspond to the keys in plot_toggles. If the value of the entry is "All", then all snapshots will be analyzed. Otherwise, will search for the closest snapshots to the requested redshifts.

Type:dict [string, string or list of floats]
models

The Model s being analyzed.

Type:list of Model class instances
num_models

The number of models being analyzed.

Type:int
output_format_data_classes_dict

A dictionary that maps the output format name to the corresponding data class.

Type:dict [str, class]
plot_functions

A dictionary of functions that are used to plot the properties of galaxies being analyzed. Here, the outer key is the name of the corresponding plot toggle (e.g., "SMF"), the value is a tuple containing the function itself (e.g., plot_SMF()), and another dictionary which specifies any optional keyword arguments to that function with keys as the name of variable (e.g., "plot_sub_populations") and values as the variable value (e.g., True).

The functions in this dictionary are called for all files analyzed and MUST have a signature func(Models, snapshot, plot_helper, plot_output_format, optional_keyword_arguments). This dict can be generated using generate_func_dict().

Type:dict [str, tuple(function, dict [str, any])]
plot_toggles

Specifies which properties should be analyzed and plotted.

Type:dict [str, bool]