Update read to follow standard

https://github.com/RichardLitt/standard-readme
romainsacchi · Mar 19, 2020 · 9dfc585 · 9dfc585
1 parent 7b9327b
commit 9dfc585
Show file tree

Hide file tree

Showing 3 changed files with 45 additions and 25 deletions.
diff --git a/LICENSE b/LICENSE
@@ -1,6 +1,6 @@
 BSD 3-Clause License
 
-Copyright (c) 2019, Paul Scherrer Institut
+Copyright (c) 2020, Paul Scherrer Institut
 
 Redistribution and use in source and binary forms, with or without
 modification, are permitted provided that the following conditions are met:

diff --git a/README.md b/README.md
@@ -13,19 +13,37 @@
   <a href="https://doi.org/10.5281/zenodo.3582994"><img src="https://zenodo.org/badge/DOI/10.5281/zenodo.3582994.svg" alt="DOI"></a>
 </p>
 
-## What is ``carculator``?
+Prospective environmental and economic life cycle assessment of vehicles made blazing fast.
 
 A fully parameterized Python model developed by the [Technology Assessment group](https://www.psi.ch/en/ta) of the
-[Paul Scherrer Institut](https://www.psi.ch/en) to perform life cycle assessments (LCA) of passenger cars.
+[Paul Scherrer Institut](https://www.psi.ch/en) to perform life cycle assessments (LCA) of vehicles.
 
-## What is Life Cycle Assessment?
+See [the documentation](https://coarse-lci.readthedocs.io/en/latest/index.html) for more detail, validation, etc.
+
+## Table of Contents
+
+- [Background](#background)
+  - [What is LCA](#what-is-lca)
+  - [Why carculator](#why-carculator)
+- [Install](#install)
+- [Usage](#usage)
+    - [As a Python library](as-a-python-library)
+    - [As a Web app](#as-a-web-app)
+- [Support](#support)
+- [Maintainers](#maintainers)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Background
+
+### What is Life Cycle Assessment
 
 Life Cycle Assessment (LCA) is a systematic way of accounting for environmental impacts along the relevant phases of the life of a product or service.
 Typically, the LCA of a passenger vehicle includes the raw material extraction, the manufacture of the vehicle, its distribution, use and maintenance, as well as its disposal.
 The compiled inventories of material and energy required along the life cycle of the vehicle is characterized against some impact categories (e.g., climate change).
 In the research field of mobility, LCA is widely used to investigate the superiority of a technology over another one.
 
-## Why is ``carculator`` needed?
+### Why ``carculator``
 
 ``carculator`` allows to:
 * produce [life cycle assessment (LCA)](https://en.wikipedia.org/wiki/Life-cycle_assessment) results that include conventional midpoint impact assessment indicators as well cost indicators
@@ -35,16 +53,11 @@ In the research field of mobility, LCA is widely used to investigate the superio
 (i.e., supply of fuel, battery chemistry, etc.)
 * and easily export the vehicle models as inventories to be further imported in the [Brightway2](https://brightwaylca.org/) LCA framework
 
-``carculator`` integrates well with [Brightway](https://brightwaylca.org/) and [presamples](https://github.com/PascalLesage/brightway2-presamples).
-
-Extended from the initial work described in [Uncertain environmental footprint of current and future battery electric vehicles by Cox, et al (2018)](https://pubs.acs.org/doi/abs/10.1021/acs.est.8b00261).
+``carculator`` integrates well with the [Brightway](https://brightwaylca.org/) LCA framework.
 
+``carculator`` was built based on work described in [Uncertain environmental footprint of current and future battery electric vehicles by Cox, et al (2018)](https://pubs.acs.org/doi/abs/10.1021/acs.est.8b00261).
 
-## Documentation
-
-See [Documentation](https://coarse-lci.readthedocs.io/en/latest/index.html).
-
-## Installation
+## Install
 
 ``carculator`` is at an early stage of development and is subject to continuous change and improvement.
 Three ways of installing ``carculator`` are suggested.
@@ -58,14 +71,14 @@ We recommend the installation on **Python 3.7**.
 ### Installation of a development version from conda
 
     conda install -c conda-forge -c cmutel -c romainsacchi/label/nightly carculator
-
 
 ### Installation of a development version from GitHub
 
     pip install git+https://github.com/romainsacchi/carculator.git
 
+## Usage
 
-## Usage examples
+### As a Python library
 
 Calculate the fuel efficiency (or ``Tank to wheel`` energy requirement) in km/L of petrol-equivalent of current SUVs for the driving cycle WLTC 3.4
 over 800 Monte Carlo iterations:
@@ -78,14 +91,14 @@ over 800 Monte Carlo iterations:
     cm = CarModel(array, cycle='WLTC 3.4')
     cm.set_all()
     TtW_energy = 1 / (cm.array.sel(size='SUV', year=2017, parameter='TtW energy') / 42000) # assuming 42 MJ/L petrol
-    
+
     l_powertrains = TtW_energy.powertrain
     [plt.hist(e, bins=50, alpha=.8, label=e.powertrain.values) for e in TtW_energy]
     plt.xlabel('km/L petrol-equivalent')
     plt.ylabel('number of iterations')
     plt.legend()
 ```
-   
+
 ![MC results](https://github.com/romainsacchi/coarse/raw/master/docs/stochastic_example_ttw.png)
 
 Compare the carbon footprint of electric vehicles with that of rechargeable hybrid vehicles for different size categories today and in the future
@@ -101,29 +114,36 @@ over 500 Monte Carlo iterations:
         'powertrain':['BEV', 'PHEV'],
     }
     ic = InventoryCalculation(cm.array, scope=scope)
-    
+
     results = ic.calculate_impacts()
     data_MC = results.sel(impact_category='climate change').sum(axis=3).to_dataframe('climate change')
     plt.style.use('seaborn')
     data_MC.unstack(level=[0,1,2]).boxplot(showfliers=False, figsize=(20,5))
     plt.xticks(rotation=70)
     plt.ylabel('kg CO2-eq./vkm')
 ```
-    
+
 ![MC results](https://github.com/romainsacchi/coarse/raw/master/docs/example_stochastic_BEV_PHEV.png)
 
 For more examples, see [examples](https://github.com/romainsacchi/carculator/blob/master/examples/Examples.ipynb).
 
-## Web graphical user interface
+## As a Web app
 
-``carculator`` has a graphical user interface for fast comparisons of vehicles.
-See [carculator_online](http://carculator.psi.ch).
+``carculator`` has a [graphical user interface]((http://carculator.psi.ch)) for fast comparisons of vehicles.
 
+## Support
+
+Do not hesitate to contact the development team at [carculator@psi.ch](mailto:carculator@psi.ch).
+
+## Maintainers
+
+* [Romain Sacchi](https://github.com/romainsacchi)
+* [Chris Mutel](https://github.com/cmutel/)
 
 ## Contributing
 
 Details on how to contribute: see [Issues](https://github.com/romainsacchi/carculator/issues).
 
-## Support
+## License
 
-Do not hesitate to contact the development team at [carculator@psi.ch](mailto:carculator@psi.ch).
+[BSD-3-Clause](https://github.com/romainsacchi/carculator/blob/master/LICENSE). Copyright (c) 2020 Paul Scherrer Institut.
diff --git a/setup.py b/setup.py
@@ -45,7 +45,7 @@ def package_files(directory):
         "bw2io",
     ],
     url="https://github.com/romainsacchi/carculator",
-    description="Tool to perform environmental and economic prospective life cycle assessments of vehicles",
+    description="Prospective environmental and economic life cycle assessment of vehicles made blazing fast",
     classifiers=[
         "Intended Audience :: End Users/Desktop",
         "Intended Audience :: Developers",