# 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:

```python
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

```python
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:

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

## How to follow a job

```python
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:

```python
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 {doc}`troubleshooting` for the common errors.

## How to cancel jobs

```python
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

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

**In the web app:** results page → **Avatars**.

Other results:

```python
# 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

```python
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.