Instructions to setup python environment and produce results. Additional details on the project, the content, etc., see README.md
All source code used to generate the results and figures in the paper are in the code folder. The calculations and figure generation are all run inside Jupyter notebooks which are store code/notebooks. The data used in this study should be downloaded via completed the registration form and saved in the data directory, while the sources for the manuscript text and figures are in manuscript. Results generated by the code are saved in results. See the README.md files in each directory for a full description (READMEs also listed above).
Most processes and experiments depend on a pandas dataframe. A demo notebook is provided to show the steps of populating the data structure included in the data download in a csv and pickle file. Furthermore, documentation in data/README summarize the details about data as described in the paper and used in the notebooks.
You can download a copy of all the files in this repository by cloning the git repository:
git clone https://github.com/visionjo/facerec-bias-bfw.git
You'll need a working Python environment to run the code. The recommended way to set up your environment is through the Anaconda Python distribution which provides the conda package manager. Anaconda can be installed in your user directory and does not interfere with the system Python installation. The required dependencies are specified in the file environment.yml.
We use conda virtual environments to manage the project dependencies in isolation. Thus, you can install our dependencies without causing conflicts with your setup (even with different Python versions).
Run the following command in the repository folder (where environment.yml is located) to create a separate environment and install all required dependencies in it:
conda env create
Before running any code you must activate the conda environment:
source activate ENVIRONMENT_NAME
or, if you're on Windows:
activate ENVIRONMENT_NAME
This will enable the environment for your current terminal session. Any subsequent commands will use software that is installed in the environment.
To build and test the software, produce all results and figures, and compile the manuscript PDF, run this in the top level of the repository:
make all
If all goes well, the manuscript PDF will be placed in manuscript/output.
You can also run individual steps in the process using the Makefiles from the code and manuscript folders. See the respective README.md files for instructions.
Another way of exploring the code results is to execute the Jupyter notebooks individually. To do this, you must first start the notebook server by going into the repository top level and running:
jupyter notebook
This will start the server and open your default web browser to the Jupyter interface. In the page, go into the code/notebooks folder and select the notebook that you wish to view/run.
The notebook is divided into cells (some have text while other have code). Each cell can be executed using Shift + Enter.
Executing text cells does nothing and executing code cells runs the code and produces it's output. To execute the whole notebook, run all cells in order.