OutputModel
class OutputModel()
Create an output model for a Task (experiment) to store the training results.
The OutputModel object is always connected to a Task object, because it is instantiated with a Task object as an argument. It is, therefore, automatically registered as the Task’s (experiment’s) output model.
The OutputModel object is read-write.
A common use case is to reuse the OutputModel object, and override the weights after storing a model snapshot. Another use case is to create multiple OutputModel objects for a Task (experiment), and after a new high score is found, store a model snapshot.
If the model configuration and / or the model’s label enumeration
are None
, then the output model is initialized with the values from the Task object’s input model.
When executing a Task (experiment) remotely in a worker, you can modify the model configuration and / or model’s label enumeration using the ClearML Web-App.
Create a new model and immediately connect it to a task.
We do not allow for Model creation without a task, so we always keep track on how we created the models In remote execution, Model parameters can be overridden by the Task (such as model configuration & label enumerator)
Parameters
task (Task ) – The Task object with which the OutputModel object is associated.
config_text (unconstrained text string ) – The configuration as a string. This is usually the content of a configuration dictionary file. Specify
config_text
orconfig_dict
, but not both.config_dict (dict ) – The configuration as a dictionary. Specify
config_dict
orconfig_text
, but not both.label_enumeration (dict ) – The label enumeration dictionary of string (label) to integer (value) pairs. (Optional)
For example:
{
"background": 0,
"person": 1
}name (str ) – The name for the newly created model. (Optional)
tags (list ( str ) ) – A list of strings which are tags for the model. (Optional)
comment (str ) – A comment / description for the model. (Optional)
framework (str or Framework object ) – The framework of the model or a Framework object. (Optional)
base_model_id – optional, model ID to be reused
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
Get the configuration as a dictionary parsed from the config_text
text. This usually represents the model
configuration. For example, from prototxt to ini file or python code to evaluate.
Return type
dict
Returns
The configuration.
config_text
property config_text
Get the configuration as a string. For example, prototxt, an ini file, or Python code to evaluate.
Return type
str
Returns
The configuration.
connect
connect(task, name=None)
Connect the current model to a Task object, if the model is a preexisting model. Preexisting models include:
Imported models.
Models whose metadata the ClearML Server (backend) is already storing.
Models from another source, such as frameworks like TensorFlow.
Parameters
task (object ) – A Task object.
name (str ) – The model name as it would appear on the Task object. The model object itself can have a different name, this is designed to support multiple models used/created by a single Task. Use examples would be GANs or model ensemble
Return type
None
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_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 getReturn 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 getReturn 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
Get the label enumeration as a dictionary of string (label) to integer (value) pairs.
For example:
{
"background": 0,
"person": 1
}
Return type
Dict
[str
,int
]Returns
The label enumeration.
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
Get the published state of this model.
Return type
bool
Returns
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.
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
- FillFalse
- 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 namevalue (
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.
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 fileurl
- 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 setreplace (
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
OutputModel.set_default_upload_uri
classmethod set_default_upload_uri(output_uri)
Set the default upload uri for all OutputModels
Parameters
output_uri (
Optional
[str
]) – URL for uploading models. examples: https://demofiles.demo.clear.ml, s3://bucket/, gs://bucket/, azure://bucket/, file:///mnt/shared/nfsReturn type
None
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 entryvalue (
str
) – Value of the metadata entryv_type (
Optional
[str
]) – Type of the metadata entry
Return type
bool
Returns
True if the metadata was set and False otherwise
set_upload_destination
set_upload_destination(uri)
Set the URI of the storage destination for uploaded model weight files. Supported storage destinations include S3, Google Cloud Storage, and file locations.
Using this method, file uploads are separate and then a link to each is stored in the model object.
For storage requiring credentials, the credentials are stored in the ClearML configuration file, ~/clearml.conf.
Parameters
uri (str ) – The URI of the upload storage destination.
For example:
s3://bucket/directory/
file:///tmp/debug/
Return bool
The status of whether the storage destination schema is supported.
True
- The storage destination scheme is supported.False
- The storage destination scheme is not supported.
Return type
None
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
()
update_design
update_design(config_text=None, config_dict=None)
Update the model configuration. Store a blob of text for custom usage.
This method’s behavior is lazy. The design update is only forced when the weights are updated.
Parameters
config_text (unconstrained text string ) – The configuration as a string. This is usually the content of a configuration dictionary file. Specify
config_text
orconfig_dict
, but not both.config_dict (dict ) – The configuration as a dictionary. Specify
config_text
orconfig_dict
, but not both.
Return type
bool
Returns
True, update successful. False, update not successful.
update_labels
update_labels(labels)
Update the label enumeration.
Parameters
labels (dict ) – The label enumeration dictionary of string (label) to integer (value) pairs.
For example:
{
"background": 0,
"person": 1
}Return type
Optional
[Waitable
]Returns
update_weights
update_weights(weights_filename=None, upload_uri=None, target_filename=None, auto_delete_file=True, register_uri=None, iteration=None, update_comment=True, is_package=False)
Update the model weights from a locally stored model filename.
Uploading the model is a background process. A call to this method returns immediately.
Parameters
weights_filename (str ) – The name of the locally stored weights file to upload. Specify
weights_filename
orregister_uri
, but not both.upload_uri (str ) – The URI of the storage destination for model weights upload. The default value is the previously used URI. (Optional)
target_filename (str ) – The newly created filename in the storage destination location. The default value is the
weights_filename
value. (Optional)auto_delete_file (bool ) – Delete the temporary file after uploading (Optional)
True
- Delete (Default)False
- Do not delete
register_uri (str ) – The URI of an already uploaded weights file. The URI must be valid. Specify
register_uri
orweights_filename
, but not both.iteration (int ) – The iteration number.
update_comment (bool ) – Update the model comment with the local weights file name (to maintain provenance) (Optional)
True
- Update model comment (Default)False
- Do not update
is_package (bool ) – Mark the weights file as compressed package, usually a zip file.
Return type
str
Returns
The uploaded URI.
update_weights_package
update_weights_package(weights_filenames=None, weights_path=None, upload_uri=None, target_filename=None, auto_delete_file=True, iteration=None)
Update the model weights from locally stored model files, or from directory containing multiple files.
Uploading the model weights is a background process. A call to this method returns immediately.
Parameters
weights_filenames (list ( str ) ) – The file names of the locally stored model files. Specify
weights_filenames
, orweights_path
, but not both.weights_path (str ) – The directory path to a package. All the files in the directory will be uploaded. Specify
weights_path
orweights_filenames
, but not both.upload_uri (str ) – The URI of the storage destination for the model weights upload. The default is the previously used URI. (Optional)
target_filename (str ) – The newly created filename in the storage destination URI location. The default is the value specified in the
weights_filename
parameter. (Optional)auto_delete_file (bool ) – Delete temporary file after uploading (Optional)
True
- Delete (Default)False
- Do not delete
iteration (int ) – The iteration number.
Return type
str
Returns
The uploaded URI for the weights package.
url
property url: str
Return the url of the model file (or archived files)
Return type
str
Returns
The model file URL.
OutputModel.wait_for_uploads
classmethod wait_for_uploads(timeout=None, max_num_uploads=None)
Wait for any pending or in-progress model uploads to complete. If no uploads are pending or in-progress,
then the wait_for_uploads
returns immediately.
Parameters
timeout (float ) – The timeout interval to wait for uploads (seconds). (Optional).
max_num_uploads (int ) – The maximum number of uploads to wait for. (Optional).
Return type
None