Aim SDK

aim.sdk.repo module

class aim.sdk.repo.Repo(path, *, read_only=None, init=False)[source]

Aim repository object.

Provides methods for repositories creation/opening/cleanup. Provides APIs for accessing Runs. Provides API for querying Runs/Metrics based on a given expression.

Parameters

path (str) – Path to Aim repository.
read_only (bool, optional) – Flag for opening Repo in readonly mode. False by default.
init (bool, optional) – Flag used to initialize new Repo. False by default. Recommended to use aim init command instead.

collect_params_info()[source]

Utility function for getting run meta-parameters.

Returns: All runs meta-parameters.
Return type: dict

collect_sequence_info(sequence_types)[source]

Utility function for getting sequence names and contexts for all runs by given sequence types.

Parameters

sequence_types (tuple[str], optional) – Sequence types to get tracked sequence names/contexts for.
'metric'. (Defaults to) –

Returns

Tree of sequences and their contexts groupped by sequence type.

Return type

dict

copy_runs(run_hashes, dest_repo)[source]

Copy multiple Runs data from current aim repository to destination aim repository

Parameters

run_hashes (str) – list of Runs to be copied.
dest_repo (Repo) – destination Repo instance to copy Runs

Returns

(True, []) if all runs were copied successfully, (False, list) with list of remaining runs otherwise.

classmethod default_repo(init=False)[source]

Named constructor for default repository.

Searches nearest .aim directory from current directory to roo directory. If not found, return Repo for current directory.

Parameters: init (bool, optional) – Flag used to initialize new Repo. False by default. Recommended to use aim init command instead.
Returns: Repo object.

delete_run(run_hash)[source]

Delete Run data from aim repository

This action removes run data permanently and cannot be reverted. If you want to archive run but keep it’s data use repo.get_run(run_hash).archived = True.

Parameters: run_hash (str) – Run to be deleted.
Returns: True if run deleted successfully, False otherwise.

delete_runs(run_hashes)[source]

Delete multiple Runs data from aim repository

This action removes runs data permanently and cannot be reverted. If you want to archive run but keep it’s data use repo.get_run(run_hash).archived = True.

Parameters: run_hashes (str) – list of Runs to be deleted.
Returns: (True, []) if all runs deleted successfully, (False, list) with list of remaining runs otherwise.

classmethod exists(path)[source]

Check Aim repository existence.

Parameters: path (str) – Path to Aim repository.
Returns: True if repository exists, False otherwise.

classmethod from_path(path, read_only=None, init=False)[source]

Named constructor for Repo for given path.

Parameters

path (str) – Path to Aim repository.
read_only (bool, optional) – Flag for opening Repo in readonly mode. False by default.
init (bool, optional) – Flag used to initialize new Repo. False by default. Recommended to use aim init command instead.

Returns

Repo object.

get_run(run_hash)[source]

Get run if exists.

Parameters: run_hash (str) – Run hash.
Returns: Run object if hash is found in repository. None otherwise.

iter_runs()[source]

Iterate over Repo runs.

Yields: next Run in readonly mode .

move_runs(run_hashes, dest_repo)[source]

Move multiple Runs data from current aim repository to destination aim repository

Parameters

run_hashes (str) – list of Runs to be moved.
dest_repo (Repo) – destination Repo instance to move Runs

Returns

(True, []) if all runs were moved successfully, (False, list) with list of remaining runs otherwise.

query_audios(query='', report_mode=QueryReportMode.PROGRESS_BAR)[source]

Get audio collections satisfying query expression.

Parameters

query (str) – query expression.
report_mode (QueryReportMode, optional) – indicates report mode (0: DISABLED, 1: PROGRESS BAR, 2: PROGRESS TUPLE). QueryReportMode.PROGRESS_BAR if not specified.

Returns

Iterable for audio sequences matching query expression.

Return type

SequenceCollection

query_distributions(query='', report_mode=QueryReportMode.PROGRESS_BAR)[source]

