/witan.models.demography

Generic population projections for the "Witan" City planning web platform

Primary LanguageClojureEclipse Public License 1.0EPL-1.0

witan.models.demography

Build Status Dependencies Status

Table of contents:

Description

witan.models.demography is a Clojure library to run demographic models.

These models will be used on MastodonC's Witan city decision-making platform. They can also be used independently of Witan as a standalone demographic modelling library.

Current status:

  • Population projections: Release 0.1.0 includes a minimal version of the model.

See the docs for more info about the methodology.

Contribute to witan.models.demography

General practices

If you wish to contribute to witan.models.demography, please read the following guidelines.

Github guidelines

  • Fork this repository (or clone it if you have writing rights to the repository).

  • Create a new branch. Let's try to keep the naming conventions for branches as follows:

    • feature/, example: feature/project-mortality-rates
    • doc/, example: doc/contributors-practices
    • fix/, example: fix/run-ccm-from-cli
    • tidy-up/, example: tidy-up/upgrade-deps

    This way, when you see a branch starting by fix/ we know something is broken and that someone is repairing it.

  • Keep branches short so that the reviewing process is easier and faster

  • Start a pull request (PR) as early as possible. You can add a WIP in the title to specify it's in progress.

  • Describe the aim of your changes in the PR description box.

  • Before asking for a review of your PR:

    • run all the tests from the commmand line with $ lein test
    • run the lint tools Eastwood and Kibit with $ lein eastwood and $ lein kibit.
    • format your code with Cljfmt tool with lein cljfmt check followed by lein cljfmt fix.

Coding guidelines

  • Write unit tests, docstrings, and documentation.
  • Try to not have data changes and code changes in the same commit, and preferably not the same branch, as the data tends to swamp the code and hinder reviewing.
  • Avoid modifying a file that is being modified on another branch.
  • Avoid changing the name of a file while someone is working on another branch.
  • We moved away from using the Incanter library. To manipulate core.matrix datasets look for functions:
  • Have a look at the following paragraph for useful development tools.
  • Commit and push your changes often using descriptive commit messages. And squash commits (as much as possible/necessary) before asking for a review.

Development tools

When combining functions into a model there are useful tools to take advantage of, thanks to dependencies for witan.workspace-executor and witan.workspace-api.

To visualise a model workflow, you need to:

  1. Install Graphviz:

  • Ubuntu: $ sudo apt-get install graphviz

  • MacOS: $ brew install graphviz

For any OS you should also be able to install it with Pip: $ pip install graphviz.

  1. Use the view-workflow function using the cohort-component-model workflow as follows:
(witan.workspace-executor.core/view-workflow
   (:workflow witan.models.dem.ccm.models/cohort-component-model))

To print logs, use the set-api-logging! function:

(witan.workspace-api/set-api-logging! println)

Whenever a defworkflowfn is called logs will be written to your repl or terminal. It's very useful for debugging purposes.

Turn it off with:

(witan.workspace-api/set-api-logging! identity)

Splitting and Uploading data

By default, the data for the CCM is amalgamated into single data files. To split the files by GSS code, use the following command:

lein split-data

To upload all the CSV files to S3 (gzipped), use the following command:

lein upload-data

This assumes a valid AWS profile, called 'witan', is installed. For ease, these commands can be chained like so:

lein do split-data, upload-data

License

Copyright © 2016 MastodonC Ltd

Distributed under the Eclipse Public License either version 1.0 or (at your option) any later version.