API#

run_logger.hasura_logger

run_logger.main

run_logger.params

class run_logger.hasura_logger.Client(graphql_endpoint: str)#
class run_logger.hasura_logger.HasuraLogger(graphql_endpoint, seed=0, _run_id=None, debounce_time=0)#

HasuraLogger is the main logger class for this library.

Parameters

  • graphql_entrypoint – The endpoint of the Hasura GraphQL API, e.g. https://server.university.edu:1200/v1/graphql.

  • seed – The seed for the random number generator. Used for selecting random parameters in conjunction with sweeps. See sweep-logger for details about creating sweeps.

  • debounce_time – If your application expects to perform many log operations in rapid succession, debouncing collects the log data over the course of this time interval to perform a single large API call, instead of several small ones which might jam the server.

blob(blob, metadata)#

Store a blob object in database. “Blobs” typically store large objects such as images. Run-visualizer does not pull blobs from the Hasura database and they will not congest the visualizer web interface.

You must call create_run before calling this method.

Parameters

  • blob – This is expected to be a bytea datatype.

  • metadata – any JSON-compatible metadata to be stored with blob.

create_run(metadata, charts=None, sweep_id=None)#

Creates a new run in the Hasura database.

Parameters

  • metadata – Any useful data about the run being created, e.g. git commit, parameters used, etc. run-logger makes no assumptions about the content of metadata, except that it is JSON-compatible (or convertible to JSON-compatible by jsonify).

  • charts –

    A list of Vega or Vega-Lite graphical specifications, to be displayed by run-visualizer.

  • sweep_id –

    The ID of the sweep that this run is associated with, if any. See sweep-logger for details about creating sweeps.

Returns

A dictionary of new parameter values assigned by sweep, if run is associated with one

(otherwise None).

log(**log)#

Create a new log object to be added to the logs database table. This populates the data that run-visualizer will pass to Vega charts specs. Specifically, run-visualizer will insert the array of logs into data: values: [...].

You must call HasuraLogger.create_run() before calling this method.

update_metadata(metadata)#

This will combine given metadata with existing run metadata using the Hasura _append operator.

You must call HasuraLogger.create_run() before calling this method.

run_logger.hasura_logger.jsonify(value)#

Convert a value to a JSON-compatible type. In addition to standard JSON types, handles

  • pathlib.Path (converts to str)

  • np.nan (converts to null)

  • np.ndarray (converts to list)

Parameters

value – a str, Path, np.ndarray, dict, or Iterable.

Returns

value converted to JSON-serializable object

class run_logger.main.NewParams(config_params: Optional[dict], sweep_params: Optional[dict], load_params: Optional[dict])#
run_logger.main.create_run(logger=None, config=None, charts=None, metadata=None, sweep_id=None, load_id=None)#

Creates a new run. It registers the run in the database (using HasuraLogger.create_run) and returns a NewParams object, which provides parameters from three sources:

  • a config file (if provided)

  • a sweep (if the run is enrolled in a sweep)

  • the parameters from an existing run (if load_id is provided)

Parameters

  • logger – A HasuraLogger object. If None, the run is not registered in the database.

  • config – A path to a yaml config file.

  • charts – A list of charts to be added to the database, associated with this run.

  • sweep_id – The ID of the sweep in which the run is enrolled (if any).

  • load_id – The ID of an existing run whose parameters you want to access.

run_logger.main.get_config_params(config)#

Reads a yaml config file and returns a dictionary of parameters.

run_logger.main.get_load_params(load_id, logger)#

Returns the parameters of an existing run.

Parameters

  • load_id – The ID of an existing run whose parameters you want to access.

  • logger – A HasuraLogger object associated with the database where the run is stored.

run_logger.main.initialize(graphql_endpoint=None, config=None, charts=None, metadata=None, name=None, sweep_id=None, load_id=None, **params)#

The main function to initialize a run. It creates a new run and returns the parameters and a HasuraLogger object, which is a handle for accessing the database.

Parameters

  • graphql_endpoint – The endpoint of the Hasura GraphQL API, e.g. https://server.university.edu:1200/v1/graphql. If this value is None, the run will not be logged in the database.

  • config – An optional path to a yaml config file file containing parameters. See the section on Config files for more details.

  • charts –

    A list of Vega or Vega-Lite graphical specifications, to be displayed by run-visualizer.

  • metadata – Any JSON-serializable object to be stored in the database.

  • name – An optional name to be given to the run.

  • sweep_id – An optional sweep ID, to enroll this run in a sweep.

  • load_id – An optional run ID, to load parameters from an existing run.

  • params – Existing (usually default) parameters provided for the run (and updated by update_params).

Returns

A tuple of parameters and a HasuraLogger object.

run_logger.main.update_params(logger, new_params, name, **params)#

This is a convenience wrapper HasuraLogger.update_metadata Updates the existing parameters of a run (params) with new parameters using the Hasura _append operator.

Parameters are updated with the following precedence: 1. Load parameters (parameters corresponding to an existing run, specified by load_id) if any. 2. sweep parameters (parameters issued by a sweep, specified by sweep_id) if any. 3. config parameters (parameters specified in a config file, specified by config) if any.

That is, sweep parameters will overwrite config parameters and load parameters will overwrite sweep parameters.

Note that this function does mutate the metadata stored in the database.

Parameters

  • logger – A HasuraLogger object associated with the database containing the run whose parameters need to be updated.

  • new_params – The new parameters.

  • name – A name to be given to the run.

  • params – Existing parameters (e.g. command line defaults).

Returns

Updated parameters.