The Client class¶
Methods¶
__init__(...)¶
Initialise an instance of the Simvue client
Parameters
| server_token | Optional[str] |
specify token, if unset this is read from the config file |
| server_url | Optional[str] |
specify URL, if unset this is read from the config file |
abort_run(...)¶
Abort a currently active run on the server
Parameters
| run_id | str |
the unique identifier for the run |
| reason | str |
reason for abort |
Returns
dict | list
response from server
delete_alert(...)¶
Delete an alert from the server by ID
Parameters
| alert_id | str |
the unique identifier for the alert |
delete_folder(...)¶
Delete a folder by name
Parameters
| folder_path | Annotated[str, FieldInfo(annotation=None, required=True, metadata=[_PydanticGeneralMetadata(pattern='^/.*')])] |
name of the folder to delete. All paths are prefixed with / |
| recursive | bool |
if folder contains additional folders remove these, else return anerror. Default False. |
| remove_runs | bool |
whether to delete runs associated with this folder, by default False |
| allow_missing | bool |
allows deletion of folders which do not exist, else raise exception,default is exception raise |
Returns
list | None
if a folder is identified the runs also removed during execution
Raises
RuntimeError
if deletion of the folder from the server failed
delete_run(...)¶
Delete run by identifier
Parameters
| run_id | str |
the unique identifier for the run |
Returns
dict | None
the request response after deletion
Raises
RuntimeError
if the deletion failed due to server request error
delete_runs(...)¶
Delete runs in a named folder
Parameters
| folder_path | Annotated[str, FieldInfo(annotation=None, required=True, metadata=[_PydanticGeneralMetadata(pattern='^/.*')])] |
the path of the folder on which to perform deletion. All folderpaths are prefixed with / |
Returns
list | None
List of deleted runs
Raises
RuntimeError
if deletion fails due to server request error
delete_tag(...)¶
Delete a tag by its identifier
Parameters
| tag_id | str |
unique identifier for the tag |
Raises
RuntimeError
if the deletion failed due to a server request error
get_alerts(...)¶
Retrieve alerts for a given run
Parameters
| run_id | Optional[str] |
The ID of the run to find alerts for |
| critical_only | bool |
If a run is specified, whether to only return details about alerts which are currently critical, by default True |
| names_only | bool |
Whether to only return the names of the alerts (otherwise return the full details of the alerts), by default True |
| start_index | Optional[Annotated[int, Ge(ge=0)]] |
slice results returning only those above this index, by default None |
| count_limit | Optional[Annotated[int, Gt(gt=0)]] |
limit number of returned results, by default None |
Returns
list[dict[str, Any]]
a list of all alerts for this run which match the constrains specified
Raises
RuntimeError
if there was a failure retrieving data from the server
get_artifact(...)¶
Return the contents of a specified artifact
Parameters
| run_id | str |
the unique identifier of the run from which to retrieve the artifact |
| name | str |
the name of the artifact to retrieve |
| allow_pickle | bool |
whether to de-pickle the retrieved data, by default False |
Returns
DataFrame | Figure | FigureWidget | ndarray | Buffer | Tensor | bytes
de-serialized content of artifact if retrieved, else content of the server response
Raises
RuntimeError
if retrieval of artifact from the server failed
get_artifact_as_file(...)¶
Retrieve the specified artifact in the form of a file Information is saved to a file as opposed to deserialized
Parameters
| run_id | str |
unique identifier for the run to be queried |
| name | str |
the name of the artifact to be retrieved |
| path | Optional[str] |
path to download retrieved content to, the default of Noneuses the current working directory. |
Raises
RuntimeError
if there was a failure during retrieval of information from the
server
get_artifacts_as_files(...)¶
Retrieve artifacts from the given run as a set of files
Parameters
| run_id | str |
the unique identifier for the run |
| path | Optional[str] |
location to download files to, the default of None will downloadthem to the current working directory |
| startswith | Optional[str] |
only download artifacts with this prefix in their name, by default None |
| contains | Optional[str] |
only download artifacts containing this term in their name, by default None |
| endswith | Optional[str] |
only download artifacts ending in this term in their name, by default None |
Raises
RuntimeError
if there was a failure retrieving artifacts from the server
get_events(...)¶
Return events for a specified run
Parameters
| run_id | str |
the unique identifier of the run to query |
| message_contains | Optional[str] |
filter to events with message containing this expression, by default None |
| start_index | Optional[Annotated[int, Ge(ge=0)]] |
slice results returning only those above this index, by default None |
| count_limit | Optional[Annotated[int, Gt(gt=0)]] |
limit number of returned results, by default None |
Returns
list[dict[str, str]]
list of matching events containing entries with message and timestamp data
Raises
RuntimeError
if there was a failure retrieving information from the server
get_folder(...)¶
Retrieve a folder by identifier
Parameters
| folder_path | Annotated[str, FieldInfo(annotation=None, required=True, metadata=[_PydanticGeneralMetadata(pattern='^/.*')])] |
the path of the folder to retrieve on the server.Paths are prefixed with / |
Returns
dict[str, typing.Any] | None
data for the requested folder if it exists else None
Raises
RuntimeError
if there was a failure when retrieving information from the server
get_folders(...)¶
Retrieve folders from the server
Parameters
| filters | Optional[list[str]] |
set of filters to apply to the search |
| count | Annotated[int, Gt(gt=0)] |
maximum number of entries to return. Default is 100. |
| start_index | Annotated[int, Ge(ge=0)] |
the index from which to count entries. Default is 0. |
Returns
list[dict[str, Any]]
all data for folders matching the filter request
Raises
RuntimeError
if there was a failure retrieving data from the server
get_metric_values(...)¶
Retrieve the values for a given metric across multiple runs Uses filters to specify which runs should be retrieved. NOTE if the number of runs exceeds 100 'aggregated' will be set to True, and aggregated is not supported for the 'timestamp' xaxis format
Parameters
| metric_names | list[str] |
the names of metrics to return values for |
| xaxis | Literal['step', 'time', 'timestamp'] |
the xaxis type |
| output_format | Literal['dataframe', 'dict'] |
the format of the output, either a list or a Pandas dataframe |
| run_ids | Optional[list[str]] |
list of runs by id to include within metric retrieval |
| run_filters | Optional[list[str]] |
filters for specifying runs to include |
| use_run_names | bool |
use run names as opposed to IDs, note this is not recommended formultiple runs with the same name. Default is False. |
| aggregate | bool |
return results as averages (not compatible with xaxis=timestamp),default is False |
| max_points | Optional[Annotated[int, Gt(gt=0)]] |
maximum number of data points, by default None (all) |
Returns
dict or DataFrame or None
values for the given metric at each time interval if no runs pass filtering then return None
get_metrics_names(...)¶
Return information on all metrics within a run
Parameters
| run_id | str |
unique identifier of the run |
Returns
list[str]
names of metrics in the given run
Raises
RuntimeError
if there was a failure retrieving information from the server
get_run(...)¶
Retrieve a single run
Parameters
| run_id | str |
the unique identifier for this run |
Returns
dict[str, Any]
response containing information on the given run
Raises
RuntimeError
if retrieval of information from the server on this run failed
get_run_id_from_name(...)¶
Get Run ID from the server matching the specified name Assumes a unique name for this run. If multiple results are found this method will fail.
Parameters
| name | Annotated[str, FieldInfo(annotation=None, required=True, metadata=[_PydanticGeneralMetadata(pattern='^[a-zA-Z0-9\\-\\_\\s\\/\\.:]+$')])] |
the name of the run |
Returns
str
the unique identifier for this run
Raises
RuntimeError
if either information could not be retrieved from the server,
or multiple/no runs are found
get_run_name_from_id(...)¶
Retrieve the name of a run from its identifier
Parameters
| run_id | str |
the unique identifier for the run |
Returns
str
the registered name for the run
get_runs(...)¶
Retrieve all runs matching filters.
Parameters
| filters | Optional[list[str]] |
set of filters to apply to query results. If None is specifiedreturn all results without filtering. |
| metadata | bool |
whether to include metadata information in the response.Default False. |
| metrics | bool |
whether to include metrics information in the response.Default False. |
| alerts | bool |
whether to include alert information in the response.Default False. |
| output_format | Literal['dict', 'dataframe'] |
the structure of the response, either a dictionary or a dataframe.Default is 'dict'. Pandas must be installed for 'dataframe'. |
| count_limit | Optional[Annotated[int, Gt(gt=0)]] |
maximum number of entries to return. Default is 100. |
| start_index | Optional[Annotated[int, Gt(gt=0)]] |
the index from which to count entries. Default is 0. |
| show_shared | bool |
whether to include runs shared with the current user. Default is False. |
Returns
dict | pandas.DataFrame
either the JSON response from the runs request or the results in the form of a Pandas DataFrame
Raises
ValueError
if a value outside of 'dict' or 'dataframe' is specified
RuntimeError
if there was a failure in data retrieval from the server
get_tag(...)¶
Retrieve a single tag
Parameters
| tag_id | str |
the unique identifier for this tag |
Returns
dict[str, Any]
response containing information on the given tag
Raises
RuntimeError
if retrieval of information from the server on this tag failed
get_tags(...)¶
Retrieve tags
Parameters
| start_index | Optional[Annotated[int, Ge(ge=0)]] |
slice results returning only those above this index, by default None |
| count_limit | Optional[Annotated[int, Gt(gt=0)]] |
limit number of returned results, by default None |
Returns
list[dict[str, Any]]
a list of all tags for this run which match the constrains specified
Raises
RuntimeError
if there was a failure retrieving data from the server
list_artifacts(...)¶
Retrieve artifacts for a given run
Parameters
| run_id | str |
unique identifier for the run |
Returns
list[dict[str, typing.Any]]
list of relevant artifacts
Raises
RuntimeError
if retrieval of artifacts failed when communicating with the server
plot_metrics(...)¶
Plt the time series values for multiple metrics/runs
Parameters
| run_ids | list[str] |
unique identifiers for runs to plot |
| metric_names | list[str] |
names of metrics to plot |
| xaxis | Literal['step', 'time'] |
the x axis to plot against |
| max_points | Optional[int] |
maximum number of data points, by default None (all) |
Returns
Figure
plot figure object
Raises
ValueError
if invalid arguments are provided