Get distribution collections satisfying query expression.

Parameters

query (str) – query expression.
report_mode (QueryReportMode, optional) – indicates report mode (0: DISABLED, 1: PROGRESS BAR, 2: PROGRESS TUPLE). QueryReportMode.PROGRESS_BAR if not specified.

Returns

Iterable for distribution sequences matching query expression.

Return type

SequenceCollection

query_figure_objects(query='', report_mode=QueryReportMode.PROGRESS_BAR)[source]

Get Figures collections satisfying query expression.

Parameters

query (str) – query expression.
report_mode (QueryReportMode, optional) – indicates report mode (0: DISABLED, 1: PROGRESS BAR, 2: PROGRESS TUPLE). QueryReportMode.PROGRESS_BAR if not specified.

Returns

Iterable for Figure sequences matching query expression.

Return type

SequenceCollection

query_images(query='', report_mode=QueryReportMode.PROGRESS_BAR)[source]

Get image collections satisfying query expression.

Parameters

query (str) – query expression.
report_mode (QueryReportMode, optional) – indicates report mode (0: DISABLED, 1: PROGRESS BAR, 2: PROGRESS TUPLE). QueryReportMode.PROGRESS_BAR if not specified.

Returns

Iterable for image sequences matching query expression.

Return type

SequenceCollection

query_metrics(query='', report_mode=QueryReportMode.PROGRESS_BAR)[source]

Get metrics satisfying query expression.

Parameters

query (str) – query expression.
report_mode (QueryReportMode, optional) – indicates report mode (0: DISABLED, 1: PROGRESS BAR, 2: PROGRESS TUPLE). QueryReportMode.PROGRESS_BAR if not specified.

Returns

Iterable for metrics matching query expression.

Return type

SequenceCollection

query_runs(query='', paginated=False, offset=None, report_mode=QueryReportMode.PROGRESS_BAR)[source]

Get runs satisfying query expression.

Parameters

query (str, optional) – query expression. If not specified, query results will include all runs.
paginated (bool, optional) – query results pagination flag. False if not specified.
offset (str, optional) – hash of Run to skip to.
report_mode (QueryReportMode, optional) – indicates report mode (0: DISABLED, 1: PROGRESS BAR, 2: PROGRESS TUPLE). QueryReportMode.PROGRESS_BAR if not specified.

Returns

Iterable for runs/metrics matching query expression.

Return type

SequenceCollection

query_texts(query='', report_mode=QueryReportMode.PROGRESS_BAR)[source]

Get text collections satisfying query expression.

Parameters

query (str) – query expression.
report_mode (QueryReportMode, optional) – indicates report mode (0: DISABLED, 1: PROGRESS BAR, 2: PROGRESS TUPLE). QueryReportMode.PROGRESS_BAR if not specified.

Returns

Iterable for text sequences matching query expression.

Return type

SequenceCollection

classmethod rm(path)[source]

Remove Aim repository.

Parameters: path (str) – Path to Aim repository.

aim.sdk.run module

class aim.sdk.run.Run(*args, **kwargs)[source]

Run object used for tracking metrics.

Provides method track to track value and object series for multiple names and contexts. Provides dictionary-like interface for Run object meta-parameters. Provides API for iterating through tracked sequences.

Parameters

