Logger Module

class trains.logger.Logger(private_task)

The Logger class is the Trains console log and metric statistics interface, and contains methods for explicit reporting.

Explicit reporting extends Trains automagical capturing of inputs and output. Explicit reporting methods include scalar plots, line plots, histograms, confusion matrices, 2D and 3D scatter diagrams, text logging, tables, and image uploading and reporting.

In the Trains Web-App (UI), Logger output appears in the RESULTS tab, LOG, SCALARS, PLOTS, and DEBUG IMAGES sub-tabs. When you compare experiments, Logger output appears in the comparisons.

Warning

Do not construct Logger objects directly.

You must get a Logger object before calling any of the other Logger class methods by calling Task.get_logger() or Logger.current_logger().

classmethod current_logger()

Get the Logger object for the main execution Task, the current running Task, if one exists. If no Logger object exists, current_logger() creates one and returns it. Therefore, you can call this method from anywhere in the code.

logger = Logger.current_logger()
Returns

The Logger object (a singleton) for the current running Task.

Return type

Logger object

report_text(msg, level=20, print_console=True, *args, **_)

For explicit reporting, print text to the log. Optionally, print a log level and print to the console.

For example:

logger.report_text('log some text', level=logging.DEBUG, print_console=False)

You can view the reported text in the Trains Web-App (UI), RESULTS tab, LOG sub-tab.

Parameters
  • msg (str) – The text to log.

  • level (int) – The log level from the Python logging package. The default value is logging.INFO.

  • print_console (bool) –

    In addition to the log, print to the console?

    The values are:

    • True - Print to the console. (Default)

    • False - Do not print to the console.

report_scalar(title, series, value, iteration)

For explicit reporting, plot a scalar series.

For example, plot a scalar series:

scalar_series = [random.randint(0,10) for i in range(10)]
logger.report_scalar(title='scalar metrics','series', value=scalar_series[iteration], iteration=0)

You can view the scalar plots in the Trains Web-App (UI), RESULTS tab, SCALARS sub-tab.

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

  • series (str) – The title of the series.

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

  • iteration (int) – The iteration number. Iterations are on the x-axis.

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

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

For example:

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

You can view the vectors plots in the Trains Web-App (UI), RESULTS tab, PLOTS sub-tab.

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

  • series (str) – The title of the series.

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

  • iteration (int) – The iteration number. Each iteration creates another plot.

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

  • xlabels (list(str)) – 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 (str) – The x-axis title. (Optional)

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

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

For explicit reporting, plot a (stacked) histogram.

For example:

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

You can view the reported histograms in the Trains Web-App (UI), RESULTS tab, PLOTS sub-tab.

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

  • series (str) – The title of the series.

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

  • iteration (int) – The iteration number. Each iteration creates another plot.

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

  • xlabels (list(str)) – 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 (str) – The x-axis title. (Optional)

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

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

For explicit report, report a table plot.

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

  • table_plot - Pandas DataFrame

  • 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'])

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

You can view the reported tables in the Trains Web-App (UI), RESULTS tab, PLOTS sub-tab.

Parameters
  • title (str) – The title of the table.

  • series (str) – The title of the series.

  • iteration (int) – The iteration number.

  • table_plot (pandas.DataFrame) – The output table plot object

  • csv (str) – path to local csv file

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

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

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

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

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

  • iteration (int) – The iteration number.

  • 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.

report_scatter2d(title, series, scatter, iteration, xaxis=None, yaxis=None, labels=None, mode='lines', comment=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))))
logger.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 the report_scatter2d() method:

scatter2d_1 = np.hstack((np.atleast_2d(np.arange(0, 10)).T, np.random.randint(10, size=(10, 1))))
logger.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))))
logger.report_scatter2d("example_scatter', "series_2', iteration=1, scatter=scatter2d_2,
     xaxis="title x', yaxis="title y")
Parameters
  • title (str) – The title of the plot.

  • series (str) – The title of the series.

  • scatter – The scatter data.

  • iteration (int) – The iteration number. To set an initial iteration, for example to continue a previously

  • 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.

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

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

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

  • series (str) – The title of the series.

  • list] scatter (Union[numpy.ndarray,) – The scatter data.

  • iteration (int) – The iteration number.

  • 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))
logger.report_scatter3d(title='example_scatter_3d', series='series_xyz', iteration=1, scatter=scatter3d,
     xaxis='title x', yaxis="title y', zaxis="title z")
Parameters
  • 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.

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

For explicit reporting, plot a heat-map matrix.

For example:

confusion = np.random.randint(10, size=(10, 10))
logger.report_confusion_matrix("example confusion matrix', "ignored', iteration=1, matrix=confusion,
     xaxis='title X', yaxis='title Y")
Parameters
  • title (str) – The title of the plot.

  • series (str) – The title of the series.

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

  • iteration (int) – The iteration number.

  • 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)

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

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

For explicit reporting, plot a confusion matrix.

Note

report_matrix() is the same as report_confusion_matrix().

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

  • series (str) – The title of the series.

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

  • iteration (int) – The iteration number.

  • 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)

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

