Merge 388d98a into e5ee9b1

CONTRIBUTING.md

@@ -0,0 +1,92 @@
+=======================
+Contributing Guidelines
+=======================
+
+We welcome contributions to cdcam.
+
+When submitting a change to the repository, please first create an issue that
+covers the item that you'd like to change, update or enhance. Once a discussion
+has yielded a vote of support for that addition to the package, you are ready
+to submit a pull request.
+
+If you are proposing a feature:
+
+* Explain in detail how it would work.
+* Keep the scope as narrow as possible, to make it easier to implement.
+
+Create a branch for local development
+-------------------------------------
+
+Use the ``git checkout`` command to create your own branch, and pick a name
+that describes the changes that you are making::
+
+    $ git checkout -b name-of-your-bugfix-or-feature
+
+Now you can make your changes locally.
+
+Test the package
+----------------
+
+Ensure that the tests pass, and the documentation builds successfully::
+
+    $ pytest
+    $ make docs
+
+Commit and push your changes
+----------------------------
+
+Once you are sure that all tests are passing, you can commit your changes
+and push to GitHub::
+
+    $ git add .
+    $ git commit -m "Your detailed description of your changes."
+    $ git push origin name-of-your-bugfix-or-feature
+
+Submit a pull request on GitHub
+-------------------------------
+
+When submitting a pull request:
+
+- All existing tests should pass. Please make sure that the test
+  suite passes, both locally and on
+  `Travis CI <https://travis-ci.org/nismod/cdcam>`_
+  Status on
+  Travis will be visible on a pull request. If you want to enable
+  Travis CI on your own fork, please read the
+  `getting started docs <https://docs.travis-ci.com/user/getting-started/>`_.
+
+- New functionality should include tests. Please write reasonable
+  tests for your code and make sure that they pass on your pull request.
+
+- Classes, methods, functions, etc. should have docstrings. The first
+  line of a docstring should be a standalone summary. Parameters and
+  return values should be documented explicitly.
+
+- The API documentation is automatically generated from docstrings, which
+  should conform to NumpPy styling. For examples, see the `Napoleon docs
+  <https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_numpy.html>`_.
+
+- Please note that tests are also run via Travis-CI on our documentation.
+  So be sure that any ``.rst`` file submissions are properly formatted and
+  tests are passing.
+
+
+Documentation Updates
+=====================
+
+Improving the documentation and testing for code already in ``cdcam``
+is a great way to get started if you'd like to make a contribution. Please note
+that our documentation files are in
+`ReStructuredText (.rst)
+<http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`_
+format and format your pull request accordingly.
+
+To build the documentation, use the command::
+
+    $ make docs
+
+By default ``make docs`` will only rebuild the documentation if source
+files (e.g., .py or .rst files) have changed. To force a rebuild, use
+``make -B docs``.
+You can preview the generated documentation by opening
+``docs/_build/html/index.html`` in a web browser.

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2019 Edward Oughton
+Copyright (c) 2019 Edward Oughton & Tom Russell
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -85,6 +85,16 @@ If you want to quickly generate results, first download the sample dataset avail
 More details are provided in the [Getting
 Started](https://cdcam.readthedocs.io/en/latest/getting-started.html) documentation.
 
+Contributions
+-------------
+
+Contributions to this package are welcomed via the usual pull request mechanism.
+
+Support
+-------
+
+If you encounter a bug, feel the documentation is incorrect or incomplete, or want to suggest
+new features, please post an issue in the [issues](https://github.com/nismod/cdcam/issues) tab.
 
 Background and funding
 ======================

docs/authors.rst

@@ -2,5 +2,5 @@
 Developers
 ==========
 
-* Edward J. Oughton <e.oughton@jbs.cam.ac.uk>
+* Edward J. Oughton <e.oughton@ouce.ox.ac.uk>
 * Tom Russell <tom.russell@ouce.ox.ac.uk>

docs/index.rst

@@ -32,6 +32,29 @@ Citations
   Capacity, Coverage and Cost of 5G Infrastructure Strategies: Analysis of The Netherlands.
   Telematics and Informatics (January). https://doi.org/10.1016/j.tele.2019.01.003.
 
+Statement of Need
+-----------------
+
+Every decade a new generation of cellular technology is standardised and released.
+Increasingly, given the importance of the Internet of Things, Industry 4.0 and Smart Health
+applications, both governments and other digital ecosystem actors want to understand the costs
+associated with digital connectivity.
+
+However, there are very few geospatial open-source tools to help simultaneously understand
+both the engineering and cost implications of new connectivity technologies such as 5G. Hence,
+``cdcam`` has been developed to address this key research need.
+
+Applications
+------------
+
+``cdcam`` has already been used to test the capacity, coverage and cost of 5G infrastructure
+in Britain [@Oughton:2018a; @Oughton:2018b] and the Netherlands [@Oughton:2019a].
+
+The model is one of several infrastructure simulation models being used in ongoing research
+as part of the ITRC Mistral project to analyse national infrastructure systems-of-systems,
+using scenarios of population change generated by ``simim`` [@simim] and connected by a
+simulation model coupling library, ``smif`` [@smif].
+
 Setup and configuration
 -----------------------
 
@@ -42,6 +65,53 @@ All code for ``cdcam`` is written in Python (Python>=3.5) and has a number of de
 
     pip install cdcam
 
+Using a virtual environment
+---------------------------
+
+To set up a virtual environment follow the code below::
+
+    python -m venv cdcam
+    cdcam/bin/python cdcam/bin/pip install -r requirements.txt
+    cdcam/bin/python cdcam/bin/pip install -r requirements-dev.txt
+    cdcam/bin/python cdcam/bin/pip install cdcam
+    cdcam/bin/python cdcam/bin/pip install pytest pytest-cov
+    pytest --cov-report=term --cov=cdcam tests/
+
+Using conda
+-----------
+
+The recommended installation method is to use [conda](http://conda.pydata.org/miniconda.html),
+which handles packages and virtual environments, along with the
+[`conda-forge`](https://conda-forge.org/) channel which has a host of pre-built libraries and
+packages.
+
+Create a conda environment called `cdcam`:
+
+    conda create --name cdcam python=3.7
+
+Activate it (run this each time you switch projects):
+
+    conda activate cdcam
+
+First, install optional packages:
+
+    conda install fiona shapely rtree pyproj tqdm
+
+Then install `cdcam`:
+
+    pip install cdcam
+
+Alternatively, for development purposes, clone this repository and run:
+
+    python setup.py develop
+
+Install test/dev requirements:
+
+    conda install pytest pytest-cov
+
+Run the tests:
+
+    pytest --cov-report=term --cov=cdcam tests/
 
 Background and funding
 ----------------------

paper/paper.bib

@@ -5,7 +5,7 @@ @article{Oughton:2018a
     pages = {141 - 155},
     year = {2018},
     issn = {0040-1625},
-    doi = {https://doi.org/10.1016/j.techfore.2018.03.016},
+    doi = {10.1016/j.techfore.2018.03.016},
     url = {http://www.sciencedirect.com/science/article/pii/S0040162517313525},
     author = {{Oughton}, E.~J. and {Frias}, Z. and {Russell}, T. and {Sicker}, D. and {Cleevely}, D.~D.},
 }
@@ -17,7 +17,7 @@ @article{Oughton:2018b
     pages = {636 - 652},
     year = {2018},
     issn = {0308-5961},
-    doi = {https://doi.org/10.1016/j.telpol.2017.07.009},
+    doi = {10.1016/j.telpol.2017.07.009},
     url = {http://www.sciencedirect.com/science/article/pii/S0308596117302781},
     author = {{Oughton}, E.~J. and {Frias}, Z.},
 }
@@ -28,7 +28,7 @@ @article{Oughton:2019a
     pages = {50 - 69},
     year = {2019},
     issn = {0736-5853},
-    doi = {https://doi.org/10.1016/j.tele.2019.01.003},
+    doi = {10.1016/j.tele.2019.01.003},
     url = {http://www.sciencedirect.com/science/article/pii/S073658531830830X},
     author = {{Oughton}, E.~J. and {Frias}, Z. and {van der Gaast}, S. and {van der Berg}, R.},
 }
@@ -38,7 +38,7 @@ @article{Oughton:2019b
     pages = {1 - 1},
     year = {2019},
     issn = {2169-3536},
-    doi = {https://doi.org/10.1109/ACCESS.2019.2949460},
+    doi = {10.1109/ACCESS.2019.2949460},
     url = {https://ieeexplore.ieee.org/document/8882300},
     author = {{Oughton}, E.~J. and {Katsaros}, K. and {Entezami}, F. and {Kaleshi}, D. and {Crowcroft}, J.},
 }
@@ -58,6 +58,6 @@ @article{smif
     issue = {1},
     pages = {16},
     year = {2019},
-    doi = {https://doi.org/10.5334/jors.265},
+    doi = {10.5334/jors.265},
     author = {{Usher}, W. and {Russell}, T.},
 }

paper/paper.md

@@ -72,8 +72,6 @@ A common way to estimate the system capacity of a cellular network is via stocha
 
 The model is one of several infrastructure simulation models being used in ongoing research as part of the ITRC Mistral project to analyse national infrastructure systems-of-systems, using scenarios of population change generated by ``simim`` [@simim] and connected by a simulation model coupling library, ``smif`` [@smif].
 
-Increasingly, the modelling capability reported here is being applied internationally, including to provide the analytics for the World Bank's Flagship 5G report.
-
 ## Acknowledgements
 
 We would like to acknowledge the funding which has enabled development of cdcam, from the EPSRC via (i) the Infrastructure Transitions Research Consortium Mistral project (EP/N017064/1) and (ii) the EPSRC-funded Researcher in Residence programme at the UK's Digital Catapult.

requirements-dev.txt

@@ -1,10 +1,3 @@
-# requirements for running scripts: preprocess and run
-fiona>=1.7.13
-pyproj>=2
-rtree>=0.8
-shapely>=1.6
-tqdm
-
 # test/lint
 pylint
 pytest>=3.6

requirements.txt

@@ -1 +1,7 @@
 # requirements for cdcam package
+# requirements for running scripts: preprocess and run
+shapely>=1.6
+fiona>=1.8.13
+pyproj>=2.4
+rtree>=0.8
+tqdm