Skip to main content

Model

class Model()​

Represent an existing model in the system, search by model id. The Model will be read-only and can be used to pre initialize a network

Load model based on id, returned object is read-only and can be connected to a task

Notice, we can override the input model when running remotely

  • Parameters

    model_id – ID (string)

archive​

archive()

Archive the model. If the model is already archived, this is a no-op

  • Return type

    ()

comment​

property comment: str

The comment for the model. Also, use for a model description.

  • Return type

    str

  • Returns

    The model comment / description.

config_dict​

property config_dict: dict

The configuration as a dictionary, parsed from the design text. This usually represents the model configuration. For example, prototxt, an ini file, or Python code to evaluate.

  • Return type

    dict

  • Returns

    The configuration.

config_text​

property config_text: str

The configuration as a string. For example, prototxt, an ini file, or Python code to evaluate.

  • Return type

    str

  • Returns

    The configuration.

framework​

property framework: str

The ML framework of the model (for example: PyTorch, TensorFlow, XGBoost, etc.).

  • Return type

    str

  • Returns

    The model’s framework

get_all_metadata​

get_all_metadata()

See Model.get_all_metadata_casted if you wish to cast the value to its type (if possible)

  • Return type

    Dict[str, Dict[str, str]]

  • Returns

    Get all metadata as a dictionary of format Dict[key, Dict[value, type]]. The key, value and type entries are all strings. Note that each entry might have an additional ‘key’ entry, repeating the key

get_all_metadata_casted​

get_all_metadata_casted()

  • Return type

    Dict[str, Dict[str, Any]]

  • Returns

    Get all metadata as a dictionary of format Dict[key, Dict[value, type]]. The key and type entries are strings. The value is cast to its type if possible. Note that each entry might have an additional ‘key’ entry, repeating the key

get_local_copy​

get_local_copy(extract_archive=None, raise_on_error=False, force_download=False)

Retrieve a valid link to the model file(s). If the model URL is a file system link, it will be returned directly. If the model URL points to a remote location (http/s3/gs etc.), it will download the file(s) and return the temporary location of the downloaded model.

  • Parameters

    • extract_archive (bool ) – If True, the local copy will be extracted if possible. If False, the local copy will not be extracted. If None (default), the downloaded file will be extracted if the model is a package.

    • raise_on_error (bool ) – If True, and the artifact could not be downloaded, raise ValueError, otherwise return None on failure and output log warning.

    • force_download (bool ) – If True, the artifact will be downloaded, even if the model artifact is already cached.

  • Return type

    str

  • Returns

    A local path to the model (or a downloaded copy of it).

get_metadata​

get_metadata(key)

Get one metadata entry value (as a string) based on its key. See Model.get_metadata_casted if you wish to cast the value to its type (if possible)

  • Parameters

    key (str) – Key of the metadata entry you want to get

  • Return type

    Optional[str]

  • Returns

    String representation of the value of the metadata entry or None if the entry was not found

get_metadata_casted​

get_metadata_casted(key)

Get one metadata entry based on its key, casted to its type if possible

  • Parameters

    key (str) – Key of the metadata entry you want to get

  • Return type

    Optional[str]

  • Returns

    The value of the metadata entry, casted to its type (if not possible, the string representation will be returned) or None if the entry was not found

get_weights​

get_weights(raise_on_error=False, force_download=False, extract_archive=False)

Download the base model and return the locally stored filename.

  • Parameters

    • raise_on_error (bool ) – If True, and the artifact could not be downloaded, raise ValueError, otherwise return None on failure and output log warning.

    • force_download (bool ) – If True, the base model will be downloaded, even if the base model is already cached.

    • extract_archive (bool ) – If True, the downloaded weights file will be extracted if possible

  • Return type

    str

  • Returns

    The locally stored file.

get_weights_package​

get_weights_package(return_path=False, raise_on_error=False, force_download=False, extract_archive=True)

