IO & Export

Saving and loading trajectories, JSON summaries, and data export.

The io module handles all file operations, ensuring consistent formats across the library for JSON summaries, raw trajectories, and exported tables.

JSON Summaries

Workflows output their results as JSON summary files containing metadata, configuration, and classified trajectory metrics.

Saving a Summary

from hidden_attractors.io import summary_to_json

data = {
    "system": "chua_nonsmooth",
    "q": 0.98,
    "total_seeds": 50,
    "classification_counts": {
        "SELF_EXCITED": 48,
        "HIDDEN_CANDIDATE": 2
    }
}

summary_to_json(data, "results/chua_summary.json")

Loading a Summary

from hidden_attractors.io import load_summary_json

data = load_summary_json("results/chua_summary.json")
print(data["classification_counts"]["HIDDEN_CANDIDATE"]) # 2

Raw Trajectories (NumPy format)

When you find an interesting trajectory, you might want to save the entire time series array for later plotting or deep analysis. The library uses the efficient .npy binary format.

Saving a Trajectory

from hidden_attractors.io import save_trajectory
import numpy as np

# x is an array of shape (N, 3)
save_trajectory(x, "results/hidden_candidate_01.npy")

Loading a Trajectory

from hidden_attractors.io import load_trajectory

x = load_trajectory("results/hidden_candidate_01.npy")
print(x.shape)

Exporting Tables

For inclusion in academic papers, the library provides utilities to export summary data directly to CSV or LaTeX table formats.

Export to CSV

from hidden_attractors.io import export_csv

# Example data structure
rows = [
    {"Seed": 1, "Label": "SELF_EXCITED", "Distance": 0.05},
    {"Seed": 2, "Label": "HIDDEN_CANDIDATE", "Distance": 1.25}
]

export_csv(rows, "results/table.csv", columns=["Seed", "Label", "Distance"])

Export to LaTeX

This generates a ready-to-copy LaTeX tabular environment.

from hidden_attractors.io import export_latex_table

latex_code = export_latex_table(
    rows, 
    columns=["Seed", "Label", "Distance"],
    caption="Classification Results",
    label="tab:results"
)

print(latex_code)
# \begin{table}[ht]
# \centering
# \begin{tabular}{lll}
# \toprule
# Seed & Label & Distance \\
# \midrule
# 1 & SELF_EXCITED & 0.05 \\
# 2 & HIDDEN_CANDIDATE & 1.25 \\
# \bottomrule
# \end{tabular}
# \caption{Classification Results}
# \label{tab:results}
# \end{table}