{"id":23255602,"url":"https://github.com/ukuhl/introalienzoo","last_synced_at":"2025-08-10T10:03:37.528Z","repository":{"id":161071819,"uuid":"488755297","full_name":"ukuhl/IntroAlienZoo","owner":"ukuhl","description":"Introducing the Alien Zoo approach: An experimental framework for evaluating counterfactual explanations for ML","archived":false,"fork":false,"pushed_at":"2023-03-23T08:47:17.000Z","size":124964,"stargazers_count":4,"open_issues_count":0,"forks_count":3,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-07-31T18:34:07.014Z","etag":null,"topics":["ai","counterfactual-explanations","human-computer-interaction","machine-learning","user-study","xai"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"cc-by-4.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ukuhl.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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":"2022-05-04T22:02:48.000Z","updated_at":"2025-01-08T13:30:44.000Z","dependencies_parsed_at":null,"dependency_job_id":"763bca3c-f2c9-4ad0-abcb-5696758b59ab","html_url":"https://github.com/ukuhl/IntroAlienZoo","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/ukuhl/IntroAlienZoo","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ukuhl%2FIntroAlienZoo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ukuhl%2FIntroAlienZoo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ukuhl%2FIntroAlienZoo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ukuhl%2FIntroAlienZoo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ukuhl","download_url":"https://codeload.github.com/ukuhl/IntroAlienZoo/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ukuhl%2FIntroAlienZoo/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":269706661,"owners_count":24462207,"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","status":"online","status_checked_at":"2025-08-10T02:00:08.965Z","response_time":71,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["ai","counterfactual-explanations","human-computer-interaction","machine-learning","user-study","xai"],"created_at":"2024-12-19T11:28:40.676Z","updated_at":"2025-08-10T10:03:37.497Z","avatar_url":"https://github.com/ukuhl.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# README\n\nThis repository provides code, data, and analysis scripts for the Alien Zoo framework as used in the study:\n[\"Let's Go to the Alien Zoo: Introducing an Experimental Framework to Study Usability of Counterfactual Explanations for Machine Learning\"](https://arxiv.org/pdf/2205.03398.pdf)\n\nDetailed motivation and rationale are explained in the paper. In short, we provide this framework as a utility to run user studies to perform human level evaluations of counterfactual explanations (CFEs) for machine learning (ML).\n\n## Rough overview of implementation logic\n\nImplementation of the experimental framework follows a clear separation into python-based [BackEnd](BackEnd/), and a javascript based [FronEnd](FrontEnd/). \n\n## I want to replicate the experiments as described in the paper!\n\nVery well! Let's go:\n\n### Requirements and prerequisites\n\nThere is a list of steps that first need to be done on the BackEnd side before we can go to the Alien Zoo.\n\n0. Whatever you do, use Python3.\n1. `cd BackEnd`\n2. Install all requirements as listed in `REQUIREMENTS.txt`.\n3. Install [`CEML`](https://github.com/andreArtelt/ceml) (Note: required Python 3.6 or higher!):\n`pip install ceml`\n4. Setup an MySQL database (databse name, user name and password of your choice). Then, make sure the credentials and database in `dbmgr.py` (lines 6-10) fit your set up.\n5. Run `python crypt.py` (generates key pair; relevant for encrypting userId information).\n6. Decide which experiment from our study you want to recreate. The default is Experiment 1, but you can change that via the variable `expNo` in line 17 in file `BackEnd/models.py`.\n\n### Start up the server\n\nFinally, we can start the server: `python server.py` \nThe server is listening on port **8888**, so pull up a browser and go to the Alien Zoo under [localhost:8888/](localhost:8888/).\n\n### Wrapping up, export data, clear database\n\nWhen you're done, stop the running server with `Ctrl+C`.\n\nRun `BackEnd/db_export.py` to export data from the database. This command generates 6 files from the content of the database. For details on these files and coding of respective data, see [here](???).\n\nFinally, when you are done with the code, run \n`python BackEnd/reset_database.py user_name user_pw`\nto reset the database again.\n\n# FAQ\n## How was synthetic data used for model training generated?\nWe included the code on how we generated the data as R Markdown documents under BackEnd/modelData:\n* For Experiment 1: [`DataSim_IAZ_EXP1.Rmd`](BackEnd/modelData/DataSim_IAZ_EXP1.Rmd) / [`DataSim_IAZ_EXP1.pdf`](BackEnd/modelData/DataSim_IAZ_EXP1.pdf)\n* For Experiment 2: [`DataSim_IAZ_EXP2.Rmd`](BackEnd/modelData/DataSim_IAZ_EXP2.Rmd) / [`DataSim_IAZ_EXP2.pdf`](BackEnd/modelData/DataSim_IAZ_EXP2.pdf)\n\n## How were models trained?\nWe trained decision tree regression model for each experiment. Lines 44-80 in `BackEnd/models.py` show the code used for model training. Note that pre-trained models are already available, both [model_IAZ_EXP1.joblib](BackEnd/modelData/model_IAZ_EXP1.joblib) and [model_IAZ_EXP1.joblib](BackEnd/modelData/model_IAZ_EXP1.joblib).\n\n## I want a different port!\nFair enough: The port can be changed in line 15 in file `BackEnd/server.py`.\n\n## It takes ages until the buttons appear. How can I change that?\nThe delays are chosen as used in the reported Experiments. If you want to change them, check lines 84-86 in file `FrontEnd/gameUI.js`. Via this file, you can also control other details of the procedure (trials per block, number of blocks, number and placement of attention trials, etc.)\nNote that long delays are an effective measure to ensure that participants will really engage with the materials (instead of quickly brushing over everything).\n\n## I want to re-create the statistical analysis\nWe provide R Markdown documents of the entire statistical evaluation, together with the original user data acquired in both experiments:\n* For Experiment 1: `UserData/*_EXP1.csv` / [`uk_introAlienZoo_analysis_EXP1.Rmd`](StatisticalEvaluation/uk_introAlienZoo_analysis_EXP1.Rmd) / [`uk_introAlienZoo_analysis_EXP1.pdf`](StatisticalEvaluation/uk_introAlienZoo_analysis_EXP1.pdf)\n* For Experiment 2: `UserData/*_EXP2.csv` / [`uk_introAlienZoo_analysis_EXP2.Rmd`](StatisticalEvaluation/uk_introAlienZoo_analysis_EXP2.Rmd) / [`uk_introAlienZoo_analysis_EXP2.pdf`](StatisticalEvaluation/uk_introAlienZoo_analysis_EXP2.pdf)\nNote that these files can also be used to recreate all plots (and more!) from the paper.\n\n# License\n\nThis work is licensed under a\n[Creative Commons Attribution 4.0 International License][cc-by].\n\n[![CC BY 4.0][cc-by-image]][cc-by]\n\n[cc-by]: http://creativecommons.org/licenses/by/4.0/\n[cc-by-image]: https://i.creativecommons.org/l/by/4.0/88x31.png\n[cc-by-shield]: https://img.shields.io/badge/License-CC%20BY%204.0-lightgrey.svg\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fukuhl%2Fintroalienzoo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fukuhl%2Fintroalienzoo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fukuhl%2Fintroalienzoo/lists"}