Small edits (#790)

2025-06-26 18:17:44 +00:00 · 2024-03-06 15:00:50 +02:00
parent 1c45124714
commit 34affd55fb
16 changed files with 102 additions and 78 deletions
--- a/docs/guides/reporting/3d_plots_reporting.md
+++ b/docs/guides/reporting/3d_plots_reporting.md
@@ -11,15 +11,14 @@ ClearML reports these plots in the experiment's **PLOTS** tab.

 ## Surface Plot

-To plot a series as a surface plot, use the [Logger.report_surface](../../references/sdk/logger.md#report_surface) 
-method.
+To plot a series as a surface plot, use [`Logger.report_surface()`](../../references/sdk/logger.md#report_surface):

 ```python
 # report 3d surface
 surface = np.random.randint(10, size=(10, 10))
 Logger.current_logger().report_surface(
-    "example_surface",
-    "series1",
+    title="example_surface",
+    series="series1",
    iteration=iteration,
    matrix=surface,
    xaxis="title X",
@@ -33,14 +32,14 @@ View the reported surface plot in **PLOTS**.

 ## 3D Scatter Plot

-To plot a series as a 3D scatter plot, use the [Logger.report_scatter3d](../../references/sdk/logger.md#report_scatter3d) 
-method.
+To plot a series as a 3D scatter plot, use [`Logger.report_scatter3d()`](../../references/sdk/logger.md#report_scatter3d):
+
 ```python
 # report 3d scatter plot
 scatter3d = np.random.randint(10, size=(10, 3))
 Logger.current_logger().report_scatter3d(
-    "example_scatter_3d",
-    "series_xyz",
+    title="example_scatter_3d",
+    series="series_xyz",
    iteration=iteration,
    scatter=scatter3d,
    xaxis="title x",
--- a/docs/guides/reporting/artifacts.md
+++ b/docs/guides/reporting/artifacts.md
@@ -18,7 +18,7 @@ Configure ClearML for uploading artifacts to any of the supported types of stora
 S3 buckets, Google Cloud Storage, and Azure Storage ([debug sample storage](../../references/sdk/logger.md#set_default_upload_destination) 
 is different). Configure ClearML in any of the following ways:

-* In the configuration file, set [default_output_uri](../../configs/clearml_conf.md#config_default_output_uri).
+* In the configuration file, set [`default_output_uri`](../../configs/clearml_conf.md#config_default_output_uri).
 * In code, when [initializing a Task](../../references/sdk/task.md#taskinit), use the `output_uri` parameter.
 * In the **ClearML Web UI**, when [modifying an experiment](../../webapp/webapp_exp_tuning.md#output-destination).

@@ -26,12 +26,12 @@ When the script runs, it creates an experiment named `artifacts example` in the

 ClearML reports artifacts in the **ClearML Web UI** **>** experiment details **>** **ARTIFACTS** tab.

-![image](../../img/examples_reporting_03.png)
+![Experiment artifacts](../../img/examples_reporting_03.png)

 ## Dynamically Tracked Artifacts

-Currently, ClearML supports uploading and dynamically tracking Pandas DataFrames. Use the [Task.register_artifact](../../references/sdk/task.md#register_artifact)
-method. If the Pandas DataFrame changes, ClearML uploads the changes. The updated artifact is associated with the experiment.
+ClearML supports uploading and dynamically tracking Pandas DataFrames. Use [`Task.register_artifact()`](../../references/sdk/task.md#register_artifact)
+to add a DataFrame to a task. If the DataFrame is modified, ClearML will automatically update the changes. 

 For example:

@@ -47,11 +47,15 @@ df = pd.DataFrame(

 # Register Pandas object as artifact to watch
 # (it will be monitored in the background and automatically synced and uploaded)
-task.register_artifact('train', df, metadata={'counting': 'legs', 'max legs': 69}))
+task.register_artifact(
+    name='train', 
+    artifact=df, 
+    metadata={'counting': 'legs', 'max legs': 68}
+)
 ```

-By changing the artifact, and calling the [Task.get_registered_artifacts](../../references/sdk/task.md#get_registered_artifacts) 
-method to retrieve it, you can see that ClearML tracked the change.
+By modifying the artifact, and calling [`Task.get_registered_artifacts()`](../../references/sdk/task.md#get_registered_artifacts) 
+to retrieve it, you can see ClearML tracking the changes:

 ```python
 # change the artifact object
@@ -78,7 +82,7 @@ Artifacts without tracking include:
 ### Pandas DataFrames
 ```python
 # add and upload pandas.DataFrame (onetime snapshot of the object)
-task.upload_artifact('Pandas', artifact_object=df)
+task.upload_artifact(name='Pandas', artifact_object=df)
 ```

 ### Local Files
@@ -86,7 +90,7 @@ task.upload_artifact('Pandas', artifact_object=df)
 ```python
 # add and upload local file artifact
 task.upload_artifact(
-    'local file', 
+    name='local file', 
    artifact_object=os.path.join(
        'data_samples',
        'dancing.jpg'
@@ -97,31 +101,31 @@ task.upload_artifact(
 ### Dictionaries
 ```python
 # add and upload dictionary stored as JSON
-task.upload_artifact('dictionary', df.to_dict())
+task.upload_artifact(name='dictionary', artifact_object=df.to_dict())
 ```
    
 ### Numpy Objects
 ```python
 # add and upload Numpy Object (stored as .npz file)
-task.upload_artifact('Numpy Eye', np.eye(100, 100))
+task.upload_artifact(name='Numpy Eye', artifact_object=np.eye(100, 100))
 ```
    
 ### Image Files
 ```python
 # add and upload Image (stored as .png file)
 im = Image.open(os.path.join('data_samples', 'dancing.jpg'))
-task.upload_artifact('pillow_image', im)
+task.upload_artifact(name='pillow_image', artifact_object=im)
 ```
    
 ### Folders
 ```python
 # add and upload a folder, artifact_object should be the folder path
-task.upload_artifact('local folder', artifact_object=os.path.join('data_samples'))
+task.upload_artifact(name='local folder', artifact_object=os.path.join('data_samples'))
 ```

 ### Wildcards
 ```python
 # add and upload a wildcard
-task.upload_artifact('wildcard jpegs', artifact_object=os.path.join('data_samples', '*.jpg'))
+task.upload_artifact(name='wildcard jpegs', artifact_object=os.path.join('data_samples', '*.jpg'))
 ```
    
--- a/docs/guides/reporting/clearml_logging_example.md
+++ b/docs/guides/reporting/clearml_logging_example.md
@@ -53,8 +53,8 @@ scatter2d = np.hstack(
 )
 # report 2d scatter plot with markers
 logger.report_scatter2d(
-    "example_scatter",
-    "series_lines+markers",
+    title="example_scatter",
+    series="series_lines+markers",
    iteration=iteration,
    scatter=scatter2d,
    xaxis="title x",
@@ -73,8 +73,8 @@ To plot a series as a 3D scatter plot, use [`Logger.report_scatter3d()`](../../r
 # report 3d scatter plot
 scatter3d = np.random.randint(10, size=(10, 3))
 logger.report_scatter3d(
-    "example_scatter_3d",
-    "series_xyz",
+    title="example_scatter_3d",
+    series="series_xyz",
    iteration=iteration,
    scatter=scatter3d,
    xaxis="title x",
@@ -91,8 +91,8 @@ To plot a series as a surface plot, use [`Logger.report_surface()`](../../refere
 # report 3d surface
 surface = np.random.randint(10, size=(10, 10))
 logger.report_surface(
-    "example_surface",
-    "series1",
+    title="example_surface",
+    series="series1",
    iteration=iteration,
    matrix=surface,
    xaxis="title X",
@@ -111,8 +111,8 @@ Report confusion matrices by calling [`Logger.report_confusion_matrix()`](../../
 # report confusion matrix
 confusion = np.random.randint(10, size=(10, 10))
 logger.report_confusion_matrix(
-    "example_confusion",
-    "ignored",
+    title="example_confusion",
+    series="ignored",
    iteration=iteration,
    matrix=confusion,
    xaxis="title X",
@@ -131,8 +131,8 @@ To report more than one series on the same plot, use the same `title` argument.
 # report a single histogram
 histogram = np.random.randint(10, size=10)
 logger.report_histogram(
-    "single_histogram",
-    "random histogram",
+    title="single_histogram",
+    series="random histogram",
    iteration=iteration,
    values=histogram,
    xaxis="title x",
@@ -147,16 +147,16 @@ logger.report_histogram(
 histogram1 = np.random.randint(13, size=10)
 histogram2 = histogram * 0.75
 logger.report_histogram(
-    "two_histogram",
-    "series 1",
+    title="two_histogram",
+    series="series 1",
    iteration=iteration,
    values=histogram1,
    xaxis="title x",
    yaxis="title y",
 )
 logger.report_histogram(
-    "two_histogram",
-    "series 2",
+    title="two_histogram",
+    series="series 2",
    iteration=iteration,
    values=histogram2,
    xaxis="title x",
@@ -185,7 +185,7 @@ image_local_copy = StorageManager.get_local_copy(
 ### Audio

 ```python
-logger.report_media('audio', 'pink panther', iteration=1, local_path=audio_local_copy)
+logger.report_media(title='audio', series='pink panther', iteration=1, local_path=audio_local_copy)
 ``` 

 ![Audio sample](../../img/colab_explicit_reporting_08.png)
@@ -194,8 +194,8 @@ logger.report_media('audio', 'pink panther', iteration=1, local_path=audio_local

 ```python
 logger.report_media(
-    "html", 
-    "url_html", 
+    title="html", 
+    series="url_html", 
    iteration=1, 
    url="https://clear.ml/docs/latest/docs/index.html"
 )
@@ -206,7 +206,12 @@ logger.report_media(
 ### Images

 ```python
-logger.report_image("image", "image from url", iteration=100, local_path=image_local_copy)
+logger.report_image(
+    title="image", 
+    series="image from url", 
+    iteration=100, 
+    local_path=image_local_copy
+)
 ```

 ![Image sample](../../img/colab_explicit_reporting_10.png)
@@ -214,7 +219,12 @@ logger.report_image("image", "image from url", iteration=100, local_path=image_l
 ### Video

 ```python
-logger.report_media('video', 'big bunny', iteration=1, local_path=video_local_copy)
+logger.report_media(
+    title='video', 
+    series='big bunny', 
+    iteration=1, 
+    local_path=video_local_copy
+)
 ```

 ![Video sample](../../img/colab_explicit_reporting_11.png)
--- a/docs/guides/reporting/media_reporting.md
+++ b/docs/guides/reporting/media_reporting.md
@@ -50,7 +50,9 @@ Use the `local_path` parameter.
 ```python
 #  report audio, report local media audio file
 Logger.current_logger().report_media(
-    'audio', 'tada', iteration=1,
+    title='audio', 
+    series='tada', 
+    iteration=1,
    local_path=os.path.join('data_samples', 'sample.mp3')
 )
 ```