# EmberMaker
## Purpose
EmberMaker is a scientific graphic library aimed at (re)producing "burning ember" diagrams
of the style used in IPCC (Intergovernmental Panel on Climate Change) reports.
All graphics elements are in vector form, including color gradients (this implies specific drawing code).
EmberMaker was formerly a part of the EmberFactory project: https://pypi.org/project/EmberFactory/.
If you need to produce ember diagrams from your data, **first consider using the online [EmberFactory](https://pypi.org/project/EmberFactory/)**.
This package is intended to meet more specific needs, by drawing embers from your own code.
In addition to 'burning embers', EmberMaker can also draw common x-y plots which share the
same vertical axis as a set of embers.
While EmberMaker is a Python package, it is quite easy to use within [R](https://www.r-project.org),
as shown in the last example below.
## Installation
`pip install embermaker`
Only Python >= 3.10 is supported.
## Basic usage
Creating embers only needs calling a few functions, as in this basic example:
```
from embermaker.embergraph import EmberGraph
from embermaker.ember import Ember
# Create ember
be = Ember(name='What this ember is about', haz_valid=[0, 5])
# Add two transitions to this ember
be.trans_create(name='undetectable to moderate', min=0.6, median=1.1, max=1.4, confidence='very high')
be.trans_create(name='moderate to high', min=1.7, median=2.2, max=2.5, confidence='high')
# Create an ember graph (available native image formats are PDF and SVG)
egr = EmberGraph("output_file_name", grformat="PDF")
# Change a parameter (list of parameters: https://climrisk.org/emberfactory/doc/parameters )
egr.gp['haz_axis_top'] = 5.0 # max value on axis
# Add ember to graph (a list would work as well; more advanced uses define ember groups)
egr.add(be)
# Actually produce the diagram
outfile = egr.draw()
```
## Usage examples
Examples are provided on [FramaGit](https://framagit.org/marbaix/embermaker/-/tree/master/examples) (a GitLab instance)
### Access within python (/examples/python):
- 'create_and_draw_embers.py' is the shorter and simpler. It illustrates a few functions constructing embers from data.
- 'draw_embers_from_file.py' reads 'traditional' ember Excel sheets and shows how an x-y plot can be added.
- 'test_error_reporting.py' illustrates a few cases which produce warning or error messages and how to access these.
### Access from R (/examples/R):
- 'create_and_draw_embers.R' illustrates functions constructing embers, within an R script and using data produced in R.
As this is the first "standalone" version, the API functions may be improved in the future, as well as more documented.
We are interested in learning how you use this and any difficult you might face, to steer future development - thanks!
## Development history
The EmberFactory software was created by philippe.marbaix -at- uclouvain.be at the end of 2019.
The first objective was to produce figure 3 of Zommers et al. 2020 ([doi.org/10/gg985p](https://doi.org/10/gg985p)).
Raw data
{
"_id": null,
"home_page": "https://framagit.org/marbaix/embermaker",
"name": "embermaker",
"maintainer": "Philippe Marbaix",
"docs_url": null,
"requires_python": ">=3.10,<4.0",
"maintainer_email": "philippe.marbaix@uclouvain.be",
"keywords": "climate change,impacts,IPCC,burning embers",
"author": "Philippe Marbaix",
"author_email": "philippe.marbaix@uclouvain.be",
"download_url": "https://files.pythonhosted.org/packages/a6/85/b62d26191c61384a2fe730e1624595046b484a8e70de35878eed7b003b36/embermaker-2.0.1.tar.gz",
"platform": null,
"description": "# EmberMaker\n\n## Purpose\n\nEmberMaker is a scientific graphic library aimed at (re)producing \"burning ember\" diagrams \nof the style used in IPCC (Intergovernmental Panel on Climate Change) reports. \nAll graphics elements are in vector form, including color gradients (this implies specific drawing code).\n\nEmberMaker was formerly a part of the EmberFactory project: https://pypi.org/project/EmberFactory/. \nIf you need to produce ember diagrams from your data, **first consider using the online [EmberFactory](https://pypi.org/project/EmberFactory/)**. \nThis package is intended to meet more specific needs, by drawing embers from your own code.\n\nIn addition to 'burning embers', EmberMaker can also draw common x-y plots which share the\nsame vertical axis as a set of embers.\n\nWhile EmberMaker is a Python package, it is quite easy to use within [R](https://www.r-project.org),\nas shown in the last example below.\n\n## Installation\n\n`pip install embermaker`\n\nOnly Python >= 3.10 is supported.\n\n## Basic usage\nCreating embers only needs calling a few functions, as in this basic example:\n\n```\nfrom embermaker.embergraph import EmberGraph\nfrom embermaker.ember import Ember\n\n# Create ember\nbe = Ember(name='What this ember is about', haz_valid=[0, 5])\n\n# Add two transitions to this ember\nbe.trans_create(name='undetectable to moderate', min=0.6, median=1.1, max=1.4, confidence='very high')\nbe.trans_create(name='moderate to high', min=1.7, median=2.2, max=2.5, confidence='high')\n\n# Create an ember graph (available native image formats are PDF and SVG)\negr = EmberGraph(\"output_file_name\", grformat=\"PDF\")\n\n# Change a parameter (list of parameters: https://climrisk.org/emberfactory/doc/parameters )\negr.gp['haz_axis_top'] = 5.0 # max value on axis \n\n# Add ember to graph (a list would work as well; more advanced uses define ember groups)\negr.add(be)\n\n# Actually produce the diagram\noutfile = egr.draw()\n```\n\n## Usage examples\n\nExamples are provided on [FramaGit](https://framagit.org/marbaix/embermaker/-/tree/master/examples) (a GitLab instance)\n\n### Access within python (/examples/python): \n- 'create_and_draw_embers.py' is the shorter and simpler. It illustrates a few functions constructing embers from data.\n- 'draw_embers_from_file.py' reads 'traditional' ember Excel sheets and shows how an x-y plot can be added.\n- 'test_error_reporting.py' illustrates a few cases which produce warning or error messages and how to access these.\n### Access from R (/examples/R):\n- 'create_and_draw_embers.R' illustrates functions constructing embers, within an R script and using data produced in R.\n\nAs this is the first \"standalone\" version, the API functions may be improved in the future, as well as more documented.\nWe are interested in learning how you use this and any difficult you might face, to steer future development - thanks!\n\n## Development history\nThe EmberFactory software was created by philippe.marbaix -at- uclouvain.be at the end of 2019.\nThe first objective was to produce figure 3 of Zommers et al. 2020 ([doi.org/10/gg985p](https://doi.org/10/gg985p)).\n",
"bugtrack_url": null,
"license": "GPL-3.0-or-later",
"summary": "Software library to (re)produce burning ember and related diagrams of the style used in IPCC reports",
"version": "2.0.1",
"project_urls": {
"Homepage": "https://framagit.org/marbaix/embermaker"
},
"split_keywords": [
"climate change",
"impacts",
"ipcc",
"burning embers"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "13549d95de7f73a66f7ba0477e681b36021625a9a1fe0cb6c5fc90d7c626bb35",
"md5": "a076547acca30ff55ecbb7722fd12f2c",
"sha256": "6ca2f472979916e49d5ecfb0feecf1becf9bf53fd31fbcdb14a703f689c0a04d"
},
"downloads": -1,
"filename": "embermaker-2.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a076547acca30ff55ecbb7722fd12f2c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10,<4.0",
"size": 78832,
"upload_time": "2024-01-08T07:53:49",
"upload_time_iso_8601": "2024-01-08T07:53:49.567531Z",
"url": "https://files.pythonhosted.org/packages/13/54/9d95de7f73a66f7ba0477e681b36021625a9a1fe0cb6c5fc90d7c626bb35/embermaker-2.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a685b62d26191c61384a2fe730e1624595046b484a8e70de35878eed7b003b36",
"md5": "3f574168d6477b75ff1249794d110bf1",
"sha256": "f698a44c590ba7a337ae7cbda8ac647c9bcc243876ac5efe9ed87243585f5d01"
},
"downloads": -1,
"filename": "embermaker-2.0.1.tar.gz",
"has_sig": false,
"md5_digest": "3f574168d6477b75ff1249794d110bf1",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10,<4.0",
"size": 71789,
"upload_time": "2024-01-08T07:53:51",
"upload_time_iso_8601": "2024-01-08T07:53:51.435848Z",
"url": "https://files.pythonhosted.org/packages/a6/85/b62d26191c61384a2fe730e1624595046b484a8e70de35878eed7b003b36/embermaker-2.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-08 07:53:51",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "embermaker"
}
JSON