Download the base model package into a temporary directory (extract the files), or return a list of the locally stored filenames.

  • Parameters

    • return_path (bool ) – Return the model weights or a list of filenames (Optional)

      • True - Download the model weights into a temporary directory, and return the temporary directory path.

      • False - Return a list of the locally stored filenames. (Default)

    • raise_on_error (bool ) – If True, and the artifact could not be downloaded, raise ValueError, otherwise return None on failure and output log warning.

    • force_download (bool ) – If True, the base artifact will be downloaded, even if the artifact is already cached.

    • extract_archive (bool ) – If True, the downloaded weights file will be extracted if possible

  • Return type

    Union[str, List[Path], None]

  • Returns

    The model weights, or a list of the locally stored filenames. if raise_on_error=False, returns None on error.

id​

property id

The ID (system UUID) of the model.

  • Return type

    str

  • Returns

    The model ID.

labels​

property labels: Dict[str, int]

The label enumeration of string (label) to integer (value) pairs.

  • Return type

    Dict[str, int]

  • Returns

    A dictionary containing labels enumeration, where the keys are labels and the values as integers.

name​

property name: str

The name of the model.

  • Return type

    str

  • Returns

    The model name.

project​

property project: str

project ID of the model.

  • Return type

    str

  • Returns

    project ID (str).

publish​

publish()

Set the model to the status published and for public use. If the model’s status is already published, then this method is a no-op.

  • Return type

    ()

published​

property published: bool

Get the published state of this model.

  • Return type

    bool

  • Returns

Model.query_models​

classmethod query_models(project_name=None, model_name=None, tags=None, only_published=False, include_archived=False, max_results=None, metadata=None)

Return Model objects from the project artifactory. Filter based on project-name / model-name / tags. List is always returned sorted by descending last update time (i.e. latest model is the first in the list)

  • Parameters

    • project_name (Optional[str]) – Optional, filter based project name string, if not given query models from all projects

    • model_name (Optional[str]) – Optional Model name as shown in the model artifactory

    • tags (Optional[Sequence[str]]) – Filter based on the requested list of tags (strings). To exclude a tag add “-” prefix to the tag. Example: ["production", "verified", "-qa"]. The default behaviour is to join all tags with a logical “OR” operator. To join all tags with a logical “AND” operator instead, use “__$all” as the first string, for example:

      ["__$all", "best", "model", "ever"]

      To join all tags with AND, but exclude a tag use “__$not” before the excluded tag, for example:

      ["__$all", "best", "model", "ever", "__$not", "internal", "__$not", "test"]

      The “OR” and “AND” operators apply to all tags that follow them until another operator is specified. The NOT operator applies only to the immediately following tag. For example:

      ["__$all", "a", "b", "c", "__$or", "d", "__$not", "e", "__$and", "__$or" "f", "g"]

      This example means (“a” AND “b” AND “c” AND (“d” OR NOT “e”) AND (“f” OR “g”)). See https://clear.ml/docs/latest/docs/clearml_sdk/model_sdk#tag-filters for details.

    • only_published (bool) – If True, only return published models.

    • include_archived (bool) – If True, return archived models.

    • max_results (Optional[int]) – Optional return the last X models, sorted by last update time (from the most recent to the least).

    • metadata (Optional[Dict[str, str]]) – Filter based on metadata. This parameter is a dictionary. Notice that the type of the metadata field is not required.

  • Return type

    List[Model]

  • Returns

    ModeList of Models objects

Model.remove​

classmethod remove(model, delete_weights_file=True, force=False, raise_on_errors=False)

Remove a model from the model repository. Optional, delete the model weights file from the remote storage.

  • Parameters

    • model (Union[str, Model]) – Model ID or Model object to remove

    • delete_weights_file (bool) – If True (default), delete the weights file from the remote storage

    • force (bool) – If True, remove model even if other Tasks are using this model. default False.

    • raise_on_errors (bool) – If True, throw ValueError if something went wrong, default False.

  • Return type

    bool

  • Returns

    True if Model was removed successfully partial removal returns False, i.e. Model was deleted but weights file deletion failed

report_confusion_matrix​

