{"id":15673219,"url":"https://github.com/dniku/free-lunch-saliency","last_synced_at":"2025-05-06T22:25:26.292Z","repository":{"id":73411808,"uuid":"195440434","full_name":"dniku/free-lunch-saliency","owner":"dniku","description":"Code for \"Free-Lunch Saliency via Attention in Atari Agents\"","archived":false,"fork":false,"pushed_at":"2020-12-18T11:15:17.000Z","size":44,"stargazers_count":16,"open_issues_count":1,"forks_count":2,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-05-02T01:42:26.374Z","etag":null,"topics":["atari","attention","interpretability","reinforcement-learning"],"latest_commit_sha":null,"homepage":"https://arxiv.org/abs/1908.02511","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dniku.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-07-05T16:40:54.000Z","updated_at":"2024-01-04T16:35:28.000Z","dependencies_parsed_at":"2023-03-23T11:47:06.787Z","dependency_job_id":null,"html_url":"https://github.com/dniku/free-lunch-saliency","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dniku%2Ffree-lunch-saliency","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dniku%2Ffree-lunch-saliency/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dniku%2Ffree-lunch-saliency/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dniku%2Ffree-lunch-saliency/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dniku","download_url":"https://codeload.github.com/dniku/free-lunch-saliency/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252777904,"owners_count":21802666,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["atari","attention","interpretability","reinforcement-learning"],"created_at":"2024-10-03T15:38:34.513Z","updated_at":"2025-05-06T22:25:26.265Z","avatar_url":"https://github.com/dniku.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Free-Lunch Saliency via Attention in Atari Agents\n\nCode for https://arxiv.org/abs/1908.02511.\n\nTrained models are available [here](https://drive.google.com/drive/folders/1iAow0QqnpjF9NwQkupwo1_GC35gICfWp?usp=sharing). Directory structure is as follows:\n\n```\n\u003cgame\u003e.\u003cnetwork\u003e\n└── \u003ctrain_seed\u003e\n    ├── config.json\n    ├── eval.pkl\n    ├── events.out.tfevents.\u003ctimestamp\u003e.\u003chostname\u003e\n    ├── model.pkl\n    └── saliency.pkl  # only for cnn{,_daqn,_rsppo,_sparse_fls,_sparse_fls_pool,_dense_fls}\n```\n\n### Environment\n\nThe recommended way to run our code is via Docker. We provide a container that you can download:\n\n```bash\ndocker pull dniku/fl-saliency\n```\n\nor, alternatively, build it yourself:\n\n```bash\ncat Dockerfile | docker build -t fl-saliency -\n```\n\nThe container is based off the official `nvidia/cuda:9.0-cudnn7-devel-ubuntu16.04` image with additional Python 3.6 and a set of extra libraries, including a [slightly patched](https://github.com/openai/baselines/compare/6d1c6c7...dniku:0b217d2) version of OpenAI Baselines.\n\n### Training\n\nCreate output directory with your user:\n\n```bash\nmkdir /tmp/fl-saliency\n```\n\nRun training:\n\n```bash\ndocker run \\\n    -v $(pwd):/home/docker/fl-saliency \\\n    -v /tmp/fl-saliency:/home/docker/out \\\n    --gpus all --user=$(id -u):$(id -g) --rm -it \\\n    dniku/fl-saliency \\\n    python3 fl-saliency/train_baselines.py \\\n        --output-dir /home/docker/out \\\n        --network \u003cNETWORK\u003e \\\n        --env-name \u003cENV_NAME\u003e \\\n        --train-seed \u003cTRAIN_SEED\u003e \\\n        --num-timesteps \u003cNUM_TIMESTEPS\u003e\n```\n\nParameters:\n\n *  `NETWORK` can be one of the following\n    ```\n    cnn\n    cnn_daqn\n    cnn_rsppo\n    cnn_rsppo_nopad\n    cnn_sparse_fls\n    cnn_sparse_fls_pool\n    cnn_sparse_fls_norm\n    cnn_sparse_fls_1x1\n    cnn_sparse_fls_sp2\n    cnn_sparse_fls_norelu\n    cnn_sparse_fls_norelu_pool\n    cnn_sparse_fls_h1\n    cnn_sparse_fls_x3\n    cnn_dense_fls\n    cnn_dense_fls_norelu\n    ```\n *  `ENV` can be any environment supported by OpenAI Gym. We used the following ones:\n    ```\n    BeamRiderNoFrameskip-v4\n    BreakoutNoFrameskip-v4\n    MsPacmanNoFrameskip-v4\n    SpaceInvadersNoFrameskip-v4\n    EnduroNoFrameskip-v4\n    SeaquestNoFrameskip-v4\n    ```\n *  `TRAIN_SEED` can be any integer. We used `1`, `9`, `17`, `25`, `33`.\n *  `NUM_TIMESTEPS` can be any integer ≥ `1024`. We used `50000000`. Use `1024` for testing.\n\nOutput will be saved in the directory specified by `--output-dir` in the following format:\n\n```\nlogs\n├── 0.N.monitor.csv  # logs for each of the 8 training environments\n├── log.txt          # plain-text log with metrics (also printed to stdout)\n└── progress.csv     # CSV log with metrics\ntb\n└── events.out.tfevents.\u003ctimestamp\u003e.\u003chostname\u003e  # Tensorboard log\nmodel.pkl            # trained model in Baselines format\n```\n\n### Performance evaluation\n\nAssuming that you downloaded the models to `~/data/fl-saliency`:\n\n```bash\ndocker run \\\n    -v $(pwd):/home/docker/fl-saliency \\\n    -v ~/data/fl-saliency/Breakout.cnn_sparse_fls/01/:/home/docker/experiment:ro \\\n    -v /tmp/fl-saliency:/home/docker/out \\\n    --gpus all --user=$(id -u):$(id -g) --rm -it \\\n    dniku/fl-saliency \\\n    python3 fl-saliency/run_baselines.py \\\n        --experiment-dir experiment \\\n        --output-dir out \\\n        --num-env \u003cNUM_ENV\u003e \\\n        --evals-per-env \u003cEVALS_PER_ENV\u003e \\\n        --max-eplen \u003cMAX_EPLEN\u003e \\\n        --progress\n```\n\nParameters:\n\n *  `NUM_ENV`: how many environments to spawn in parallel. We used `16`. Use `1` or `2` for testing.\n *  `EVALS_PER_ENV`: how many times to evaluate in each environment. We used `512`. Use `1` for testing.\n *  `MAX_EPLEN`: limit episode length to this many steps. Default is `108000` which corresponds to 30 minutes at 60 FPS. This is the recommended default for all games except Breakout, where models tend to enter a cycle. For Breakout, we recommend using `30000`. For testing, use `1000`.\n *  `--raw-obs`: save a video called `perception.mkv` with raw observations and an attention overlay.\n *  `--processed-obs`: save a video called `perception.mkv` with preprocessed observations and an attention overlay.\n\nIf you pass both `--raw-obs` and `--processed-obs`, raw and preprocessed observations will be stacked vertically.\n\nEvaluation results are saved in `results.json`. Example:\n\n```json\n{\n    \"rewards\": [\n        864.0\n    ],\n    \"lengths\": [\n        6849.0\n    ],\n    \"elapsed_time\": [\n        25.020986557006836\n    ],\n    \"done_per_env\": [\n        1\n    ]\n}\n```\n\n`rewards`, `lengths`, and `elapsed_time` come from Baselines. Each entry corresponds to a finished episode. `lengths` contains the number of steps while `elapsed_time` is the time since the environment was spawned, in seconds. `done_per_env` has an entry for each environment and counts how many episodes were finished there by the time evaluation is over.\n\n### Saliency evaluation\n\nFirst, download the [Atari-HEAD](https://zenodo.org/record/2603190) dataset:\n\n```bash\npip install --user zenodo-get\nmkdir -p ~/data/atari_head/\ncd ~/data/atari_head/\nzenodo_get.py 2603190\n```\n\nThen:\n\n```bash\ndocker run \\\n    -v $(pwd):/home/docker/fl-saliency \\\n    -v ~/data/fl-saliency/Breakout.cnn_sparse_fls/01:/home/docker/experiment \\\n    -v /tmp/fl-saliency:/home/docker/out \\\n    -v ~/data/atari_head:/home/docker/atari_head \\\n    --gpus all --user=$(id -u):$(id -g) --rm -it \\\n    dniku/fl-saliency \\\n    sh -c '\\\n    pip3 install --user -e fl-saliency/streaming-image-env \u0026\u0026 \\\n    python3 fl-saliency/benchmark_atari_head.py \\\n        --experiment-dir experiment \\\n        --atari-head-dir atari_head \\\n        --output-dir out \\\n        --progress'\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdniku%2Ffree-lunch-saliency","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdniku%2Ffree-lunch-saliency","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdniku%2Ffree-lunch-saliency/lists"}