FieldSet Export

DataFrame generation, CSV/HTML/chart export, and template rendering for numpy arrays and FieldSet containers.

pandas is optional — CSV, table, and chart exporters work with just numpy. Only StyledExporter requires pandas.

Installation

pip install vcti-fieldset-export>=1.0.0

With pandas support (for StyledExporter):

pip install vcti-fieldset-export[pandas]>=1.0.0

With all optional dependencies:

pip install vcti-fieldset-export[all]>=1.0.0

Quick Start

All exporters accept numpy arrays, dicts of numpy arrays, or pandas DataFrames.

CSV Export

import numpy as np
from vcti.fieldsetexport import CsvExporter

# From a dict of numpy arrays (no pandas needed)
CsvExporter({"stress": np.array([100, 200]), "disp": np.array([0.1, 0.2])}).export("output.csv")

# From a 2-D numpy array with field names
CsvExporter(np.array([[100, 0.1], [200, 0.2]]), field_names=["stress", "disp"]).export("output.csv")

# From a pandas DataFrame (requires pandas)
import pandas as pd
CsvExporter(pd.DataFrame({"stress": [100, 200], "disp": [0.1, 0.2]})).export("output.csv")

HTML Table (Tabulator)

from vcti.fieldsetexport import TableExporter

TableExporter({"stress": np.array([100, 200])}).export("output.html")

Styled HTML (requires pandas)

from vcti.fieldsetexport import StyledExporter

(
    StyledExporter({"stress": np.array([100, 200])})
    .set_caption("Results")
    .set_format(precision=2)
    .export_html("styled.html")
)

Interactive Chart

from vcti.fieldsetexport import ChartExporter, Trace, FigType, Fig

exporter = ChartExporter({"x": np.array([1, 2, 3])})
exporter.plot.title = "Stress vs Displacement"
exporter.plot.x_axis_title = "Index"
exporter.plot.y_axis_title = "Value"

fig = Fig(FigType.XY)
fig.add_trace(Trace("Stress", np.array([100, 200, 300]), color="blue"))
fig.add_trace(Trace("Displacement", np.array([0.1, 0.2, 0.3]), color="red"))
exporter.add_fig(fig)

exporter.export("chart.html")

Export Result and Dry-Run Validation

Every export() call returns an ExportResult with statistics:

result = CsvExporter({"stress": np.array([100, 200])}).export("output.csv")
print(result)  # ExportResult: 2 rows × 1 cols in 1.2ms, 34 bytes

# Dry-run: validate data + template without writing a file
result = CsvExporter(data).export("output.csv", validate_only=True)
assert result.dry_run is True

Error Handling

All export errors inherit from ExportError for easy catch-all handling:

from vcti.fieldsetexport import CsvExporter, ExportError, InvalidDataError

try:
    CsvExporter(data).export("output.csv")
except InvalidDataError as e:
    print(f"Bad data: {e}")       # empty array, wrong shape, etc.
except ExportError as e:
    print(f"Export failed: {e}")  # catches any export error

Exception hierarchy: ExportError > InvalidDataError, TemplateRenderError, FileWriteError.

Dependencies

• numpy (>=1.24) — required
• jinja2 (>=3.0) — required
• pandas (>=2.0) — optional (for StyledExporter)
• vcti-fieldset — optional (for FieldSet integration)
• beautifulsoup4 — optional (for styled HTML export)