Deborah.Miriam.FileIO

dump_bundle_rawtrM(
    bundle::Ensemble.EnsembleArrayBundle,
    key_list::Vector{String},
    outdir::String,
    LBP::Int,
    TRP::Int
) -> Nothing

Dump raw trace moment (trMi) data from all ensembles in an Deborah.Miriam.Ensemble.EnsembleArrayBundle.

Each Deborah.Miriam.Ensemble.EnsembleArray in the bundle is dumped using its tag name as a suffix, and each ensemble within the array is saved to a separate .dat file in the given outdir.

Arguments

• bundle::Ensemble.EnsembleArrayBundle: The bundle of ensemble arrays to process
• key_list::Vector{String}: Ensemble names (must match order in each array)
• outdir::String: Directory to write output .dat files
• LBP::Int: Ratio of labeled set (used in filenames)
• TRP::Int: Ratio of training set (used in filenames)

Output

• Writes .dat files for all ensembles inside each Deborah.Miriam.Ensemble.EnsembleArray, with filenames tagged by LBP, TRP, and tag.

Notes

• Internally calls dump_ens_array_rawtrM_by_ensemble for each Deborah.Miriam.Ensemble.EnsembleArray in the bundle.

dump_ens_array_rawtrM_by_ensemble(
    ens_array::Ensemble.EnsembleArray,
    key_list::Vector{String},
    outdir::String,
    LBP::Int,
    TRP::Int;
    suffix::String = ""
) -> Nothing

Dump raw trace moment data (trMi) from each ensemble in ens_array to separate .dat files.

Each file will be named using the ensemble name and parameters LBP, TRP, and optional suffix, and stored in the given outdir.

Arguments

• ens_array::Ensemble.EnsembleArray: The container holding all ensemble data
• key_list::Vector{String}: Ensemble names (matching order of ens_array.data)
• outdir::String: Output directory for the dumped .dat files
• LBP::Int: Ratio of labeled set (for file naming)
• TRP::Int: Ratio of training set (for file naming)

Keyword Arguments

• suffix::String = "": Optional suffix to include in output filenames

Output

• Writes one file per ensemble in outdir. Each line in the file includes:
  • Four normalized trace values ($\text{Tr} \, M^{-n} \; (n=1,2,3,4)$),
  • Original configuration number,
  • Source tag as a string (e.g., "Y_tr", "Y_bc", "Y_ul").

print_bundle_summary(
    bundle::Ensemble.EnsembleArrayBundle, 
    jobid::Union{Nothing, String}=nothing
) -> Nothing

Print a brief summary of an Deborah.Miriam.Ensemble.EnsembleArrayBundle, including tags and ensemble counts.

Arguments

• bundle::Ensemble.EnsembleArrayBundle: Collection of multiple Deborah.Miriam.Ensemble.EnsembleArray objects with substitution tags.
• jobid::Union{Nothing, String}: Optional job identifier for logging.

Behavior

• Prints:
  • The tag of the first array
  • Number of ensembles in the first array
  • Total number of arrays
  • Number of ensembles in each array and their corresponding tag

read_ensemble_array(
    cfg::TOMLConfigMiriam.FullConfigMiriam,
    paths::PathConfigBuilderMiriam.MiriamPathConfig;
    replace_bc::Bool=false,
    replace_ul::Bool=false,
    jobid::Union{Nothing, String}=nothing
) -> (Ensemble.EnsembleArray{Float64}, Params{Float64}, Vector{String})

Load and construct an Deborah.Miriam.Ensemble.EnsembleArray by reading trace data from multiple ensembles.

Arguments

• cfg::TOMLConfigMiriam.FullConfigMiriam: Configuration object with metadata and analysis settings.
• paths::PathConfigBuilderMiriam.MiriamPathConfig: Path container struct with resolved directory/file paths.
• replace_bc::Bool=false: If true, use replacement files for Y_BC to YP_BC
• replace_ul::Bool=false: If true, use replacement files for Y_UL to YP_UL.
• take_only_lb::Bool=false: If true, take files for Y_LB only.
• jobid::Union{Nothing, String}: Optional job ID for logging and profiling output.