report_confusion_matrix(title, series, matrix, iteration=None, xaxis=None, yaxis=None, xlabels=None, ylabels=None, yaxis_reversed=False, comment=None, extra_layout=None)

For explicit reporting, plot a heat-map matrix.

For example:

confusion = np.random.randint(10, size=(10, 10))
model.report_confusion_matrix("example confusion matrix", "ignored", iteration=1, matrix=confusion,
     xaxis="title X", yaxis="title Y")

  • Parameters

    • title (str ) – The title (metric) of the plot.

    • series (str ) – The series name (variant) of the reported confusion matrix.

    • matrix (numpy.ndarray ) – A heat-map matrix (example: confusion matrix)

    • iteration (int ) – The reported iteration / step.

    • xaxis (str ) – The x-axis title. (Optional)

    • yaxis (str ) – The y-axis title. (Optional)

    • xlabels (list ( str ) ) – Labels for each column of the matrix. (Optional)

    • ylabels (list ( str ) ) – Labels for each row of the matrix. (Optional)

    • yaxis_reversed (bool ) – If False 0,0 is at the bottom left corner. If True, 0,0 is at the top left corner

    • comment (str ) – A comment displayed with the plot, underneath the title.

    • extra_layout (dict ) – optional dictionary for layout configuration, passed directly to plotly See full details on the supported configuration: https://plotly.com/javascript/reference/heatmap/ example: extra_layout={‘xaxis’: {‘type’: ‘date’, ‘range’: [‘2020-01-01’, ‘2020-01-31’]}}

report_histogram​

report_histogram(title, series, values, iteration=None, labels=None, xlabels=None, xaxis=None, yaxis=None, mode=None, data_args=None, extra_layout=None)

For explicit reporting, plot a (default grouped) histogram. Notice this function will not calculate the histogram, it assumes the histogram was already calculated in values

For example:

vector_series = np.random.randint(10, size=10).reshape(2,5)
model.report_histogram(title='histogram example', series='histogram series',
     values=vector_series, iteration=0, labels=['A','B'], xaxis='X axis label', yaxis='Y axis label')

  • Parameters

    • title – The title (metric) of the plot.

    • series – The series name (variant) of the reported histogram.

    • values – The series values. A list of floats, or an N-dimensional Numpy array containing data for each histogram bar.

    • iteration – The reported iteration / step. Each iteration creates another plot.

    • labels – Labels for each bar group, creating a plot legend labeling each series. (Optional)

    • xlabels – Labels per entry in each bucket in the histogram (vector), creating a set of labels for each histogram bar on the x-axis. (Optional)

    • xaxis – The x-axis title. (Optional)

    • yaxis – The y-axis title. (Optional)

    • mode – Multiple histograms mode, stack / group / relative. Default is ‘group’.

    • data_args – optional dictionary for data configuration, passed directly to plotly See full details on the supported configuration: https://plotly.com/javascript/reference/bar/ example: data_args={‘orientation’: ‘h’, ‘marker’: {‘color’: ‘blue’}}

    • extra_layout – optional dictionary for layout configuration, passed directly to plotly See full details on the supported configuration: https://plotly.com/javascript/reference/bar/ example: extra_layout={‘xaxis’: {‘type’: ‘date’, ‘range’: [‘2020-01-01’, ‘2020-01-31’]}}

report_line_plot​

report_line_plot(title, series, xaxis, yaxis, mode='lines', iteration=None, reverse_xaxis=False, comment=None, extra_layout=None)

For explicit reporting, plot one or more series as lines.

  • Parameters

    • title (str ) – The title (metric) of the plot.

    • series (list ) – All the series data, one list element for each line in the plot.

    • iteration (int ) – The reported iteration / step.

    • xaxis (str ) – The x-axis title. (Optional)

    • yaxis (str ) – The y-axis title. (Optional)

    • mode (str ) – The type of line plot. The values are:

      • lines (default)

      • markers

      • lines+markers

    • reverse_xaxis (bool ) – Reverse the x-axis. The values are:

      • True - The x-axis is high to low (reversed).

      • False - The x-axis is low to high (not reversed). (default)

    • comment (str ) – A comment displayed with the plot, underneath the title.

    • extra_layout (dict ) – optional dictionary for layout configuration, passed directly to plotly See full details on the supported configuration: https://plotly.com/javascript/reference/scatter/ example: extra_layout={‘xaxis’: {‘type’: ‘date’, ‘range’: [‘2020-01-01’, ‘2020-01-31’]}}

