Running jobs and getting results

A run is several jobs: the avatarization (JobKind.standard), the signal and privacy metrics, and the report.

The snippets on this page start from this setup:

import os

import pandas as pd

from avatars.manager import Manager
from avatars.models import JobKind

manager = Manager(api_key=os.environ["AVATAR_API_KEY"])
df = pd.read_csv("fixtures/wbcd.csv")

runner = manager.create_runner("wbcd_jobs")
runner.add_table("wbcd", df)
runner.advise_parameters("wbcd")

How to run all or some of the jobs

runner.run()  # avatars + metrics + report

# While you iterate on the parameters, run only what you need:
# runner.run(jobs_to_run=[JobKind.standard])  # avatars only
# runner.run(jobs_to_run=[JobKind.standard, JobKind.privacy_metrics, JobKind.signal_metrics])

run() returns at once: it does not wait for the jobs, so it does not tell you if a job fails on the server. The result methods (shuffled, privacy_metrics, …) wait until the job is finished, and raise a ValueError if the job failed or was cancelled.

Calling run() again on the same runner starts a new run and emits a UserWarning with the identifier of the previous run, so that you can still reload it. To hide the warning:

runner.update_parameters("wbcd", k=10)
runner.run(ignore_warnings=True)

How to follow a job

runner.statuses()  # {'standard': 'finished', 'privacy_metrics': 'queued', ...}
runner.get_status(JobKind.standard)

How to read the error of a failed job

run() does not raise when a job fails on the server. You see the failure when you ask for a result: runner.shuffled("wbcd") raises ValueError: Job standard failed with exception: .... To diagnose it, read the status and the error message of the job:

job = runner.get_job(JobKind.standard)
print(job.status)  # JobStatus.error
print(job.exception)  # error message from the server, e.g. k larger than the dataset

See Troubleshooting for the common errors.

How to cancel jobs

runner.cancel()  # every job of this runner that is still going
# runner.cancel(JobKind.report)  # one job

A job that has not started stops at once. A running job stops at its next safe point. The jobs that wait for a cancelled job are cancelled too.

To cancel a run by name: manager.cancel_job("wbcd_jobs").

How to get the avatars

avatars_df = runner.shuffled("wbcd")  # the avatars, in random order: the file to share

In the web app: results page → Avatars.

Other results:

# Avatars in the order of the original rows: SENSITIVE, do not share
unshuffled = runner.sensitive_unshuffled("wbcd")

# Coordinates of the originals and of the avatars in the projection space
original_coordinates, avatar_coordinates = runner.projections("wbcd")

# Everything at once
results = runner.get_all_results()

Warning

sensitive_unshuffled keeps the link between each avatar and the original row it comes from. Use it only to compute your own row-by-row checks, never share it.

The output format is the format of the input, unless you set output_format="csv" or "parquet" in create_runner.

How to delete jobs

runner.delete()  # every job of this runner
# runner.delete([JobKind.standard, JobKind.privacy_metrics])  # some jobs

To delete a run by name: manager.delete_job("wbcd_jobs"). If several runs have this name, a ValueError lists the commands to choose one.