Returns

• ens_array::Ensemble.EnsembleArray{Float64}: The loaded ensemble trace data.
• param::Params{Float64}: Shared lattice parameter struct.
• key_list::Vector{String}: Names of all ensembles in the array (ordered).

read_ensemble_array_bundle(
    cfg::TOMLConfigMiriam.FullConfigMiriam,
    paths::PathConfigBuilderMiriam.MiriamPathConfig,
    jobid::Union{Nothing, String}=nothing
) -> Tuple{Ensemble.EnsembleArrayBundle, Vector{String}}

Read and construct a full Deborah.Miriam.Ensemble.EnsembleArrayBundle by loading four consistent array variants (full datasets $+$ Y_LB-only datasets with/without Y_BC replacement). Also prints a bundle summary (when jobid = nothing) and can dump raw trace matrices if requested.

Arguments

• cfg::TOMLConfigMiriam.FullConfigMiriam: Global configuration containing input paths, flags, and analysis settings.
• paths::PathConfigBuilderMiriam.MiriamPathConfig: Resolved path builder for locating ensemble files.
• jobid::Union{Nothing, String}: Optional job ID used for structured logging and timing.

Loaded Variants

This function internally calls read_ensemble_array four times with the following settings and assigns the corresponding tags:

1. FULL-LBOG-ULOG → full data, no replacements

   • replace_bc = false, replace_ul = false, take_only_lb = false
   • Loads Y_TR, Y_BC, and Y_UL as originally present.

2. FULL-LBOG-ULML → full data, Y_UL replaced

   • replace_bc = false, replace_ul = true, take_only_lb = false
   • Y_TR and Y_BC are original; Y_UL is replaced to YP_UL.

3. LABL-TROG-BCOG → Y_LB-only, Y_BC original

   • replace_bc = false, replace_ul = false, take_only_lb = true
   • Loads only Y_TR and Y_BC (Y_UL is entirely skipped/ignored).

4. LABL-TROG-BCML → Y_LB-only, Y_BC replaced

   • replace_bc = true, replace_ul = false, take_only_lb = true
   • Loads only Y_TR and YP_BC (Y_UL is entirely skipped/ignored).

Note: When take_only_lb = true, any replace_ul setting is effectively ignored, and UL (Y_ul/YP_ul) data are not read at all.

Behavior

• Each call to read_ensemble_array is timed and logged via Deborah.Sarah.JobLoggerTools.@logtime_benji.
• The four Deborah.Miriam.Ensemble.EnsembleArrays are combined into a single Deborah.Miriam.Ensemble.EnsembleArrayBundle along with the tag list: ["FULL-LBOG-ULOG", "FULL-LBOG-ULML", "LABL-TROG-BCOG", "LABL-TROG-BCML"].
• The key_list (common ensemble identifiers) is taken from the first call and reused.
• If cfg.data.dump_original == true, the function invokes Deborah.Miriam.FileIO.dump_bundle_rawtrM to persist raw trace matrices for downstream inspection.
• If jobid = nothing, a human-readable summary of the bundle is printed.

Returns

• (::Ensemble.EnsembleArrayBundle, ::Vector{String}):
  • The constructed bundle containing the four array variants.
  • The key_list used for consistent ensemble identification across variants.

secondary_tag_to_str(
    tag::UInt8
) -> String

Convert a numeric secondary tag into its corresponding human-readable label.

Arguments

• tag::UInt8: Secondary tag value (typically 0 or 1)

Returns

• String: One of the following depending on the value:
  • 0 → "Y_lb"
  • 1 → "Y_ul"
  • Otherwise → "unknown"

source_tag_to_str(
    tag::UInt8
) -> String

Convert a numeric source tag into its corresponding human-readable label.

Arguments

• tag::UInt8: Source tag value (typically from 0 to 2)

Returns

• String: One of the following depending on the value:
  • 0 → "Y_tr"
  • 1 → "Y_bc"
  • 2 → "Y_ul"
  • Otherwise → "unknown"