Public repository that exposes project partners and collaborators to open source tooling, python libraries, and simple programs requiring command line execution.
Working through the steps in this README helps tech for good contributors jumpstart a conversation with their non-profit partner on their comfort using more common open source tools and technologies: Docker, python-based modules, Jupyter notebooks, and command-line commands.
When partners lack a prescribed ecosystem (e.g., tech stack), we must design a solution they can own after the project handover. Early exposure to free design components helps project partners understand what they should prepare to support independently.
A clear and early understanding of the technologies, skill sets, and responsibilities benefits both the tech-for-good contributor (in terms of design) and the partner (in terms of upskilling). For instance, everyone can make informed design choices from the start, dedicate time throughout the project to upskilling, or subscribe to free or low-cost learning resources. This experience can also encourage discussions within the partner organization about exploring paid platforms for the future, such as Tableau, Google Cloud, or Azure.
To complete the exercise, follow the steps below. Actively document your process as you go along.
-
Where did you get stuck? How did you unstick yourself? Did you use any online guides/materials?
-
What did you learn? Was anything you were asked to do that surprised you?
-
Think about your current processes. Imagine where this new tool will fit into that process. Describe that, too.
We recommend adopting a code editor to avoid working solely in the terminal. For the sake of this exercise, download the free version of Visual Studio Code. Note that there are other open-source, free editors to choose from!
We'll be using Homebrew
- Open a terminal. How to open a terminal on MAC
- Paste this into the terminal. This will run an installation script, which will pause, offer an explanation throughout the process, and periodically ask for your permission to continue.
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
Git is a distributed version control system. Every change made to code is tracked in the repository. Also, the entire codebase and history are available on every developer/user's computer, allowing easy branching, merging, and executing. More info on Github
Must Dos
- Create a Github account
- Use Brew to install the git command line package. Paste this into the terminal. This tutorial video provides additional guidance on set-up (if needed) How to Install Git on Mac OS
brew install git
Extra Credit
We aren't going to ask you to set up a Python-friendly development environment on your local machine. Instead, we'll guide you through a containerized solution.
"Docker is a tool for creating and deploying isolated environments for running applications with their dependencies. Docker makes it easy to write and run codes smoothly on other machines with different operating systems by putting together the code and all its dependencies in a container. This container makes the code self-contained and independent from the operating system." Source Article
- Install Docker using Brew
brew install docker
- Install Colima. Colima is an open-source project that lets us work with dDocker containers without needing to use the Docker Desktop.
brew install colima
Open Visual Studio Code and clone this repository.
colima start --cpu=4 --disk=100 --memory=6 --dns=1.1.1.1
docker build -t designing-probono .
docker run -it -p 8000:80 -p 8888:8888 -v $(pwd):/technical_test designing-probono bash
make run_data
This will write a file called test.csv to ./data/interim directory.
python -m src.data.make_census_data --group_id S1501 --geometry_level NECTA
This will call the census API, populate it, and write the following files in your local ./data directory.
./raw/NECTA
└── tiger_zip.zip
./interim/NECTA
├── tl_2020_us_necta.cpg
├── tl_2020_us_necta.dbf
├── tl_2020_us_necta.prj
├── tl_2020_us_necta.shp
├── tl_2020_us_necta.shp.ea.iso.xml
├── tl_2020_us_necta.shp.iso.xml
└── tl_2020_us_necta.shx
./processed/NECTA
└── census_geom_NECTA.geojson
If you see these files, then it worked!
Feel free to explore census data by trying different table/geography combinations. List of ACS 2020 5-year subject tables
Open the config.py file located under the ./src directory. Modify the string variable specified after WORD_FOR_PRINT = and save the file. Run the command make run_data again and see if the printed statement changes.
Once you've launched your local container and you're in the bash terminal, execute:
jupyter lab --ip 0.0.0.0 --allow-root --NotebookApp.notebook_dir=/technical_test
Copy and paste the https path from the terminal into your web browser. I am confident that this works for Chrome. This link will take you to a Jupyter Lab environment with a kernel backed by your local docker container. Note that closing the terminal will end your Jupyter Lab session
There is an example notebook in the ./notebooks directory called data_visualization
Practice running the notebook cells. And feel free to play around with them! This is a space designed for you to explore.
To end your Jupyter session, run ctrl+c in the terminal.