For explicit reporting, report a 3d surface plot.

Note

The report_surface() method plots the same data as report_confusion_matrix(), but presents the data as a surface diagram not a confusion matrix.

surface_matrix = np.random.randint(10, size=(10, 10))
logger.report_surface("example surface', "series', iteration=0, matrix=surface_matrix,
     xaxis='title X', yaxis='title Y', zaxis="title Z")
Parameters
  • title (str) – The title of the plot.

  • series (str) – The title of the series.

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

  • iteration (int) – The iteration number.

  • 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.

report_image(title, series, iteration, local_path=None, image=None, matrix=None, max_image_history=None, delete_after_upload=False, url=None)

For explicit reporting, report an image and upload its contents.

The report_image() method uploads the image to a preconfigured bucket (see setup_upload()) with a key (filename) describing the task ID, title, series and iteration.

For example:

matrix = np.eye(256, 256, dtype=np.uint8)*255
matrix = np.concatenate((np.atleast_3d(matrix), np.zeros((256, 256, 2), dtype=np.uint8)), axis=2)
logger.report_image("test case', "image color red', iteration=1, image=m)

image_open = Image.open(os.path.join("<image_path>', "<image_filename>"))
logger.report_image("test case', "image PIL', iteration=1, image=image_open)

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

Parameters
  • title (str) – The title of the image.

  • series (str) – The title of the series of this image.

  • iteration (int) – The iteration number.

  • local_path (str) – A path to an image file.

  • url (str) – A URL for the location of a pre-uploaded image.

  • image (numpy.ndarray, PIL.Image.Image) – Image data (RGB).

  • matrix (3D numpy.ndarray) –

    Image data (RGB).

    Note

    The matrix paramater is deprecated. Use the image parameters.

  • max_image_history (int) – The maximum number of images to store per metric/variant combination. For an unlimited number, use a negative value. The default value is set in global configuration (default=``5``).

  • delete_after_upload (bool) –

    After the upload, delete the local copy of the image?

    The values are:

    • True - Delete after upload.

    • False - Do not delete after upload. (Default)

set_default_upload_destination(uri)

Set the destination storage URI (for example, S3, Google Cloud Storage, a file path) for uploading debug images.

The images are uploaded separately. A link to each image is reported.

Note

Credentials for the destination storage are specified in the Trains configuration file, ~/trains.conf.

Parameters

uri (str) – example: ‘s3://bucket/directory/’ or ‘file:///tmp/debug/’

Returns

bool

The values are:

  • True - The destination scheme is supported (for example, s3://, file://, or gc://).

  • False - The destination scheme is not supported.

get_default_upload_destination()

Get the destination storage URI (for example, S3, Google Cloud Storage, a file path) for uploading debug images (see the set_default_upload_destination() method).

Returns

The default upload destination URI.

For example, s3://bucket/directory/ or file:///tmp/debug/.

Return type

str

flush()

Flush cached reports and console outputs to backend.

Returns

bool

The values are:

  • True - Successfully flushed the cache.

  • False - Failed.

get_flush_period()

Get the Logger flush period.

Returns

The logger flush period in seconds.

Return type

int

set_flush_period(period)

Set the logger flush period.

Parameters

period (float) – The period to flush the logger in seconds. To set no periodic flush, specify None or 0.

report_image_and_upload(title, series, iteration, path=None, matrix=None, max_image_history=None, delete_after_upload=False)

Warning

The report_image_and_upload() method is deprecated, but currently maintained for backwards compatibility. Use the report_image() method.

classmethod tensorboard_auto_group_scalars(group_scalars=False)

Group together TensorBoard scalars that do not have a title, or assign a title/series with the same tag.

Parameters

group_scalars (bool) –

Group TensorBoard scalars without a title?

The values are:

  • True - Scalars without specific titles are grouped together in the “Scalars” plot, preserving backward compatibility with Trains automagical behavior.

  • False - TensorBoard scalars without titles get a title/series with the same tag. (Default)

classmethod tensorboard_single_series_per_graph(single_series=False)

Group TensorBoard scalar series together or in separate plots.

Parameters

single_series (bool) –

Group TensorBoard scalar series together?

The values are:

  • True - Generate a separate plot for each TensorBoard scalar series.

  • False - Group the TensorBoard scalar series together in the same plot. (Default)