README.md 4.02 KB
Newer Older
P Marbaix's avatar
P Marbaix committed
1 2 3 4 5 6
The Ember Factory
=================

Objective
---------
The purpose of this software is to (re)produce burning ember diagrams of the style used in IPCC reports.
P Marbaix's avatar
P Marbaix committed
7 8 9
An example is figure 2 from the Summary for Policymakers of the 
Special Report on a global warming of 1.5°C: 
[SR15 Figure SPM.2](https://www.ipcc.ch/site/assets/uploads/sites/2/2019/02/SPM2-1003x1024.png). 
10 11
Please note that this software is not a product of the IPCC; the IPCC is not responsible for projects or researches.
The ability of this software to reproduce several figures (previously) published by the IPCC was carefully tested.
P Marbaix's avatar
P Marbaix committed
12 13 14

How to use
----------
15
This software (hereafter 'the EF') is designed to work as a web application. However, it is relatively easy to run it "locally":
P Marbaix's avatar
P Marbaix committed
16

P Marbaix's avatar
P Marbaix committed
17 18
- The application is publicly available here: https://climrisk.org/emberfactory

P Marbaix's avatar
P Marbaix committed
19
- To run it on your own computer, you need to have Python 3.x installed, then install the EF with pip: `pip3 install emberfactory`
20 21 22
  Then set the environment variable needed by flask: `export FLASK_APP=emberweb` (for Windows: `$env:FLASK_APP = "emberweb"`) 
  and start with `flask run`. You should receive an url to open in your browser and access the EF, such as for example
  http://127.0.0.1:5000/
23 24

- To run the app on a server, you need to have a WSGI server such as Gunicorn (not included in the required packages
25
because you do not need it to run the EF locally and you may have another WSGI server).  
26
If you want a root path such as /emberfactory, the EF is written so that you should set this path 
P Marbaix's avatar
P Marbaix committed
27
in the APPLICATION_ROOT variable within a file called emberfactory.cfg that needs to be
28
located in your /instance folder (this is not entirely standard).
P Marbaix's avatar
P Marbaix committed
29 30 31 32 33 34 35

Structure
---------
The Ember Factory is made of two 'almost independent' packages:
- embermaker contains the code (and default data) needed to draw burning embers. 
The diagrams are obtained in PDF format.
- emberweb is the user interface. 
P Marbaix's avatar
P Marbaix committed
36

P Marbaix's avatar
P Marbaix committed
37 38 39 40 41 42 43 44
The reason why it is not yet 'fully independent' is that emberweb relies on auxiliary functions
that are in embermaker/helpers.py 

Version numbers
---------------
The main version number is increased with every change to any part of The Ember Factory,
(emberweb and embermaker, see above). The main version number is in emberweb/__init__.py
Embermaker also has its own version number (in embermaker/__init__.py), so as to indicate changes
45 46
that might influence the 'product', ie. burning ember diagrams. However, our objective is to avoid any change
that would alter the reproduction of older figures, and tests are done before new releases to check that.
P Marbaix's avatar
P Marbaix committed
47 48 49 50

Development history
-------------------
This software was created by philippe.marbaix -at- uclouvain.be at the end of 2019.
51
The first objective was to produce figure 3 of Zommers et al. 2020 ([doi.org/10/gg985p](https://doi.org/10/gg985p)).
P Marbaix's avatar
P Marbaix committed
52
While I have a long experience of coding in a range of programming languages, this is
P Marbaix's avatar
P Marbaix committed
53
my first experience with a web application. I made efforts in order to have 
54 55 56 57 58 59 60
a structure that can be understood and potentially extended in the future. Improvements were
regularly provided during 2020 and this will likely continue if there are needs. 
Some aspects of the coding may still reflect the logic of the first versions rather than 
what would be done if starting from sratch; changes are done when they become useful, as experience
also drives further development. Any feedback is thus very helpful!
The work for this project is done outside of my duties for the 
[Plateforme wallonne pour le GIEC](https://plateforme-wallonne-giec.be).
P Marbaix's avatar
P Marbaix committed
61

62
Help is welcome to further improve the application. All contributions will be recognised :-).
P Marbaix's avatar
P Marbaix committed
63 64 65 66

No tracking by Google or anyone else
------------------------------------
I am making efforts to keep things 'fully under control', avoiding anything that could result in
P Marbaix's avatar
P Marbaix committed
67
user tracking: no fonts, icons or libraries downloaded from third-parties by the user.
P Marbaix's avatar
P Marbaix committed
68
I would like this to continue in the future. Advice would be welcome.
P Marbaix's avatar
P Marbaix committed
69
It is also why the code is hosted by [framasoft](framasoft.org) using [gitlab](gitlab.org). I thank them both.