report_matrix​

report_matrix(title, series, matrix, iteration=None, xaxis=None, yaxis=None, xlabels=None, ylabels=None, yaxis_reversed=False, extra_layout=None)

For explicit reporting, plot a confusion matrix.

info

This method is the same as Model.report_confusion_matrix.

  • Parameters

    • title (str ) – The title (metric) of the plot.

    • series (str ) – The series name (variant) of the reported confusion matrix.

    • matrix (numpy.ndarray ) – A heat-map matrix (example: confusion matrix)

    • iteration (int ) – The reported iteration / step.

    • xaxis (str ) – The x-axis title. (Optional)

    • yaxis (str ) – The y-axis title. (Optional)

    • xlabels (list ( str ) ) – Labels for each column of the matrix. (Optional)

    • ylabels (list ( str ) ) – Labels for each row of the matrix. (Optional)

    • yaxis_reversed (bool ) – If False, 0,0 is at the bottom left corner. If True, 0,0 is at the top left corner

    • extra_layout (dict ) – optional dictionary for layout configuration, passed directly to plotly See full details on the supported configuration: https://plotly.com/javascript/reference/heatmap/ example: extra_layout={‘xaxis’: {‘type’: ‘date’, ‘range’: [‘2020-01-01’, ‘2020-01-31’]}}

report_scalar​

report_scalar(title, series, value, iteration)

For explicit reporting, plot a scalar series.

  • Parameters

    • title (str ) – The title (metric) of the plot. Plot more than one scalar series on the same plot by using the same title for each call to this method.

    • series (str ) – The series name (variant) of the reported scalar.

    • value (float ) – The value to plot per iteration.

    • iteration (int ) – The reported iteration / step (x-axis of the reported time series)

  • Return type

    None

report_scatter2d​

report_scatter2d(title, series, scatter, iteration=None, xaxis=None, yaxis=None, labels=None, mode='line', comment=None, extra_layout=None)

For explicit reporting, report a 2d scatter plot.

For example:

scatter2d = np.hstack((np.atleast_2d(np.arange(0, 10)).T, np.random.randint(10, size=(10, 1))))
model.report_scatter2d(title="example_scatter", series="series", iteration=0, scatter=scatter2d,
     xaxis="title x", yaxis="title y")

Plot multiple 2D scatter series on the same plot by passing the same title and iteration values to this method:

scatter2d_1 = np.hstack((np.atleast_2d(np.arange(0, 10)).T, np.random.randint(10, size=(10, 1))))
model.report_scatter2d(title="example_scatter", series="series_1", iteration=1, scatter=scatter2d_1,
     xaxis="title x", yaxis="title y")

scatter2d_2 = np.hstack((np.atleast_2d(np.arange(0, 10)).T, np.random.randint(10, size=(10, 1))))
model.report_scatter2d("example_scatter", "series_2", iteration=1, scatter=scatter2d_2,
     xaxis="title x", yaxis="title y")

  • Parameters

    • title (str ) – The title (metric) of the plot.

    • series (str ) – The series name (variant) of the reported scatter plot.

    • scatter (list ) – The scatter data. numpy.ndarray or list of (pairs of x,y) scatter:

    • iteration (int ) – The reported iteration / step.

    • xaxis (str ) – The x-axis title. (Optional)

    • yaxis (str ) – The y-axis title. (Optional)

    • labels (list ( str ) ) – Labels per point in the data assigned to the scatter parameter. The labels must be in the same order as the data.

    • mode (str ) – The type of scatter plot. The values are:

      • lines

      • markers

      • lines+markers

    • comment (str ) – A comment displayed with the plot, underneath the title.

    • extra_layout (dict ) – optional dictionary for layout configuration, passed directly to plotly See full details on the supported configuration: https://plotly.com/javascript/reference/scatter/ example: extra_layout={‘xaxis’: {‘type’: ‘date’, ‘range’: [‘2020-01-01’, ‘2020-01-31’]}}

