Open source project on PyPi

date published : April 08, 2020

Open source contribution

As mentioned in my blog post I recently wrote my first piece of open source software, work which was funded by the Bill and Melinda Gates Foundation and as such had to be made available for free usage by the public.

The package is up on PyPi here and it allows the creation of Qualtrics surveys from pre-defined templates, and the collection and processing of responses to these surveys.

PyPi Package

This was a fun little project to carve out part of our early technical stack and turn into a standalone package.

Usage

Pytrics requires Python 3. Once you have that installed or activated you can install and use Pytrics as described below.

Pytrics Usage

More information about working with surveys using Qualtrics and this package can be found on the package page and in the repository’s readme file.

The Repository

The repository is public and available here.

GitHub Repo

Context

This information has been put together to describe the work undertaken to open source 60 Decibels standard agriculture survey and the code for operating with the survey platform Qualtrics in order to utilise the standard agriculture survey templates.

Intended Audience

The intended audience for this software are software engineers familiar with the Python programming language.

Qualtrics Account

You will need a Qualtrics account before you can use this code, if you intend to use this software please register for an account with Qualtrics.

Use Cases

The two main use cases for this package are creating surveys on Qualtrics and retrieving responses to these.

By using this package you can easily create a survey from our template definitions and deliver this to researchers who can conduct interviews and capture response data.

Following capture of response data you can use this package to download these responses and process them into an easily readable and consumable form for your purposes.

Additionally we have also provided the ability to summarise our standard survey definitions, this is useful when preparing call scripts for researchers conducting these surveys.

Survey Definitions

Our Standard Agriculture Survey consists of 66 questions and is intended for delivery by a researcher over the phone, using Qualtrics as the means for data capture. The survey questions cover areas such as;

  • Profile & Acquisition
  • First Access
  • Information
  • Net Promoter Score
  • Quality of Life
  • Way of Farming
  • Alternative Products or Services
  • Challenges found with Products or Services
  • Customer Retention
  • Farmed Land & Ownership
  • Poverty Reach
  • Demographic Data

Supported Countries

We have provided survey definitions for each of the following countries (their two character iso code is provided in brackets for reference);

  • Ethiopia (et)
  • India (in)
  • Kenya (ke)
  • Nigeria (ng)
  • Tanzania (tz)

Supported Languages

At present we have only provided survey definitions in English.

Tailoring of Surveys

The surveys definitions use a placeholder {Company} to represent the company that provides the products or services being surveyed. This is to be replaced with the name of the specific company users are interested in.

Poverty Reach & PPI (Poverty Probability Index) Questions

Part of our standard surveys is a series of questions designed to allow you to measure the likelihood that a given household is living below the poverty line. The questions we use have been sourced from The Poverty Index.

Tools to calculate the PPI (on a per country basis) based on the answers to the questions in our surveys are available to download for free from The Poverty Index (requires registration of free account).

Live Example Surveys

The following example surveys have been created with this software package to demonstrate the deliverables of this code.

60 Decibels Standard Agriculture Survey

Publishing packages on PyPi

As part of this work I had to learn how to create and publish packages on PyPi, below are some notes on this process. Firstly you will need an account on PyPi. Once registered create a package page with your desired name, in our case this is pytrics.

Setup

You will need to install twine first, we’ll use this to publish our new package version in a moment;

Install twine

Steps to create and publish a package

Collate your code, the repository shows you the structure needed to get this up and running so refer to this if needed.

Ensure you set or update the version property in setup.py to the desired version number. I strongly suggest using SemVer - Semantic Versioning.

Below is an example of the full contents of setup.py for the Pytrics package, as a reference point should you wish to publish your code.

Setup.py

Ensure you include any new/further libraries that are required by this package in the install_requires list (see above)

Ensure you update HISTORY.md with a note and the latest version number

Commit your changes

Delete any previous/old distributions in the dist folder of the repository (if you don’t you’ll get an error: “HTTPError: 400 Client Error: File already exists. …” when you publish via twine, see below)

Create a source distribution using the command below;

Create a source distribution

Publish your new distribution using twine

Publish your source distribution

Visit the package page on PyPI to see your new version

After a minute or two this should be ready to install via pip, (it takes a minute for the new version to be available, presumably due to the CDN they use) so test that out in a new virtual environment somewhere else on your hard drive:

Test installation of your package

Check the version you just installed

Check the version you just installed

If this doesn’t provide you with the expected version this is again probably due to caching / PyPI’s CDN - you can request a specific version (your version) using the ==version syntax, as per below;

Install specific version

Assuming all is well you have just published your package, nice work 💯