diff --git a/README.md b/README.md index 1488d88b..adc26810 100644 --- a/README.md +++ b/README.md @@ -25,12 +25,12 @@ your experimentation logs, outputs, and data to one centralized server. * Git repository, branch, commit id, entry point and local git diff * Python environment (including specific packages & versions) -* StdOut and StdErr +* stdout and stderr * Resource Monitoring (CPU/GPU utilization, temperature, IO, network, etc.) * Hyper-parameters * ArgParser for command line parameters with currently used values * Explicit parameters dictionary -* Tensorflow Defines (absl-py) + * Tensorflow Defines (absl-py) * Initial model weights file * Model snapshots * Tensorboard/TensorboardX scalars, metrics, histograms, images (with audio coming soon) @@ -39,8 +39,7 @@ your experimentation logs, outputs, and data to one centralized server. * Seamless integration (including version control) with **Jupyter Notebook** and [*PyCharm* remote debugging](https://github.com/allegroai/trains-pycharm-plugin) -**Detailed overview of TRAINS offering and system design can be found [here](https://github.com/allegroai/trains/blob/master/docs/brief.md).** - +**Additionally, log data explicitly using [TRAINS Explicit Logging](https://github.com/allegroai/trains/blob/master/docs/logger.md).** ## Using TRAINS diff --git a/docs/faq.md b/docs/faq.md index ec613877..db0954b2 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -51,8 +51,7 @@ scikit-learn TRAINS API -[How can I use the TRAINS API to fetch data?](#api) - +* [How can I use the TRAINS API to fetch data?](#api) ## General Information @@ -92,23 +91,7 @@ export TRAINS_API_HOST="http://localhost:8008" ### How can I track OS environment variables with experiments? -Set the OS environment variable `TRAINS_LOG_ENVIRONMENT` to either a list of environment variables to track, a wildcard for all environment variables, -or unset it with no value and TRAINS does not log environment variables. - -For example, to log the `PWD` and `PYTHONPATH` environment variables: -```bash -$ export TRAINS_LOG_ENVIRONMENT="PWD,PYTHONPATH" -``` - -For example, to log all environment variables: -```bash -$ export TRAINS_LOG_ENVIRONMENT="*" -``` - -For example, do not log any environment variables (the default): -```bash -$ export TRAINS_LOG_ENVIRONMENT= -``` +​Set the OS environment variable `TRAINS_LOG_ENVIRONMENT` with the variables you need track. See [Specifying Environment Variables to Track](https://github.com/allegroai/trains/blob/master/docs/logger.md#specifying-environment-variables-to-track). ## Models @@ -132,10 +115,10 @@ Task.current_task().set_model_label_enumeration( {"label": int(0), } ) ### Can I store the model configuration file as well? -Yes! Use the `Task.set_model_design()` method: +Yes! Use the `Task.set_model_config()` method: ```python -Task.current_task().set_model_design("a very long text with the configuration file's content") +Task.current_task().set_model_config("a very long text with the configuration file's content") ``` ### I am training multiple models at the same time, but I only see one of them. What happened? @@ -170,13 +153,7 @@ If you still don't care, just ignore this message - it is merely a warning. ### I do not use Argparser for hyper-parameters. Do you have a solution? -Yes! TRAINS supports using a Python dictionary for hyper-parameter logging. Just use: - -```python -parameters_dict = Task.current_task().connect(parameters_dict) -``` - -From this point onward, not only are the dictionary key/value pairs stored as part of the experiment, but any changes to the dictionary will be automatically updated in the task's information. +Yes! TRAINS supports [logging an experiment parameter dictionary](https://github.com/allegroai/trains/blob/master/docs/logger.md#logging-an-experiment-parameter-dictionary). ### I noticed that all of my experiments appear as `Training`. Are there other options? @@ -260,28 +237,7 @@ Task.current_task().get_logger().report_vector( ### I want to add more graphs, not just with Tensorboard. Is this supported? -Yes! Use a [Logger](https://github.com/allegroai/trains/blob/master/trains/logger.py) object. An instance can be always be retrieved using the `Task.current_task().get_logger()` method: - -```python -# Get a logger object -logger = Task.current_task().get_logger() - -# Report some scalar -logger.report_scalar("loss", "classification", iteration=42, value=1.337) -``` - -#### **TRAINS supports:** - -* Scalars -* Plots -* 2D/3D Scatter Diagrams -* Histograms -* Surface Diagrams -* Confusion Matrices -* Images -* Text logs - -For a more detailed example, see [here](https://github.com/allegroai/trains/blob/master/examples/manual_reporting.py). +Yes! Use the [Logger](https://github.com/allegroai/trains/blob/master/trains/logger.py) module. For more information, see [TRAINS Explicit Logging](https://github.com/allegroai/trains/blob/master/docs/logger.md). ## Git and Storage diff --git a/docs/logger.md b/docs/logger.md new file mode 100644 index 00000000..9fd01fef --- /dev/null +++ b/docs/logger.md @@ -0,0 +1,1518 @@ +# TRAINS Explicit Logging + +Using the **TRAINS** [Logger](https://github.com/allegroai/trains/blob/master/trains/logger.py) module and other **TRAINS** features, you can explicitly log any of the following: + +* Report graphs and images + * [Scalar metrics](#scalar-metrics) + * [Histograms](#histograms) + * [Line plots](#line-plots) + * [2D scatter diagrams](#2d-scatter-diagrams) + * [3D scatter diagrams](#3d-scatter-diagrams) + * [Confusion matrices](#confusion-matrices) + * [Surface diagrams](#surface-diagrams) + * [Images](#images) + * [Files](#files) + +* Track hyper-parameters and OS environment variables + * Logging experiment parameter [dictionaries](#logging-experiment-parameter-dictionaries) + * Specifying [environment variables](#specifying-environment-variables-to-track) to track + +* Message logging + * [Debugging messages](#debugging-messages) + * [Informational messages](#informational-messages) + * [Warnings](#warnings) + * [General errors](#general-errors) + * [Critial errors](#critical-errors) + * [Fatal errors](#fatal-errors) + * [Console and logger messages](#console-and-logger-messages) + * [Reporting text without formatting](#reporting-text-without-formatting) + +Additionally, the **TRAINS** Logger module provides methods that allow you to do the following: + + * Get the [current logger]() + * Overrride the TRAINS configuration file with a [default upload destination]() for images and files + +## Graphs and Images + +### Scalar Metrics + +Use to report scalar metrics by iteration as a line plot. + +First [get the current logger](#get-the-current-logger) and then use it (see an [example script](https://github.com/allegroai/trains/blob/master/examples/manual_reporting.py)) with the following method. + +**Method**: + +```python +def report_scalar(self, title, series, value, iteration) +``` + +**Arguments**: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Parameter + Type + Description + Mandatory +
iteration + integer + The iteration number (x-axis). + Yes +
series + string + The data series label. + Yes +
title + string + The plot title. + Yes +
value + float + The scalar metric data value (y-axis). + Yes +
+ +### Histograms + +Use to report any data by iteration as a histogram. + +First [get the current logger](#get-the-current-logger) and then use it (see an [example script](https://github.com/allegroai/trains/blob/master/examples/manual_reporting.py)) with the following method. + +**Method**: + +```python +def report_histogram(self, title, series, values, iteration, labels=None, xlabels=None) +``` + +**Arguments**: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Parameter + Type + Description + Mandatory +
iteration + integer + The iteration number (x-axis). + Yes +
series + string + The data series label. + Yes +
title + string + The plot title. + Yes +
values + Either: +
    +
  • list of float +
    • +
  • numpy array +
    • +
+ 		The histogram data values (y-axis). + Yes +
labels + list of strings + Labels for each bar group in the histogram. The default value is None. + No +
xlabels + list of strings + Labels for each bucket in the histogram. Each label in the xlabels list corresponds to a value in the values list (or numpy array). The default value is None. + No +
+ + +### Line Plots + +Use to report any data by iteration as a single or multiple line plot. + +First [get the current logger](#get-the-current-logger) and then use it (see an [example script](https://github.com/allegroai/trains/blob/master/examples/manual_reporting.py)) with the following method. + +**Method**: + +```python +def report_line_plot(self, title, series, iteration, xaxis, yaxis, mode='lines', reverse_xaxis=False, comment=None) +``` + +**Arguments**: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Parameter + Type + Description + Mandatory +
iteration + integer + The iteration number (x-axis). + Yes +
series + LineSeriesInfo + One (single line plot) or more (multiple line plot) series of data. + Yes +
title + string + The plot title. + Yes +
comment + string + Any text (e.g., subtitle or other comment) which displays under the plot title. The default value is None. + No +
mode + string + Type of line plot. The values are: +
    +
  • lines - lines connecting data points (default) +
    • +
  • markers - markers for each data point +
    • +
  • lines+markers - lines and markers +
    • +
+ 		No +
reverse_xaxis + boolean + Indicates whether to display the x-axis values in ascending or descending order. The values are: +
    +
  • True - descending order +
    • +
  • False - ascending order (default) +
    • +
+ 		No +
xaxis + string + x-axis title. + No +
yaxis + string + y-axis title. + No +
+ + +### 2D Scatter Diagrams + +Use to report any vector data as a 2D scatter diagram. + +First [get the current logger](#get-the-current-logger) and then use it (see an [example script](https://github.com/allegroai/trains/blob/master/examples/manual_reporting.py)) with the following method. + +**Method**: + +```python +def report_scatter2d(self, title, series, scatter, iteration, xaxis=None, yaxis=None, labels=None, mode='lines', comment=None) +``` + +**Arguments**: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Parameter + Type + Description + Mandatory +
iteration + integer + The iteration number (x-axis). + Yes +
scatter + Either: +
    +
  • list of (pairs of x, y) +
    • +
  • ndarray +
    • +
+ 		The scatter data. For example, a list of pairs in the form: [(x1,y1),(x2,y2),(x3,y3),...]. + Yes +
series + string + The data series label. + Yes +
title + string + The plot title. + Yes +
comment + string + Any text (e.g., subtitle or other comment) which displays under the plot title. The default value is None. + No +
labels + list of strings + Label text per data point in the scatter diagram. The default value is None. + No +
mode + string + Type of 2D scatter diagram. The values are: +
    +
  • lines - lines connecting data points (default) +
    • +
  • markers - markers for each data point +
    • +
  • lines+markers - lines and markers +
    • +
+ 		No +
xaxis + string + x-axis title. The default value is None. + No +
yaxis + string + y-axis title. The default value is None. + No +
+ + +### 3D Scatter Diagrams + +Use to report any array data as a 3D scatter diagram. + +First [get the current logger](#get-the-current-logger) and then use it (see an [example script](https://github.com/allegroai/trains/blob/master/examples/manual_reporting.py)) with the following method. + +**Method**: + +```python +def report_scatter3d(self, title, series, scatter, iteration, labels=None, mode='markers', fill=False, comment=None) +``` + +**Argument**: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Parameter + Type + Description + Mandatory +
iteration + integer + The iteration number (x-axis). + Yes +
scatter + Either: +
    +
  • list of (pairs of x, y, z) +
    • +
  • ndarray +
    • +
  • list of series [[(x1,y1,z1)...]] +
    • +
+ 		The scatter data. For example, a list of series in the form: + [[(x1,y1,z1),(x2,y2,z2),...],[(x3,y3,z3),(x4,y4,z4),...],[(x5,y5,z5),(x6,y6,z6),...]] + Yes +
series + string + The data series label. + Yes +
title + string + The plot title. + Yes +
comment + string + Any text (e.g., subtitle or other comment) which displays under the plot title. The default value is None. + No +
fill + boolean + Indicates whether to fill the area under the scatter diagram. The values are: +
    +
  • True - fill +
    • +
  • False - do not fill (default) +
    • +
+ 		No +
labels + list of strings + Label text per data point in the scatter. The default value is None. + No +
mode + string + Type of 3D scatter diagram. The values are: +
    +
  • lines +
    • +
  • markers +
    • +
  • lines+markers +
    • +
+ The default values is lines. + 		No +
+ + +### Confusion Matrices + +Use to report a heat-map matrix as a confusion matrix. You can also plot a heat-map as a [surface diagram](#surface-diagrams). + +First [get the current logger](#get-the-current-logger) and then use it (see an [example script](https://github.com/allegroai/trains/blob/master/examples/manual_reporting.py)) with the following method. + +**Method**: + +```python +def report_confusion_matrix(self, title, series, matrix, iteration, xlabels=None, ylabels=None, comment=None) +``` + +**Arguments**: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Parameter + Type + Description + Mandatory +
iteration + integer + The iteration number (x-axis). + Yes +
matrix + ndarray + A heat-map matrix. + Yes +
series + string + The data series label. + Yes +
title + string + The plot title. + Yes +
xlabels + list of strings + Label per column of the matrix. The default value is None. + No +
ylabels + list of strings + Label per row of the matrix. The default value is None. + No +
+ + +### Surface Diagrams + +Use to plot a heat-map matrix as a surface diagram. You can also plot a heat-map as a [confusion matrix](#confusion-matrices). + +First [get the current logger](#get-the-current-logger) and then use it (see an [example script](https://github.com/allegroai/trains/blob/master/examples/manual_reporting.py)) with the following method. + +**Method**: + +```python +def report_surface(self, title, series, matrix, iteration, xlabels=None, ylabels=None, xtitle=None, ytitle=None, camera=None, comment=None) +``` + +**Arguments**: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Parameter + Type + Description + Mandatory +
iteration + integer + The iteration number (x-axis). + Yes +
matrix + ndarray + A heat-map matrix. + Yes +
series + string + The data series label. + Yes +
title + string + The plot title. + Yes +
camera + tuple + The position of the camera as (x, y, x), if applicable. + No +
comment + string + Any text (e.g., subtitle or other comment) which displays under the plot title. The default value is None. + No +
xlabels + list of strings + Label per column of the matrix. The default value is None. + No +
xtitle + string + x-axis title. + No +
ylabels + list of strings + Label per row of the matrix. The default value is None. + No +
ytitle + string + y-axis title. + No +
+ +### Images + +Use to report an image and upload its contents to the bucket specified in the **TRAINS** configuration file, +or a [a default upload destination](#set-default-upload-destination), if you set a default. + +First [get the current logger](#get-the-current-logger) and then use it (see an [example script](https://github.com/allegroai/trains/blob/master/examples/manual_reporting.py)) with the following method. + +**Method**: + +```python +def report_image_and_upload(self, title, series, iteration, path=None, matrix=None, max_image_history=None, delete_after_upload=False) +``` + +**Arguments**: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Parameter + Type + Description + Mandatory +
iteration + integer + The iteration number. + Yes +
series + string + The label of the series. + Yes +
title + string + The title of the image. + Yes +
delete_after_upload + boolean + Indicates whether to delete the local copy of the file after uploading it. The values are: +
    +
  • True - delete +
    • +
  • False - do not delete (default) +
    • +
+ 		No +
matrix + ndarray + A 3D numpy.ndarray object containing image data (RGB). If path is not specified, then matrix is required. The default values is None. + No +
max_image_history + integer + The maximum number of images to store per metric / variant combination. For an unlimited number of images to store, specify a negative number. + The default value which is set in the global configuration is 5. + No +
path + string + The path of the image file. If matrix is not specified, then path is required. The default values is None. + No +
+ +### Files + +Use to upload a file and report a link to it. The file contents is uploaded to the bucket specified in the **TRAINS** configuration file, +or a [a default upload destination](#set-default-upload-destination), if you set a default. + +First [get the current logger](#get-the-current-logger) and then use it (see an [example script](https://github.com/allegroai/trains/blob/master/examples/manual_reporting.py)) with the following method. + +**Method**: + +```python +def report_file_and_upload(self, title, series, iteration, path=None, max_file_history=None, + delete_after_upload=False) +``` + +**Arguments**: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Parameter + Type + Description + Mandatory +
iteration + integer + The iteration number. + Yes +
series + string + The label of the series. + Yes +
title + string + The title of the image. + Yes +
delete_after_upload + boolean + Indicates whether to delete the local copy of the file after uploading it. The values are: +
    +
  • True - delete +
    • +
  • False - do not delete (default) +
    • +
+ 		No +
max_file_history + integer + The maximum number of images to store per metric / variant combination. For an unlimited number of files to store, specify a negative number. + The default value which is set in the global configuration is 5. + No +
path + string + The path of the file to upload. + No +
+ +## Hyper-parameters and Environment Variables + +### Logging Experiment Parameter Dictionaries + +In order for **TRAINS** to log a dictionary of parameters, use the `Task.connect` method. + +For example, to log the hyper-parameters learning_rate, batch_size, display_step, model_path, n_hidden_1, and n_hidden_2: + +```python +# Create a dictionary of parameters +parameters_dict = { 'learning_rate': 0.001, 'batch_size': 100, 'display_step': 1, + 'model_path': "/tmp/model.ckpt", 'n_hidden_1': 256, 'n_hidden_2': 256 } + +# Connect the dictionary to your TRAINS Task +parameters_dict = Task.current_task().connect(parameters_dict) +``` + +### Specifying Environment Variables to Track + +By setting the `TRAINS_LOG_ENVIRONMENT` environment variable, make **TRAINS** log either: + +* All environment variables + + export TRAINS_LOG_ENVIRONMENT="*" + +* Specific environment variables + + For example, log `PWD` and `PYTHONPATH` + + export TRAINS_LOG_ENVIRONMENT="PWD,PYTHONPATH" + +* No environment variables + + export TRAINS_LOG_ENVIRONMENT= + +## Logging Messages + +Use the methods in this section to log various types of messages. The method name describes the type of message. + +### Debugging Messages + +**Method**: + +```python +def debug(self, msg, *args, **kwargs) +``` + +First [get the current logger](#get-the-current-logger) and then use it (see an [example script](https://github.com/allegroai/trains/blob/master/examples/manual_reporting.py)) with the following method. + +**Arguments**: + + + + + + + + + + + + + + + + + +
Parameter + Type + Description + Mandatory +
msg + string + The text to log. + Yes +
+ +### Informational Messages + +**Method**: + +```python +def info(self, msg, *args, **kwargs) +``` + +First [get the current logger](#get-the-current-logger) and then use it (see an [example script](https://github.com/allegroai/trains/blob/master/examples/manual_reporting.py)) with the following method. + +**Arguments**: + + + + + + + + + + + + + + + + + +
Parameter + Type + Description + Mandatory +
msg + string + The text to log. + Yes +
+ +### Warnings + +**Method**: + +```python +def warn(self, msg, *args, **kwargs) +``` + +First [get the current logger](#get-the-current-logger) and then use it (see an [example script](https://github.com/allegroai/trains/blob/master/examples/manual_reporting.py)) with the following method. + +**Arguments**: + + + + + + + + + + + + + + + + + + +
Parameter + Type + Description + Mandatory +
msg + string + The text to log. + Yes +
+ +### General Errors + +**Method**: + +```python +def error(self, msg, *args, **kwargs) +``` + +First [get the current logger](#get-the-current-logger) and then use it (see an [example script](https://github.com/allegroai/trains/blob/master/examples/manual_reporting.py)) with the following method. + +**Arguments**: + + + + + + + + + + + + + + + + + +
Parameter + Type + Description + Mandatory +
msg + string + The text to log. + Yes +
+ +### Critical Errors + +**Method**: + +```python +def critical(self, msg, *args, **kwargs) +``` + +First [get the current logger](#get-the-current-logger) and then use it (see an [example script](https://github.com/allegroai/trains/blob/master/examples/manual_reporting.py)) with the following method. + +**Arguments**: + + + + + + + + + + + + + + + + + +
Parameter + Type + Description + Mandatory +
msg + string + The text to log. + Yes +
+ +### Fatal Errors + +**Method**: + +```python +def fatal(self, msg, *args, **kwargs) +``` + +First [get the current logger](#get-the-current-logger) and then use it (see an [example script](https://github.com/allegroai/trains/blob/master/examples/manual_reporting.py)) with the following method. + +**Arguments**: + + + + + + + + + + + + + + + + + +
Parameter + Type + Description + Mandatory +
msg + string + The text to log. + Yes +
+ +### Console and Logger Messages + +**Method**: + +```python +def console(self, msg, level=logging.INFO, omit_console=False, *args, **kwargs) +``` + +First [get the current logger](#get-the-current-logger) and then use it (see an [example script](https://github.com/allegroai/trains/blob/master/examples/manual_reporting.py)) with the following method. + +**Arguments**: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Parameter + Type + Description + Mandatory +
msg + string + The text to log. + Yes +
level + string + The log level. The values are: +
    +
  • logging.DEBUG +
    • +
  • logging.INFO +
    • +
  • logging.WARNING +
    • +
  • logging.ERROR +
    • +
  • logging.FATAL +
    • +
  • logging.CRITICAL +
    • +
+ 		No +
omit_console + boolean + Indicates whether to send the message to the log only. The values are: +
    +
  • True - send the message to the log only +
    • +
  • False - send the message to the console and the log +
    • +
+ 		No +
+ +### Reporting Text Without Formatting + +**Method**: + +```python +def report_text(self, msg, level=logging.INFO, print_console=False, *args, **_) +``` + +First [get the current logger](#get-the-current-logger) and then use it (see an [example script](https://github.com/allegroai/trains/blob/master/examples/manual_reporting.py)) with the following method. + +**Arguments**: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Parameter + Type + Description + Mandatory +
msg + string + The text to log. + Yes +
level + string + The log level. The values are: +
    +
  • logging.DEBUG +
    • +
  • logging.INFO +
    • +
  • logging.WARNING +
    • +
  • logging.ERROR +
    • +
  • logging.FATAL +
    • +
  • logging.CRITICAL +
    • +
+ 		No +
print_console + boolean + Indicates whether to log to the console, in addition to the log. The values are: +
    +
  • True - print to the console and log +
    • +
  • False - print to the log, only (default) +
    • +
+ 		No +
+ +## Logger Object and Storage Methods + +### Get the Current Logger + +Use to return a reference to the current logger object. + +**Method**: + +```python +def current_logger(cls) +``` + +**Arguments**: + +None. + +### Set Default Upload Destination + +Use to specify the default destination storage location used for uploading images. +Images are uploaded and a link to the image is reported. + +Credentials for the storage location are in the global configuration file (for example, on Linux, ~/trains.conf). + +**Method**: + +```python +def set_default_upload_destination(self, uri) +``` + +**Arguments**: + + + + + + + + + + + + + + + + + + +
Parameter + Type + Description + Mandatory +
uri + string + The destination storage location, for example s3://bucket/directory/ or file:///tmp/debug/. + Yes +
+ diff --git a/trains/backend_interface/setupuploadmixin.py b/trains/backend_interface/setupuploadmixin.py index d21f79ed..f4ed9497 100644 --- a/trains/backend_interface/setupuploadmixin.py +++ b/trains/backend_interface/setupuploadmixin.py @@ -12,6 +12,7 @@ class SetupUploadMixin(object): self, bucket_name, host=None, access_key=None, secret_key=None, region=None, multipart=True, https=True): """ Setup upload options (currently only S3 is supported) + :param bucket_name: AWS bucket name :type bucket_name: str :param host: Hostname. Only required in case a Non-AWS S3 solution such as a local Minio server is used) diff --git a/trains/logger.py b/trains/logger.py index d64ee187..08a23aca 100644 --- a/trains/logger.py +++ b/trains/logger.py @@ -53,7 +53,7 @@ class Logger(object): This is how we send graphs/plots/text to the system, later we can compare the performance of different tasks. - **Usage: Task.get_logger()** + **Usage:** :func:`Logger.current_logger` or :func:`Task.get_logger` """ SeriesInfo = SeriesInfo _stdout_proxy = None @@ -64,7 +64,7 @@ class Logger(object): """ **Do not construct Logger manually!** - please use Logger.current_logger() + please use :func:`Logger.current_logger` """ assert isinstance(private_task, _Task), \ 'Logger object cannot be instantiated externally, use Logger.current_logger()' @@ -139,7 +139,7 @@ class Logger(object): """ Return a logger object for the current task. Can be called from anywhere in the code - :return Singleton Logger object for the current running task + :return: Singleton Logger object for the current running task """ from .task import Task task = Task.current_task() diff --git a/trains/task.py b/trains/task.py index 047824cd..946ea798 100644 --- a/trains/task.py +++ b/trains/task.py @@ -50,20 +50,20 @@ class Task(_Task): Task (experiment) object represents the current running experiments and connects all the different parts into \ a fully reproducible experiment - Common usage is calling Task.init() to initialize the main task. + Common usage is calling :func:`Task.init` to initialize the main task. The main task is development / remote execution mode-aware, and supports connecting various SDK objects - such as Models etc. In development mode, the main task supports task reuse (see Task.init() for more + such as Models etc. In development mode, the main task supports task reuse (see :func:`Task.init` for more information in development mode features). - Any subsequent call to Task.init() will return the already-initialized main task + Any subsequent call to :func:`Task.init` will return the already-initialized main task and will not create a new main task. Sub-tasks, meaning tasks which are not the main task and are not development / remote execution mode aware, can be - created using Task.create(). These tasks do no support task reuse and any call - to Task.create() will always create a new task. + created using :func:`Task.create`. These tasks do no support task reuse and any call + to :func:`Task.create` will always create a new task. - You can also query existing tasks in the system by calling Task.get_task(). + You can also query existing tasks in the system by calling :func:`Task.get_task`. - **Usage: Task.init(...), Task.create() or Task.get_task(...)** + **Usage:** :func:`Task.init` or :func:`Task.get_task` """ TaskTypes = _Task.TaskTypes @@ -142,8 +142,14 @@ class Task(_Task): Notice! The reused task will be reset. (when running remotely, the usual behaviour applies) If reuse_last_task_id is of type string, it will assume this is the task_id to reuse! Note: A closed or published task will not be reused, and a new task will be created. - :param output_uri: Default location for output models (currently support folder/S3/GS/ ). + :param output_uri: Default location for output models (currently support folder/S3/GS/Azure ). notice: sub-folders (task_id) is created in the destination folder for all outputs. + + Usage example: /mnt/share/folder, s3://bucket/folder , gs://bucket-name/folder, + azure://company.blob.core.windows.net/folder/ + + Note: When using cloud storage, make sure you install the accompany packages. + For example: trains[s3], trains[gs], trains[azure] :param auto_connect_arg_parser: Automatically grab the ArgParser and connect it with the task. if set to false, you can manually connect the ArgParser with task.connect(parser) :param auto_connect_frameworks: If true automatically patch MatplotLib, Keras callbacks, and TensorBoard/X to @@ -633,17 +639,39 @@ class Task(_Task): if self.is_main_task(): self.__register_at_exit(None) - def add_artifact(self, name, artifact): + def register_artifact(self, name, artifact, metadata=None): """ Add artifact for the current Task, used mostly for Data Audition. Currently supported artifacts object types: pandas.DataFrame - :param name: name of the artifacts. can override previous artifacts if name already exists - :type name: str - :param artifact: artifact object, supported artifacts object types: pandas.DataFrame - :type artifact: pandas.DataFrame + :param str name: name of the artifacts. Notice! it will override previous artifacts if name already exists. + :param pandas.DataFrame artifact: artifact object, supported artifacts object types: pandas.DataFrame + :param dict metadata: dictionary of key value to store with the artifact (visible in the UI) """ - self._artifacts_manager.add_artifact(name=name, artifact=artifact) + self._artifacts_manager.register_artifact(name=name, artifact=artifact, metadata=metadata) + + def unregister_artifact(self, name): + """ + Remove artifact from the watch list. Notice this will not remove the artifacts from the Task. + It will only stop monitoring the artifact, + the last snapshot of the artifact will be taken immediately in the background. + """ + self._artifacts_manager.unregister_artifact(name=name) + + def upload_artifact(self, name, artifact_object=None, artifact_file=None, metadata=None): + """ + Add static artifact to Task. Artifact file/object will be uploaded in the background + + :param str name: Artifact name. Notice! it will override previous artifact if name already exists + :param object artifact_object: Artifact object to upload. Currently supports Numpy, PIL.Image. + Numpy will be stored as .npz, and Image as .png file. + Use None if uploading a file directly with 'artifact_file'. + :param str artifact_file: path to artifact file to upload. None means not applicable. + Notice you wither artifact object or artifact_file + :param dict metadata: Simple key/value dictionary to store on the artifact + :return: True if artifact is supported + """ + raise ValueError("Not implemented yet") def is_current_task(self): """