Trains Python Client Reference Overview

This reference section provides detailed information about the Trains Python Client Package classes and their usage. This section also includes Trains Python Client Extras which are additional Trains components that require installation and configuration separate from the Trains Python Client Package. These classes and extras allow you to implement the many features of Trains for enhanced experimentation and autoML. This is in addition to our automagical capturing of experiment inputs and outputs.

Task class

Reference page: Task (Experiment) Class

Module in the trains repository: task.py

Using Trains, all Python experiment scripts that create experiments import the Task class and initialize a Task object by calling the Task.init(). This connects all the parts of the experiment and allows Trains automagically capture information.

The Task.init() method provides control over Task initialization (creation). Its parameters include the following:

  • project_name - The experiment's project. If it does not exist, it is created.
  • task_name - The experiment's name.
  • task_type - The experiment's type, including training, testing, and inference.
  • reuse_last_task_id - Optionally, force a new experiment each time the experiment runs, even if one with the same name in the project already exists.
  • output_uri - Specify a storage destination for model snapshots and artifacts
  • auto_connect_arg_parser - Enable/disable automatic argparse object parameter connection to the experiment. As an alternative, you can manually connect parameters.
  • auto_connect_frameworks - Fine control to enable/disable automatic framework connection, including specifying a dictionary enabling/disabling individual frameworks and repository detection.
  • auto_resource_monitoring - Enable/disable resource monitoring which, if enabled, appears in the Trains Web-App RESULTS tab, SCALARS sub-tab.

The Task class contains methods to manage all the parts of experiments and integrate them with Trains for tracking, storage, coding, analysis, comparison, and experiment management. Some of these methods include:

  • connect() - Connect the parts of an experiment to the experiment in Trains, including hyperparameter dictionaries, input and output models, configuration dictionaries, and class enumeration labels.
  • get_logger() - Create a logger object which you can use for explicit reporting.
  • get_task() - Get a reference to any experiment in Trains by Task Id, or task and project name.
  • register_artifact() - Store an artifact which is dynamically synchronized with Trains.
  • get_registered_artifacts() - After you register an artifact, retrieve a reference to it, manipulate the artifact in your code, and the changes are updated in Trains.
  • upload_artifact() - Upload static (one-time) artifacts (which do not synchronize with Trains).
  • get_model_config_dict() - Get the configuration as a dictionary and then easily work with it in your code.
  • set_model_config() - Set the model configuration before creating an output model so that the output model inherits the configuration properties.
  • set_model_label_enumeration() - Similar to set_model_config(), but for class label enumeration.
  • clone() - Create an editable copy of an experiment. For example, clone an experiment for hyperparameter tuning or multiple times for autoML.
  • enqueue() - Add an experiment to a queue. Similar to dequeue() above, enqueue() allows you to develop scripts which can automate your experimentation.
  • dequeue() - Remove an enqueued experiment from a queue.
  • reset() - Delete a Completed, Aborted, or Failed status experiment's output data and make it editable with status Draft.
  • set_initial_iteration() - To continue a previous experiment run, set the initial iteration (set to a non-zero).
  • get_initial_iteration() - Delete a Completed, Aborted, or Failed status experiment's output data and make it editable with status Draft.

To learn how to use some of these important Task class methods, see our Explicit Reporting, Tuning Experiments, and AutoML tutorials.

Model class

Reference page: Model Class

Module in the trains repository: model.py

Use the Model class's InputModel and OutputModel classes and methods to augment control of input models and output using methods such as:

  • InputModel.import_model() - Import a pre-trained model for your experiment.
  • InputModel.connect() - Connect the current model the Task (experiment).
  • InputModel.config_dict() - Get the input model's configuration as a dictionary.
  • InputModel.get_weights() - Download the base model.
  • OutputModel.connect() - Connect the output model to the Task (experiment).
  • OutputModel.set_upload_destination() - Specify a destination for uploading debug images.

Logger class

Reference page: Logger Class

Module in the trains repository: logger.py

Use the Logger class and methods to extend Trains automagical capturing of stdout and stderr with Trains' own explicit reporting for scalar metrics, any plot data in a variety of chart types, text messages, errors, warnings, debug messages, and uploading tables and debug images, as well as other methods.

  • Logger.current_logger()
  • Logger.report_text()
  • Logger.report_scalar()
  • Logger.report_line_plot()
  • Logger.report_scatter2d()
  • Logger.report_scatter3d()
  • Logger.report_histogram()
  • Logger.report_table()
  • Logger.report_confusion_matrix()
  • Logger.set_upload_destination()
  • Logger.report_image()

To learn how to use explicit reporting, see our Explicit Reporting tutorials.

Trains Python Client Extras

Trains Python Client Extras are components of the Trains Python Client Package which provide additional features, but are not installed when you install Trains (meaning, they are not installed when you execute, pip install trains). They are referred to as extras, because they are defined in the Trains Python Client Package's setup.py extras_require dictionary. Python package components in the extras_require dictionary require separate installation.

The Trains Python Client Extras include extras for experiment storage of model snapshots and other artifacts. The supported Cloud storage types include:

  • AWS S3
  • Google Cloud Storage
  • Azure Storage

These extras for storage also require that you add your storage bucket names, credentials, and related information to your Trains configuration file.

To install and configure any of these, follow the instructions on the Trains Python Client Extras page.

After installing and configuring, you can use the Cloud storage in your Python experiment scripts by calling the Task.init() method, and specifying the output_uri parameter.