run_hash (str, optional) – Run’s hash. If skipped, generated automatically.
( (repo) – obj:`Union[Repo,str], optional): Aim repository path or Repo object to which Run object is bound. If skipped, default Repo is used.
read_only (bool, optional) – Run creation mode. Default is False, meaning Run object can be used to track metrics.
experiment (str, optional) – Sets Run’s experiment property. ‘default’ if not specified. Can be used later to query runs/sequences.
force_resume (bool, optional) – Forcefully resume stalled Run.
system_tracking_interval (int, optional) – Sets the tracking interval in seconds for system usage metrics (CPU, Memory, etc.). Set to None to disable system metrics tracking.
log_system_params (bool, optional) – Enable/Disable logging of system params such as installed packages, git info, environment variables, etc.

__delitem__(key): Remove key from run meta-params. :param key: meta-parameter path

__getitem__(key)

Get run meta-parameter by key.

Parameters: key – path to Run meta-parameter.
Returns: Collected sub-tree of Run meta-parameters.

Examples

>>> run = Run('3df703c')
>>> run['hparams']  # -> {'batch_size': 42}
>>> run['hparams', 'batch_size']  # -> 42

__setitem__(key, val)

Set Run top-level meta-parameter.

Parameters

key (str) – Top-level meta-parameter name. Use ellipsis to reset run’s all meta-parameters.
val – Meta-parameter value.

Examples

>>> run = Run('3df703c')
>>> run[...] = params
>>> run['hparams'] = {'batch_size': 42}

add_tag(value)

Add tag to run

Parameters: value (str) – Tag to add.

collect_sequence_info(sequence_types, skip_last_value=False)

Retrieve Run’s all sequences general overview.

Parameters

sequence_types – Type names of sequences for which to collect name/context pairs.
skip_last_value (bool, optional) – Boolean flag to include tracked sequence last value in
default. (sequence info. False by) –

Returns

list of sequence’s context, name and optionally last tracked value triplets.

Return type

list

dataframe(include_props=True, include_params=True)

Get run properties and params as pandas DataFrame

Parameters

include_props – (int, optional): If true, include run structured props
include_params – (int, optional): If true, include run parameters

get_audio_sequence(name, context)

Retrieve audios sequence by its name and context.

Parameters

name (str) – Tracked audios sequence name.
context (Context) – Tracking context.

Returns

Audios object if exists, None otherwise.

get_distribution_sequence(name, context)

Retrieve distributions sequence by it’s name and context.

Parameters

name (str) – Tracked distribution sequence name.
context (Context) – Tracking context.

Returns

Distributions object if exists, None otherwise.

get_figure_sequence(name, context)

Retrieve figure sequence by its name and context.

Parameters

name (str) – Tracked figure sequence name.
context (Context) – Tracking context.

Returns

Figures object if exists, None otherwise.

get_image_sequence(name, context)

Retrieve images sequence by it’s name and context.

Parameters

name (str) – Tracked image sequence name.
context (Context) – Tracking context.

Returns

Images object if exists, None otherwise.

get_log_records()

Retrieve duplicated terminal logs for a run

Returns: Sequence object if exists, None otherwise.

get_metric(name, context)

Retrieve metric sequence by it’s name and context.

Parameters

name (str) – Tracked metric name.
context (Context) – Tracking context.

Returns

Metric object if exists, None otherwise.

get_terminal_logs()

Retrieve duplicated terminal logs for a run

Returns: Logs object if exists, None otherwise.

get_text_sequence(name, context)

Retrieve texts sequence by it’s name and context.

Parameters

name (str) – Tracked text sequence name.
context (Context) – Tracking context.

Returns

Texts object if exists, None otherwise.

iter_metrics_info()

Iterator for all run metrics info.

Yields: tuples of (name, context, run) where run is the Run object itself and name, context defines Metric type sequence (with values of float and int).

iter_sequence_info_by_type(dtypes)

Iterator for run sequence infos for the given object data types

Parameters: dtypes – The objects data types list.
Yields: tuples of (name, context, run) where run is the Run object itself and name, context defines sequence for one of dtypes types.

metrics()

Get iterable object for all run tracked metrics.

Returns: Iterable for run metrics.
Return type: MetricCollection

Examples

>>> run = Run('3df703c')
>>> for metric in run.metrics():
>>>     metric.values.sparse_numpy()

remove_tag(tag_name)

Remove run tag.

Parameters: tag_name (str) – name of tag to be removed.

report_progress(*, expect_next_in=0, block=False)

Report progress for the run. Report the expected time for the next progress report.

If no progress reports are received by the expiry date (plus the grace period), the run is considered as failed.

Parameters

expect_next_in – (int, optional): The number of seconds to wait before the next progress report.
block – (bool, optional): If true, block the thread until the report is written to filesystem.

report_successful_finish(*, block=True)

Report successful finish of the run. If the run is not marked as successfully finished, it can potentially be considered as failed.

Parameters: block – (bool, optional): If true, block the thread until the report is written to filesystem.

track(value, name=None, step=None, epoch=None, *, context=None)

Main method for tracking numeric value series and object series.

Parameters

value – The tracked value.
name (str) – Tracked sequence name.
step (int, optional) – Sequence tracking iteration. Auto-incremented if not specified.
epoch (int, optional) – The training epoch.
context (dict, optional) – Sequence tracking context.

Appends the tracked value to sequence specified by name and context. Appended values should be of the same type, in other words, sequence is a homogeneous collection.

property active

Check if run is active or not.

Getter: Returns run’s active state.
Type: bool

property archived

Check is run archived or not.

Getter: Returns run’s archived state.
Setter: Archive/un-archive run.
Type: bool

property creation_time

Run object creation time [UTC] as timestamp.

Getter: Returns run creation time.

property description

Run description, set by user.

Getter: Returns run’s description.
Setter: Sets run’s description.
Type: string

property duration

Run duration in seconds (end_time - creation_time)

Getter: Returns run duration.

property end_time

Run finalization time [UTC] as timestamp.

Getter: Returns run finalization time.

property experiment

Run experiment.

Getter: Returns run’s experiment name.
Setter: Sets run’s experiment.
Type: string

property name

Run name, set by user.

Getter: Returns run’s name.
Setter: Sets run’s name.
Type: string

property tags

List of run tags.

Getter: Returns run’s tag list.

aim.sdk.objects.image

class aim.sdk.objects.image.Image(*args, **kwargs)[source]

Image object used to store image objects in Aim repository…

Parameters

( (optimize) – obj:): pillow Image object or torch.Tensor or numpy.array used to construct aim.Image.
caption (str, optional) – Optional image caption. ‘’ by default.
( – obj: str, optional): Parameter for PIL’s .save() method. ‘png’ by default.
( – obj: int, optional): Parameter for PIL’s .save() method. 85 by default.
( – obj: bool, optional): Parameter for PIL’s .save() method. False by default.
format (For more information on the) –
parameters (quality and optimize) –
documentation. (refer to PIL) –

Example of params to reduce quality of the image:: format=’jpeg’, optimize=True, quality=85

json()[source]: Dump image metadata to a dict

to_pil_image()[source]: Method to convert aim.Image to pillow Image

property caption

Image caption, set by user.

Getter: Returns image caption.
Setter: Sets image caption.
Type: string

property format

Stored image format.

Getter: Returns image format.
Type: string

property height

Stored image height.

Getter: Returns image height.
Type: string

property size

Stored image size.

Getter: Returns image (width, height) pair.
Type: string

property width

Stored image width.

Getter: Returns image width.
Type: string

aim.sdk.objects.distribution

class aim.sdk.objects.distribution.Distribution(*args, **kwargs)[source]

Distribution object used to store distribution objects in Aim repository.

Parameters

( (hist) – obj:): Array-like object of data sampled from a distribution.
bin_count (int, optional) – Optional distribution bin count for binning samples. 64 by default, max 512.
( – obj:, optional): Array-like object representing bin frequency counts. Max 512 bins allowed. samples must not be specified.
bin_range (tuple, optional) – Tuple of (start, end) bin range.

classmethod from_histogram(hist, bin_range)[source]

Create Distribution object from histogram.

Parameters

( (hist) – obj:): Array-like object representing bin frequency counts. Max 512 bins allowed.
bin_range (tuple, optional) – Tuple of (start, end) bin range.

classmethod from_samples(samples, bin_count=64)[source]

Create Distribution object from data samples.

Parameters

( (samples) – obj:): Array-like object of data sampled from a distribution.
bin_count (int, optional) – Optional distribution bin count for binning samples. 64 by default, max 512.

json()[source]: Dump distribution metadata to a dict

to_np_histogram()[source]: Return np.histogram compatible format of the distribution

property bin_count

Stored distribution bin count

Getter: Returns distribution bin_count.
Type: string

property range

Stored distribution range

Getter: Returns distribution range.
Type: List

property ranges

Stored distribution ranges

Getter: Returns distribution ranges as np.array.
Type: np.ndarray

property weights

Stored distribution weights

Getter: Returns distribution weights as np.array.
Type: np.ndarray

aim.sdk.objects.audio

class aim.sdk.objects.audio.Audio(*args, **kwargs)[source]

Audio object used to store audio objects in Aim repository..

Currently, audio formats are limited to mp3, wav, flac

Parameters

data – file path, bytes, io.BaseIO or numpy.array (only for WAV)
format (str) – Format of the audio source
rate (int) – Rate of the audio file, for WAV defaults to 22500
caption (str, optional) – Optional audio caption. ‘’ by default.

get()[source]

Reads data from the inner container and writes it to a buffer

Returns: io.BytesIO

json()[source]: Dump audio metadata to a dict

to_numpy()[source]

This method converts WAV to Numpy array. Other audio formats are not supported at this moment.

Returns: numpy array

aim.sdk.objects.text

class aim.sdk.objects.text.Text(*args, **kwargs)[source]

Text object used to store text objects in Aim repository.

Parameters: ( (text) – obj:): str object used to construct aim.Text.

aim.sdk.objects.figure

class aim.sdk.objects.figure.Figure(*args, **kwargs)[source]

Figure object can be used for storing Plotly or Matplotlib figures into Aim repository. Core functionality is based on Plotly.

Parameters: ( (obj) – obj:): plotly or matplotlib figure object.

json()[source]: Dump figure metadata to a dict

aim.sdk.sequence module

class aim.sdk.sequence.Sequence(name, context, run)[source]

Class representing single series of tracked value.

Objects series can be retrieved as Sequence regardless the object’s type, but subclasses of Sequence might provide additional functionality. Provides interface to access tracked values, steps, timestamps and epochs. Values, epochs and timestamps are accessed via aim.storage.arrayview.ArrayView interface.

classmethod allowed_dtypes()[source]

classmethod to get allowed object types for particular sequence

For example, numeric sequences a.k.a. Metric allow float and integer numbers. The base Sequence allows any value, and to indicate that, allowed_dtypes returns ‘*’.

first_step()[source]

Get sequence tracked first step.

Required to implement ranged and sliced data fetching.

last_step()[source]

Get sequence tracked last step.

Required to implement ranged and sliced data fetching.

classmethod sequence_name()[source]: classmethod to get retrieve sequence’s registered name

property epochs

Tracked epochs array as ArrayView.

Getter: Returns epochs ArrayView.

property timestamps

Tracked timestamps array as ArrayView.

Getter: Returns timestamps ArrayView.

property values

Tracked values array as ArrayView.

Getter: Returns values ArrayView.

aim.sdk.sequences.metric module

aim.sdk.sequences.image_sequence module

class aim.sdk.sequences.image_sequence.Images(name, context, run)[source]

Class representing series of Image objects or Image lists.

classmethod sequence_name()[source]: classmethod to get retrieve sequence’s registered name

aim.sdk.sequences.distribution_sequence module

class aim.sdk.sequences.distribution_sequence.Distributions(name, context, run)[source]

Class representing series of Distribution objects.

first_step()[source]

Get sequence tracked first step.

Required to implement ranged and sliced data fetching.

last_step()[source]

Get sequence tracked last step.

Required to implement ranged and sliced data fetching.

classmethod sequence_name()[source]: classmethod to get retrieve sequence’s registered name

aim.sdk.sequences.audio_sequence module

class aim.sdk.sequences.audio_sequence.Audios(name, context, run)[source]

Class representing series of Audio objects or Audio lists.

classmethod sequence_name()[source]: classmethod to get retrieve sequence’s registered name

aim.sdk.sequences.text_sequence module

class aim.sdk.sequences.text_sequence.Texts(name, context, run)[source]

Class representing series of Text objects.

classmethod sequence_name()[source]: classmethod to get retrieve sequence’s registered name

aim.sdk.sequences.figure_sequence module

class aim.sdk.sequences.figure_sequence.Figures(name, context, run)[source]

Class representing series of Plotly figure objects or Plotly lists.

first_step()[source]

Get sequence tracked first step.

Required to implement ranged and sliced data fetching.

last_step()[source]

Get sequence tracked last step.

Required to implement ranged and sliced data fetching.

classmethod sequence_name()[source]: classmethod to get retrieve sequence’s registered name

aim.sdk.sequence_collection module

class aim.sdk.sequence_collection.SequenceCollection[source]

Abstract interface for collection of tracked series/sequences.

Typically represents sequences of a same run or sequences matching given query expression.

abstract iter()[source]

Get Sequence iterator for collection’s sequences.

Yields: Next sequence object based on implementation.

abstract iter_runs()[source]

Get SequenceCollection iterator for collection’s runs.

Yields: Next run’s SequenceCollection based on implementation.

class aim.sdk.sequence_collection.SingleRunSequenceCollection(run, seq_cls=<class 'aim.sdk.sequence.Sequence'>, query='', runs_proxy_cache=None, timezone_offset=0)[source]

Bases: SequenceCollection

Implementation of SequenceCollection interface for a single Run.

Method iter() returns Sequence iterator which yields Sequence matching query from run’s sequences. Method iter_runs() raises StopIteration, since the collection is bound to a single Run.

Parameters

run (Run) – Run object for which sequences are queried.
seq_cls (type) – The collection’s sequence class. Sequences not matching to seq_cls.allowed_dtypes will be skipped. Sequence by default, meaning all sequences will match.
query (str, optional) – Query expression. If specified, method iter() will return iterator for sequences matching the query. If not, method iter() will return iterator for run’s all sequences.

class aim.sdk.sequence_collection.QuerySequenceCollection(repo, seq_cls=<class 'aim.sdk.sequence.Sequence'>, query='', report_mode=QueryReportMode.PROGRESS_BAR, timezone_offset=0)[source]

Bases: SequenceCollection

Implementation of SequenceCollection interface for repository’s sequences matching given query.

Method iter() returns Sequence iterator, which yields Sequence matching query from currently iterated run’s sequences. Once there are no sequences left in current run, repository’s next run is considered. Method iter_runs() returns SequenceCollection iterator for repository’s runs.

Parameters

repo (Repo) – Aim repository object.
seq_cls (type) – The collection’s sequence class. Sequences not matching to seq_cls.allowed_dtypes will be skipped. Sequence by default, meaning all sequences will match.
query (str, optional) – Query expression. If specified, method iter() will skip sequences not matching the query. If not, method iter() will return iterator for all sequences in repository (that’s a lot of sequences!).

class aim.sdk.sequence_collection.QueryRunSequenceCollection(repo, seq_cls=<class 'aim.sdk.sequence.Sequence'>, query='', paginated=False, offset=None, report_mode=QueryReportMode.PROGRESS_BAR, timezone_offset=0)[source]

Bases: SequenceCollection

Implementation of SequenceCollection interface for repository’s runs matching given query.

Method iter() returns Sequence iterator which yields Sequence for current run’s all sequences. Method iter_runs() returns SequenceCollection iterator from repository’s runs matching given query.

Parameters

repo (Repo) – Aim repository object.
seq_cls (type) – The collection’s sequence class. Sequences not matching to seq_cls.allowed_dtypes will be skipped. Sequence by default, meaning all sequences will match.
query (str, optional) – Query expression. If specified, method iter_runs() will skip runs not matching the query. If not, method iter_run() will return SequenceCollection iterator for all runs in repository.