report_scatter3d​

report_scatter3d(title, series, scatter, iteration=None, xaxis=None, yaxis=None, zaxis=None, labels=None, mode='markers', fill=False, comment=None, extra_layout=None)

For explicit reporting, plot a 3d scatter graph (with markers).

  • Parameters

    • title (str ) – The title (metric) of the plot.

    • series (str ) – The series name (variant) of the reported scatter plot.

    • list ] scatter (Union [ numpy.ndarray , ) – The scatter data. list of (pairs of x,y,z), list of series [[(x1,y1,z1)…]], or numpy.ndarray

    • iteration (int ) – The reported iteration / step.

    • xaxis (str ) – The x-axis title. (Optional)

    • yaxis (str ) – The y-axis title. (Optional)

    • zaxis (str ) – The z-axis title. (Optional)

    • labels (list ( str ) ) – Labels per point in the data assigned to the scatter parameter. The labels must be in the same order as the data.

    • mode (str ) – The type of scatter plot. The values are: lines, markers, lines+markers.

      For example:

      scatter3d = np.random.randint(10, size=(10, 3))
      model.report_scatter3d(title="example_scatter_3d", series="series_xyz", iteration=1, scatter=scatter3d,
          xaxis="title x", yaxis="title y", zaxis="title z")

    • fill (bool ) – Fill the area under the curve. The values are:

      • True - Fill

      • False - Do not fill (default)

    • comment (str ) – A comment displayed with the plot, underneath the title.

    • extra_layout (dict ) – optional dictionary for layout configuration, passed directly to plotly See full details on the supported configuration: https://plotly.com/javascript/reference/scatter3d/ example: extra_layout={‘xaxis’: {‘type’: ‘date’, ‘range’: [‘2020-01-01’, ‘2020-01-31’]}}

report_single_value​

report_single_value(name, value)

Reports a single value metric (for example, total experiment accuracy or mAP)

  • Parameters

    • name (str) – Metric’s name

    • value (float) – Metric’s value

  • Return type

    None

report_surface​

report_surface(title, series, matrix, iteration=None, xaxis=None, yaxis=None, zaxis=None, xlabels=None, ylabels=None, camera=None, comment=None, extra_layout=None)

For explicit reporting, report a 3d surface plot.

info

This method plots the same data as Model.report_confusion_matrix, but presents the data as a surface diagram not a confusion matrix.

surface_matrix = np.random.randint(10, size=(10, 10))
model.report_surface("example surface", "series", iteration=0, matrix=surface_matrix,
     xaxis="title X", yaxis="title Y", zaxis="title Z")

  • Parameters

    • title (str ) – The title (metric) of the plot.

    • series (str ) – The series name (variant) of the reported surface.

    • matrix (numpy.ndarray ) – A heat-map matrix (example: confusion matrix)

    • iteration (int ) – The reported iteration / step.

    • xaxis (str ) – The x-axis title. (Optional)

    • yaxis (str ) – The y-axis title. (Optional)

    • zaxis (str ) – The z-axis title. (Optional)

    • xlabels (list ( str ) ) – Labels for each column of the matrix. (Optional)

    • ylabels (list ( str ) ) – Labels for each row of the matrix. (Optional)

    • camera (list ( float ) ) – X,Y,Z coordinates indicating the camera position. The default value is (1,1,1).

    • comment (str ) – A comment displayed with the plot, underneath the title.

    • extra_layout (dict ) – optional dictionary for layout configuration, passed directly to plotly See full details on the supported configuration: https://plotly.com/javascript/reference/surface/ example: extra_layout={‘xaxis’: {‘type’: ‘date’, ‘range’: [‘2020-01-01’, ‘2020-01-31’]}}

report_table​

report_table(title, series, iteration=None, table_plot=None, csv=None, url=None, extra_layout=None)

For explicit report, report a table plot.

One and only one of the following parameters must be provided.

  • table_plot - Pandas DataFrame or Table as list of rows (list)

  • csv - CSV file

  • url - URL to CSV file

For example:

df = pd.DataFrame({'num_legs': [2, 4, 8, 0],
        'num_wings': [2, 0, 0, 0],
        'num_specimen_seen': [10, 2, 1, 8]},
        index=['falcon', 'dog', 'spider', 'fish'])

model.report_table(title='table example',series='pandas DataFrame',iteration=0,table_plot=df)

  • Parameters

    • title – The title (metric) of the table.

    • series – The series name (variant) of the reported table.

    • iteration – The reported iteration / step.

    • table_plot – The output table plot object

    • csv – path to local csv file

    • url – A URL to the location of csv file.

    • extra_layout – optional dictionary for layout configuration, passed directly to plotly See full details on the supported configuration: https://plotly.com/javascript/reference/layout/ example: extra_layout={‘height’: 600}

report_vector​

report_vector(title, series, values, iteration=None, labels=None, xlabels=None, xaxis=None, yaxis=None, mode=None, extra_layout=None)

For explicit reporting, plot a vector as (default stacked) histogram.

For example:

vector_series = np.random.randint(10, size=10).reshape(2,5)
model.report_vector(title='vector example', series='vector series', values=vector_series, iteration=0,
     labels=['A','B'], xaxis='X axis label', yaxis='Y axis label')

  • Parameters

    • title – The title (metric) of the plot.

    • series – The series name (variant) of the reported histogram.

    • values – The series values. A list of floats, or an N-dimensional Numpy array containing data for each histogram bar.

    • iteration – The reported iteration / step. Each iteration creates another plot.

    • labels – Labels for each bar group, creating a plot legend labeling each series. (Optional)

    • xlabels – Labels per entry in each bucket in the histogram (vector), creating a set of labels for each histogram bar on the x-axis. (Optional)

    • xaxis – The x-axis title. (Optional)

    • yaxis – The y-axis title. (Optional)

    • mode – Multiple histograms mode, stack / group / relative. Default is ‘group’.

    • extra_layout – optional dictionary for layout configuration, passed directly to plotly See full details on the supported configuration: https://plotly.com/javascript/reference/layout/ example: extra_layout={‘showlegend’: False, ‘plot_bgcolor’: ‘yellow’}

set_all_metadata​

set_all_metadata(metadata, replace=True)

Set metadata based on the given parameters. Allows replacing all entries or updating the current entries.

  • Parameters

    • metadata (Dict[str, Dict[str, str]]) – A dictionary of format Dict[key, Dict[value, type]] representing the metadata you want to set

    • replace (bool) – If True, replace all metadata with the entries in the metadata parameter. If False, keep the old metadata and update it with the entries in the metadata parameter (add or change it)

  • Return type

    bool

  • Returns

    True if the metadata was set and False otherwise

set_metadata​

set_metadata(key, value, v_type=None)

Set one metadata entry. All parameters must be strings or castable to strings

  • Parameters

    • key (str) – Key of the metadata entry

    • value (str) – Value of the metadata entry

    • v_type (Optional[str]) – Type of the metadata entry

  • Return type

    bool

  • Returns

    True if the metadata was set and False otherwise

system_tags​

property system_tags: List[str]

A list of system tags describing the model.

  • Return type

    List[str]

  • Returns

    The list of tags.

tags​

property tags: List[str]

A list of tags describing the model.

  • Return type

    List[str]

  • Returns

    The list of tags.

task​

property task: str

Return the creating task ID

  • Return type

    str

  • Returns

    The Task ID (str)

unarchive​

unarchive()

Unarchive the model. If the model is not archived, this is a no-op

  • Return type

    ()

url​

property url: str

Return the url of the model file (or archived files)

  • Return type

    str

  • Returns

    The model file URL.