API Reference

API Reference#

class notata.logbook.Logbook(run_id, base_dir='outputs', params=None, overwrite=False, preallocate=False, callback=None)#

Bases: object

Structured log directory for a single scientific run.

Each Logbook instance creates an isolated folder under the base directory, where parameters, metadata, logs, arrays, plots, and other artifacts can be saved. Supports context-manager semantics to automatically mark success/failure.

Example structure:

log_<run_id>/
    log.txt
    metadata.json
    params.yaml
    data/
        states.npz
    plots/
        loss.png
    artifacts/
        config.json
        model.pkl

Note

Logbook methods are not thread- or process-safe. Use external coordination when logging from multiple workers.

Parameters:

run_id (Union[str, int]) – Unique string or int identifying the run.
base_dir (Union[str, Path]) – Parent directory under which to create the log directory.
params (Optional[Dict[str, Any]]) – Optional parameters to save immediately.
overwrite (bool) – If True, overwrite any existing run directory.
preallocate (bool) – If True, pre-create standard subdirectories.
callback (Optional[Callable]) – Optional function to call when marking the run as complete or failed. It receives the Logbook instance as the only argument.

array(name, array)#

Save a single NumPy array in .npy format.

Parameters:

name (str) – Base filename without extension.
array (ndarray) – Numpy array to save.

Example

>>> log.array("velocity", np.array([0, 1, 2]))

arrays(name, compressed=True, **arrays)#

Save multiple arrays into one compressed .npz archive.

Parameters:

name (str) – Base filename without extension.
compressed (bool) – If True, use compressed format.
**arrays (ndarray) – Named arrays (keys become archive keys).

bytes(name, data)#

Save raw bytes to artifacts/{name}.

Parameters:

name (str) – Output filename (with extension).
data (bytes) – Byte content to write.

Example

>>> log.bytes("weights.bin", b"")

debug(msg)#

property elapsed: float#: Elapsed wall time in seconds since initialization.

error(msg)#

info(msg)#

json(name, data)#

Save a JSON file in artifacts/{name}.json.

Parameters:

name (str) – Base filename without extension.
data (Dict[str, Any]) – Dictionary to serialize as JSON.

Example

>>> log.json("metrics", {"loss": 0.01})

mark_complete()#: Mark the run as complete and finalize metadata.

mark_failed(reason)#

Mark the run as failed.

Parameters:: reason (str) – Brief description of the failure cause.

meta(**fields)#: Update metadata.json with new fields (atomic merge).

note(message, level=20)#

params(ext='yaml', **kwargs)#

Write run parameters in YAML or JSON.

Parameters:

ext (str) – Either ‘yaml’ or ‘json’.
**kwargs (Any) – Parameters to save.

Raises:

ValueError – If ext is not one of the supported formats.

pickle(name, obj, protocol=5)#

Serialize a Python object with pickle to artifacts/{name}.pkl.

Parameters:

name (str) – Base filename without extension.
obj (Any) – Object to serialize.
protocol (int) – Pickle protocol version to use.

Example

>>> log.pickle("model", model_object)

plot(name, fig=None, dpi=200, formats=('png',))#

Save a matplotlib figure to plots/{name}.{ext}.

If no figure is provided, the current active figure (plt.gcf()) is used. Supports saving in multiple formats simultaneously (e.g., PNG and PDF).

Parameters:

name (str) – Base filename without extension.
fig (Optional[Any]) – Matplotlib figure to save. Defaults to current figure.
dpi (int) – Resolution (dots per inch) for raster formats like PNG.
formats (Iterable[str]) – List or tuple of file extensions to save (e.g., (“png”, “pdf”)).

Raises:

RuntimeError – If matplotlib is not installed.

Example

>>> log.plot("trajectory", fig=fig, formats=("png", "pdf"))

property status: str#: Current run status. [‘initialized’, ‘complete’, ‘failed’, ‘unknown’]

text(name, content)#

Save plain text to artifacts/{name}.txt.

Parameters:

name (str) – Base filename without extension.
content (str) – Text content to write.

Example

>>> log.text("stdout", "Simulation complete.")

warning(msg)#

class notata.experiment.Experiment(name, base_dir='outputs')#

Bases: object

Structured manager for organizing and accessing multiple scientific runs.

Each Experiment instance creates an isolated folder under the base directory, where individual runs are stored as subdirectories. Supports adding new runs, recording metrics, and querying results.

Example structure:

experiment_name/
    index.csv
    runs/
        log_<run_id>/
            metadata.json
            params.yaml
            data/
                states.npz
            plots/
                loss.png
            artifacts/
                config.json
                model.pkl

Parameters:

name (str) – Name of the experiment.
base_dir (Path | str) – Parent directory under which to create the experiment directory.

add(skip_existing=False, **params)#

Return type:: Logbook | None

record(log, metrics_file='artifacts/metrics.json')#

select(**filters)#

to_dataframe()#

class notata.reader.ExperimentReader(path)#

Bases: object

Facilitates access to multiple Logbook runs within an experiment directory.

This class enables iteration over runs, retrieval of parameters and metadata, and querying the experiment index.

Example

>>> exp = ExperimentReader("outputs/my_experiment")
>>> for run in exp:
>>>     print(run.meta)

Parameters:

path (Union[str, Path]) – Path to the experiment directory.
base_dir – Base directory for experiments, defaults to “outputs”.

index()#

Iterate over rows in the index.csv file.

Yields:: Dict[str, Any] – A dictionary representing a row in the index file.
Return type:: Iterator[Dict[str, Any]]

property meta: Dict[str, Dict[str, Any]]#

Load the metadata of all the runs in this experiment.

Returns:: A dictionary mapping run IDs to their metadata.
Return type:: Dict[str, Dict[str, Any]]

property params: Dict[str, Dict[str, Any]]#

Load the parameters of all the runs in this experiment.

Returns:: A dictionary mapping run IDs to their parameters.
Return type:: Dict[str, Dict[str, Any]]

class notata.reader.LogReader(path)#

Bases: object

Provides access to data and metadata from a single Logbook run directory.

This class allows users to retrieve parameters, metadata, arrays, artifacts, and plots associated with a specific run.

Example

>>> reader = LogReader("outputs/log_my_run")
>>> print(reader.params)

Parameters:: path (Union[str, Path]) – Path to the Logbook run directory.

property arrays: List[str]#

property artifacts: List[str]#

load_array(name)#

Load an array by name.

Supports:

‘foo’ -> loads data/foo.npy
‘bundle:key’ -> loads key from data/bundle.npz

Raises:: FileNotFoundError, KeyError if missing. –

load_json(name)#

Return type:: Dict[str, Any]

property meta: Dict[str, Any]#

Load the metadata of the run.

Returns:: Metadata loaded from metadata.json.
Return type:: Dict[str, Any]

property params: Dict[str, Any]#

Load the parameters of the run.

Returns:: Parameters loaded from params.yaml or params.json.
Return type:: Dict[str, Any]

property plots: List[str]#

property run_id: str#

Get the unique identifier for the run.

Returns:: The run ID, derived from the directory name.
Return type:: str

API Reference

Contents

API Reference#