PyVOLCANS: A Python package to flexibly explore similarities and differences between volcanic systems
The main goal of PyVOLCANS is to help alleviate data-scarcity issues in volcanology, and contribute to developments in a range of topics, including (but not limited to): quantitative volcanic hazard assessment at local to global scales, investigation of magmatic and volcanic processes, and even teaching and scientific outreach. We hope that future users of PyVOLCANS will include any volcano scientist or enthusiast with an interest in exploring the similarities and differences between volcanic systems worldwide. Please visit our wiki pages for more information.
A new article on PyVOLCANS has been published in the Journal of Open Source Software. Please check its content here 
PyVOLCANS can be installed from PyPI as follows:
pip install pyvolcans
This method adds pyvolcans to the virtual environment PATH so that it can be
used from any directory.
Users interact with PyVOLCANS via the command-line tool. The --help command describes the possible options.
$ pyvolcans --help
usage: pyvolcans [-h] [--apriori [APRIORI [APRIORI ...]]]
[-Ts TECTONIC_SETTING] [-G ROCK_GEOCHEMISTRY] [-M MORPHOLOGY]
[-Sz ERUPTION_SIZE] [-St ERUPTION_STYLE] [--count COUNT] [-w]
[-ovd] [-oad] [-W] [-v] [-pa] [-S] [-V]
volcano
positional arguments:
volcano Set target volcano name or Smithsonian ID (VNUM)
optional arguments:
-h, --help show this help message and exit
--apriori [APRIORI [APRIORI ...]]
Provide one or more a priori analogue volcanoes
-Ts TECTONIC_SETTING, --tectonic_setting TECTONIC_SETTING
Set tectonic setting weight (e.g. '0.2' or '1/5')
-G ROCK_GEOCHEMISTRY, --rock_geochemistry ROCK_GEOCHEMISTRY
Set rock geochemistry weight (e.g. '0.2' or '1/5')
-M MORPHOLOGY, --morphology MORPHOLOGY
Set volcano morphology weight (e.g. '0.2' or '1/5')
-Sz ERUPTION_SIZE, --eruption_size ERUPTION_SIZE
Set eruption size weight (e.g. '0.2' or '1/5')
-St ERUPTION_STYLE, --eruption_style ERUPTION_STYLE
Set eruption style weight (e.g. '0.2' or '1/5')
--count COUNT Set the number of top analogue volcanoes
-w, --write_csv_file Write list of top analogue volcanoes as .csv file
-ovd, --output_volcano_data
Output volcano data (ID profile) for the selected
target volcano in a json-format file. NB. Verbose mode
needs to be activated to be able to use this feature.
-oad, --output_analogues_data
Output volcano data (ID profile) for all the top
analogue volcanoes, for the selected target volcano
and weighting scheme, in a json-format file. NB.
Verbose mode needs to be activated to be able to use
this feature.
-W, --website Open GVP website for top analogue volcano
-v, --verbose Print debug-level logging output, ID profile for the
selected target volcano, and include single-criterion
analogy values, besides the total analogy values, in
the PyVOLCANS results.
-pa, --plot_apriori Generate bar plots displaying: (1) values of single-
criterion and total analogy between the target volcano
and any 'a priori' analogues chosen by the user; and
(2) percentages of 'better analogues' (for the target
volcano) than each of the 'a priori' analogues,
considering all volcanoes in the GVP database.
-S, --save_figures Save all generated figures
-V, --version Print PyVOLCANS package version and exit
Calling PyVOLCANS with a volcano name returns the top 10 analogue volcanoes:
$ pyvolcans Hekla
Top 10 analogue volcanoes for Hekla, Iceland (372070):
name country smithsonian_id total_analogy
Torfajokull Iceland 372050 0.941676
Bardarbunga Iceland 373030 0.921407
Prestahnukur Iceland 371070 0.919877
Langjokull Iceland 371080 0.915929
Hengill Iceland 371050 0.911855
Brennisteinsfjoll Iceland 371040 0.907751
Kverkfjoll Iceland 373050 0.906833
Fremrinamar Iceland 373070 0.905074
Ecuador Ecuador 353011 0.901611
Marion Island South Africa 234070 0.892960
In verbose mode (e.g. $ pyvolcans Hekla --verbose), PyVOLCANS provides further information regarding the weights selected for each volcanological criteria, as well as the values for each single-criterion analogy, which combined make up the total_analogy values (NB. The total analogy is a weighted average of the single-criterion analogies. Please see equation 1 in Tierz et al., 2019 for more details).
As of PyVOLCANS v1.3.0, the verbose mode also provides the ID profile (i.e. summary of volcanological data available for VOLCANS calculations) for the specific volcano of interest. Please see Tierz et al., 2019 for further details on how these data are used to compute single-criterion and total-analogy values.
For example:
$ pyvolcans Hekla --verbose
PyVOLCANS: Supplied weights: {'tectonic_setting': 0.2, 'geochemistry': 0.2, 'morphology': 0.2, 'eruption_size': 0.2, 'eruption_style': 0.2}
Top 10 analogue volcanoes for Hekla, Iceland (372070):
name country smithsonian_id total_analogy ATs AG AM ASz ASt
Torfajokull Iceland 372050 0.941676 0.2 0.188235 0.187584 0.180280 0.185577
Bardarbunga Iceland 373030 0.921407 0.2 0.188235 0.187584 0.172727 0.172861
Prestahnukur Iceland 371070 0.919877 0.2 0.188235 0.189474 0.169091 0.173077
Langjokull Iceland 371080 0.915929 0.2 0.188235 0.177193 0.169091 0.181410
Hengill Iceland 371050 0.911855 0.2 0.192157 0.173684 0.169091 0.176923
Brennisteinsfjoll Iceland 371040 0.907751 0.2 0.164706 0.184211 0.169091 0.189744
Kverkfjoll Iceland 373050 0.906833 0.2 0.188235 0.187584 0.169091 0.161923
Fremrinamar Iceland 373070 0.905074 0.2 0.188235 0.168421 0.169091 0.179327
Ecuador Ecuador 353011 0.901611 0.2 0.164706 0.194737 0.169091 0.173077
Marion Island South Africa 234070 0.892960 0.2 0.141176 0.200000 0.169091 0.182692
ID profile for Hekla, Iceland (372070):
{
"name": "Hekla",
"country": "Iceland",
"smithsonian_id": 372070,
"tectonic_setting": {
"0.0": "Rift Oceanic Crust"
},
"geochemistry": {
"Foidite": 0.0,
"Phonolite": 0.0,
"Trachyte": 0.0,
"Trachyandesite/Basaltic trachyandesite": 0.0,
"Phono-tephrite/Tephri-phonolite": 0.0,
"Tephrite/Basanite/Trachybasalt": 0.0,
"Basalt": 0.25,
"Andesite": 0.25,
"Dacite": 0.25,
"Rhyolite": 0.25
},
"morphology": 0.39473684210526316,
"eruption_size": {
"VEI leq 2": 0.26666666666666666,
"VEI 3": 0.35,
"VEI 4": 0.2833333333333333,
"VEI 5": 0.1,
"VEI 6": 0.0,
"VEI 7": 0.0,
"VEI 8": 0.0
},
"eruption_style": {
"Lava flow and/or fountaining": 0.8769230769230769,
"Ballistics and tephra": 0.6923076923076923,
"Phreatic and phreatomagmatic activity": 0.0,
"Water-sediment flows": 0.15384615384615385,
"Tsunamis": 0.015384615384615385,
"Pyroclastic density currents": 0.09230769230769231,
"Edifice collapse/destruction": 0.0,
"Caldera formation": 0.0
}
}
Please note that some volcano names are composed of more than one word, such as Rincón de la Vieja (Costa Rica) or St. Helens (USA). In these cases, please wrap around the volcano name using quotation marks. For example:
$ pyvolcans "Rincon de la Vieja"
Top 10 analogue volcanoes for Rincon de la Vieja, Costa Rica (345020):
name country smithsonian_id total_analogy
Sorikmarapi Indonesia 261120 0.965415
Zaozan Japan 283190 0.963941
Mahawu Indonesia 266110 0.959122
Akita-Yakeyama Japan 283260 0.958577
Lascar Chile 355100 0.956498
Miravalles Costa Rica 345030 0.955624
Hakkodasan Japan 283280 0.955043
Poas Costa Rica 345040 0.954254
Midagahara Japan 283080 0.952637
Maruyama Japan 285061 0.951902
Please also note that some naming conventions used in the Holocene Volcano List of the Global Volcanism Program (GVP) include the sorting of some words in the volcano name, separated by commas. For example: "Fournaise, Piton de la" (France), "Sawad, Harra Es-" (Yemen) or "Bravo, Cerro" (Colombia). One of the functionalities of PyVOLCANS is to provide a list of volcano-name suggestions, if the volcano name introduced by the user contains a typo and/or is arranged in a different word order. Please see the following command example:
$ pyvolcans "Nevados de Chillan"
PyVOLCANS: Nevados de Chillan not found! Did you mean:
name country smithsonian_id
Chillan, Nevados de Chile 357070
Chachani, Nevado Peru 354007
Huila, Nevado del Colombia 351050
Casiri, Nevados Peru 354060
Cuernos de Negros Philippines 272010
Carrán-Los Venados Chile 357140
Chaine des Puys France 210020
Ruiz, Nevado del Colombia 351020
Red Hill United States 327812
Incahuasi, Nevado de Chile-Argentina 355125
$ pyvolcans "Chillan, Nevados de"
Top 10 analogue volcanoes for Chillan, Nevados de, Chile (357070):
name country smithsonian_id total_analogy
Guallatiri Chile 355020 0.972271
San Pedro-San Pablo Chile 355070 0.970770
San Jose Chile-Argentina 357020 0.968865
Galeras Colombia 351080 0.966499
Peuet Sague Indonesia 261030 0.965005
Zhupanovsky Russia 300120 0.964308
Bulusan Philippines 273010 0.963809
Chiginagak United States 312110 0.963711
Villarrica Chile 357120 0.961412
Cotopaxi Ecuador 352050 0.960387
Finally, please be aware of possible synonyms and subfeatures of the volcanic systems listed in the Holocene Volcano List of GVP. For example, "Fagradalsfjall" for "Krýsuvík-Trölladyngja" (Iceland) or "Sakurajima" for "Aira" (Japan). In these situations, we recommend PyVOLCANS users perform a simple Google Search using: "Fagradalsfjall GVP" or "Sakurajima GVP". In general, the first search result should point to the GVP website of the volcanic system of interest. Users can then use that volcano name to run their volcano analogues searches via pyvolcans.
For a comprehensive description of the purpose, input arguments and output variables for each of the functions and methods used by pyvolcans, please follow the link to the source scripts.
Please also visit our wiki pages to find out more details on the usage of PyVOLCANS, as well as several example outputs for different commands.
The best way to get in touch to ask questions, submit bug reports or contribute code is by submitting an issue in this repository.
To modify the code, first clone the PyVOLCANS repository into your local machine:
git clone https://github.com/BritishGeologicalSurvey/pyvolcansThen move to the root directory of the project (pyvolcans, which contains the setup.py file -
please also check the requirements.txt file for a full list of dependencies in the code),
and run the following command to install PyVOLCANS in development mode, preferably within a
clean virtual environment:
python -m pip install -e .[dev]The -e flag makes the files in the current working directory available
throughout the virtual environment and, therefore, changes are reflected straight away.
With this installation, it is no longer required to set the PYTHONPATH.
The [dev] part installs packages required for development e.g. pytest.
Run tests with:
pytest -v testPyVOLCANS was created by and is maintained by British Geological Survey
Volcanology and Digital Capabilities.
- Pablo Tierz (PTierz)
- Vyron Christodoulou (mobiuscreek)
- John A Stevenson (volcan01010)
PyVOLCANS and the associated VOLCANS Matlab scripts are distributed under the LGPL v3.0 licence.
Copyright: © BGS / UKRI 2021