update paper and add build functionality

.github/workflows/draft-pdf.yml

@@ -0,0 +1,23 @@
+on: [push]
+
+jobs:
+  paper:
+    runs-on: ubuntu-latest
+    name: Paper Draft
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+      - name: Build draft PDF
+        uses: openjournals/openjournals-draft-action@master
+        with:
+          journal: joss
+          # This should be the path to the paper within your repo.
+          paper-path: paper.md
+      - name: Upload
+        uses: actions/upload-artifact@v1
+        with:
+          name: paper
+          # This is the output path where Pandoc will write the compiled
+          # PDF. Note, this should be the same directory as the input
+          # paper.md
+          path: paper.pdf

paper.md

@@ -1,13 +1,16 @@
 ---
-title: 'ThermoPlotter: Streamlined Analysis of Thermoelectric Properties'
+title: 'ThermoParser: Streamlined Analysis of Thermoelectric Properties'
 tags:
   - Python
   - Matplotlib
   - thermoelectrics
+  - electronic properties
+  - transport properties
   - materials science
   - chemistry
   - physics
   - science
+  - data analysis
   - plotting
 authors:
   - name: Kieran B. Spooner
@@ -21,77 +24,87 @@ authors:
     affiliation: "1, 2"
   - name: David O. Scanlon
     orchid: 0000-0001-9174-8601
-    affiliation: "1, 2, 3"
+    affiliation: "1, 2"
 affiliations:
  - name: Department of Chemistry, University College London, 20 Gordon Street, London WC1H 0AJ, United Kingdom
    index: 1
  - name: Thomas Young Centre, University College London, Gower Street, London WC1E 6BT, United Kingdom
    index: 2
- - name: Diamond Light Source Ltd., Diamond House, Harwell Science and Innovation Campus, Didcot, Oxfordshire OX11 0DE, UK
-   index: 3
-date: 1 February 2021
+date: 13 July 2023
 bibliography: ref.bib
 ---
 
 # Summary
 
-Thermoelectric materials, which convert heat into electricity, have become an accessible area of computational materials research in recent years owing to the development of several codes capable of calculating their key properties.
-These packages include Phonopy [@Togo2015a], Phono3py [@Togo2015], ShengBTE/ almaBTE [@Li2014], ALAMODE [@Tadano2014] and TDEP [@Hellman2011].
-Thermoelectric performance is determined by the thermal and charge transport properties of a material, several of which are strongly interrelated.
-Such complexity makes thermoelectrics an extremely interesting area of study, but a lack of readily accessible post-processing tools mean that data analysis and visualisation is often challenging and time consuming.
-ThermoPlotter facilitates the post-processing of thermoelectric properties directly from the raw output of multiple software packages, resulting in publication-standard plots   [@Spooner2020;@Einhorn2020].
+Thermoelectric materials, which convert heat into electricity, could be an important renewable energy source to help slow the encroaching climate crisis.
+With the growing computational capacity and development of several codes to calculate the key properties of thermoelectrics, they have become an increasingly popular area of computational materials research in recent years.
+Thermal transport packages include Phonopy [@Togo2015a], Phono3py [@Togo2015], ShengBTE/ almaBTE [@Li2014], ALAMODE [@Tadano2014], TDEP [@Hellman2011] and HiPhive [@Eriksson2019]; and electronic transport packages include BoltzTraP(2) [@Madsen2006;@Madsen2018], EPW [@Noffsinger2010], EPA [@Samsonidze2018], EPIC STAR [@Deng2020], AMSET [@Ganose2021], Perturbo [@Zhou2021], TOSSPB [@Poehls2022] and ElecTra [@Graziosi2023].
+While separate packages are required for such different calculations, this makes data analysis complex, needing to load in different file formats, account for different data arrangements (e.g. array shapes), and convert to consistent units, even before one begins analysing anything.
+ThermoParser deals with these time-consuming and error-prone problems by loading data from multiple codes into a consistent data format with informative metadata, and facilitates the post-processing of thermoelectric properties by using this to accurately calculate and visualise them through an easy-to-use command-line interface (CLI) and a fully customisable Python package.
+Some of its utility can be seen by its use in the literature [@Spooner2020;@Einhorn2020;@Kavanagh2021;@Spooner2021;@Brlec2022;@HerringRodriguez2023].
 
 # Statement of Need
 
-There already exist some tools for plotting thermoelectric properties.
-For example, Phonopy has built-in modules to plot phonon dispersions and densities of states (DoSs). 
-Phono3py contains a small number of auxiliary tools for plotting properties including lattice thermal conductivity and phonon mean free path.
-Some command-line codes such as sumo [@Ganose2018] and Phono3py-Power-Tools [@Skelton2020], allow plotting of phonon dispersions, phonon DoSs and properties such as the modal contribution to lattice thermal conductivity.
-ThermoPlotter brings two key novelties to the existing software landscape:
-First, the automatic parsing of outputs from multiple codes into a common format;
-Second, the ability to plot this data as publication-ready figures using an intuitive Python API, accessible to Python novices while fully customisable.
-There is also a suite of command-line scripts for quick and easy plotting.
+To the best of our knowledge no package exists for processing data from the vastly different sets of calculations needed to study thermoelectrics computationally.
+While there are several codes to aid with individual aspects of thermoelectric calculations, such as the inbuilt analysis sections of Phonopy and AMSET or packages such as Phono3py-Power-Tools [@Skelton2020] and sumo [@Ganose2018], they are specialised to either the phononic or electronic side.
+ThermoParser brings three key novelties to the existing software landscape:
+
+* The automatic parsing of outputs from multiple codes for both electronic and phononic calculations;
+* A data system which is transparent in the origin, arrangement and units of the data, customisable, and accessible regardless of Python aptitude;
+* Plotting tools for the creation of publication-ready figures through an intuitive Python API, accessible to Python novices while fully customisable for making complex, information-rich graphics, with the most common plots also availble via a CLI.
+
+To complement these capabilities, there is also a range of ancillary functions which streamline all parts of the process.
 
-# ThermoPlotter
+# ThermoParser
 
-ThermoPlotter is a Python package for analysing and plotting thermoelectric properties.
-The main dependencies are matplotlib [@Hunter2007] for plotting, pymatgen [@Ong2013] for symmetry analysis and numpy for calculations.
-The package interfaces with Phonopy, Phono3py, AMSET [@Ganose2020] and BoltzTraP [@Madsen2006]. 
-It is written to allow for easy expansion to other codes, which is planned for future releases.
+ThermoParser is a Python package for analysing and plotting thermoelectric properties.
+The main dependencies are matplotlib [@Hunter2007] for plotting, pymatgen [@Ong2013] for symmetry analysis, numpy for calculations and click for the CLI.
+The package interfaces with Phonopy, Phono3py, AMSET and BoltzTraP.
 
-The interface is designed to be accessible to those unfamiliar with Python, with the simplest plots requiring just four lines of code.
-More complex plots can be achieved by making full use of the Python API.
+The package is modular, with a separate function for loading from each code, plotting each graph-type and preparing each axis arrangement, as well as numerous helper functions for calculating properties, manipulating data, and fomatting outputs.
+Therefore, in order to add support for a new code, calculated property or plot-type, one needs only create a single function able to read/write the common format, and perhaps some metadata, and the rest should just work.
+Everything loaded into the common format has a `meta` directory, containing all the metadata needed to understand the data: the code it was loaded from, the shape of the array (e.g. if the first index is temperature) and the units, as well as any conditions imposed, such as if the data has been reduced to a particular temperature.
+All dependent variables are also loaded by default.
+A `tprc.yaml` config file is supplied, which enables the user to automatically convert units, and update the units as they appear in the metadata and on axis labels.
+This data is used by CLI functions provided to retrieve data from files, which verbosely describes the conditions under which it was measured for maximum transparency.
+
+Plotting simple plots can be done easily via the CLI, but the Python interface is designed to be accessible to those unfamiliar with Python, with the simplest plots requiring just four lines of code.
+More complex plots can be achieved by making full use of the Python API, but oftentimes still only require adding an extra `plot` line.
 In general, raw data is converted to high-quality plots in four stages:
 
  1. Axes: Choose pre-sized axes suitable for publication or presentation from `tp.axes`.
 
  2. Load: Use the `data.load` module to parse outputs of other codes, standardising variable names, formatting and ensuring consistency across code versions. There is also a module which efficiently runs BoltzTraP and saves the output.
 
- 3. Add: Use the `plot` module to add plots to the axes. Options exist for scaling data, multiple plots per set of axes, and other customisation options. 
+ 3. Add: Use the `plot` module to add plots to the axes. Options exist for scaling data, multiple plots per set of axes, and other customisation.
 
- 4. Save: Use `matplotlib.pyplot.savefig` or similar.
+ 4. Save: Use `fig.savefig` or similar.
 
-The `tprc.yaml` file allows users to set a range of defaults, including axis labels, tick locators, style sheets and more. 
-While a [gallery](https://smtg-ucl.github.io/ThermoPlotter/gallery.html) is curated to demonstrate all plotting functionality, we highlight some key examples in Figures 1 and 2. 
+The `tprc.yaml` file allows users to set a range of defaults, including axis labels, tick locators, style sheets and more.
+While a [gallery](https://smtg-ucl.github.io/ThermoPlotter/gallery.html) is curated to demonstrate all plotting functionality, we highlight some key examples in Figures 1 and 2.
 
-\autoref{fig:phonon}a shows a phonon dispersion with an element-decomposed DoS sharing the y axis.
+\autoref{fig:phonon}a shows a phonon dispersion with an element-decomposed DoS sharing the y-axis.
 Different environments for the same atom type can be specified, if desired, and it is possible to overlay multiple dispersions to assess calculation convergence.
-\autoref{fig:phonon}b shows the same dispersion with lifetime projected on the colour axis. Data from both Phono3py and Phonopy is parsed, and ThermoPlotter internally calculates mean free path and phonon lifetime.
-Several other ways of projecting a range of properties onto a phonon dispersion are implemented, including the broadened bands plot (`tp.plot.frequency.add_wideband`), which is more commonly seen in the literature.
+\autoref{fig:phonon}b shows the same dispersion with lifetime projected on the colour axis.
+Data from both Phono3py and Phonopy is parsed, and ThermoParser internally calculates mean free path and phonon lifetime.
+Several other ways of projecting a range of properties onto a phonon dispersion are implemented, including the broadened bands plot (`tp.plot.frequency.add_wideband`), which is more commonly seen in the literature [@Togo2015].
+This also demonstrates the utility of ThermoParser's consistent data format: as well as Phono3py data, Gruneisen parameter data from Phonopy can be projected onto phonon dispersions in the same way, by changing only which data is loaded and setting `quantity='gruneisen'` rather than `'lifetime'`.
 
 ![Phonon dispersions for ZnO with a) DoS and b) phonon lifetime projected on the colour axis. \label{fig:phonon}](joss_figures/phonons-subfigs.png)
 
 \autoref{fig:waterfall} is a waterfall plot of mean free path against frequency overlaying a DoS plot, clearly showing the relationship between elemental composition and scattering.
-Scaling the linear-scaled DoS data to the log-scaled waterfall axes would be time-consuming on a case-by-case basis, whereas the `tp.plot.frequency.add_dos` function wil autodetect the data range and rescale appropriately if the `scale` argument is set to `True`. 
+Scaling the linear-scaled DoS data to the log-scaled waterfall axes would be time-consuming on a case-by-case basis, whereas the `tp.plot.frequency.add_dos` function wil autodetect the data range and rescale appropriately if the `scale` argument is set to `True`.
 
 ![Waterfall plot overlaid on a DoS for BaSnO$_3$. \label{fig:waterfall}](joss_figures/waterfall.png)
 
+Future directions for ThermoParser include increasing the number of supported codes; and functions to extract and add metadata to experimental data to enable easier comparison of theoretical and experimental results.
+
 # Author Contributions
 
 The primary code base was largely written by KBS based on standalone scripts written by KBS and ME.
 ME implemented functions to plot the density of phonon modes.
 DWD provided day-to-day supervision and guidance and DOS provided the initial idea and motivation for the code.
-The first draft of the manuscript was written by KBS and DWD with input from all co-authors. 
+The first draft of the manuscript was written by KBS and DWD with input from all co-authors.
 
 # Conflicts of Interest
 
@@ -100,7 +113,7 @@ There are no conflicts to declare.
 # Acknowledgements
 
 KBS, DWD and DOS acknowledge support from the European Research Council (grant 758345).
-This work made use of the ARCHER UK National Supercomputing Service via the Materials Chemistry Consortium, which is funded by EPSRC (EP/L000202), and resources made available via the UK Materials and Molecular Modelling Hub, which is partially funded by EPSRC (EP/P020194/1).
-We would like to acknowledge contributions of ideas and time from Bonan Zhu, Seán R. Kavanagh and Warda Rahim.
+This work made use of the ARCHER2 UK National Supercomputing Service via the Materials Chemistry Consortium, which is funded by EPSRC (EP/L000202), and resources made available via the UK Materials and Molecular Modelling Hub, which is partially funded by EPSRC (EP/P020194/1).
+We would like to acknowledge contributions of ideas and time from Bonan Zhu, Seán R. Kavanagh, Warda Rahim, Katarina Brlec, Joe Willis, Luisa Herring--Rodriguez and Sabrine Hachmioune.
 
 # References

ref.bib

@@ -176,4 +176,85 @@ @Article{Tadano2014
   publisher = {IOP Publishing},
 }
 
+@Article{HerringRodriguez2023,
+  author    = {Herring Rodriguez, Luisa and Spooner, Kieran B and Einhorn, Maud and Scanlon, David O},
+  journal   = {J. Mater. Chem. C},
+  title     = {Sr$_{2}$Sb$_{2}$O$_{7}$: a Novel Earth Abundant Oxide Thermoelectric},
+  year      = {2023},
+  publisher = {Royal Society of Chemistry},
+}
+
+@Article{Poehls2022,
+  author    = {P{\"o}hls, Jan-Hendrik and Mozharivskyj, Yurij},
+  journal   = {Comput. Mater. Sci.},
+  title     = {TOSSPB: Thermoelectric Optimization Based on Scattering-Dependent Single-Parabolic Band Model},
+  year      = {2022},
+  pages     = {111152},
+  volume    = {206},
+  publisher = {Elsevier},
+}
+
+@Article{Noffsinger2010,
+  author    = {Noffsinger, Jesse and Giustino, Feliciano and Malone, Brad D and Park, Cheol-Hwan and Louie, Steven G and Cohen, Marvin L},
+  journal   = {Comput. Phys. Commun.},
+  title     = {EPW: A Program for Calculating the Electron--Phonon Coupling Using Maximally Localized Wannier Functions},
+  year      = {2010},
+  number    = {12},
+  pages     = {2140},
+  volume    = {181},
+  publisher = {Elsevier},
+}
+
+@Article{Samsonidze2018,
+  author    = {Samsonidze, Georgy and Kozinsky, Boris},
+  journal   = {Adv. Energy Mater.},
+  title     = {Accelerated Screening of Thermoelectric Materials by First-Principles Computations of Electron--Phonon Scattering},
+  year      = {2018},
+  number    = {20},
+  pages     = {1800246},
+  volume    = {8},
+  publisher = {Wiley Online Library},
+}
+
+@Article{Madsen2018,
+  author    = {Madsen, Georg KH and Carrete, Jes{\'u}s and Verstraete, Matthieu J},
+  journal   = {Comput. Phys. Commun.},
+  title     = {BoltzTraP2, a Program for Interpolating Band Structures and Calculating Semi-Classical Transport Coefficients},
+  year      = {2018},
+  pages     = {140},
+  volume    = {231},
+  publisher = {Elsevier},
+}
+
+@Article{Zhou2021,
+  author    = {Zhou, Jin-Jian and Park, Jinsoo and Lu, I-Te and Maliyov, Ivan and Tong, Xiao and Bernardi, Marco},
+  journal   = {Comput. Phys. Commun.},
+  title     = {Perturbo: A Software Package for ab Initio Electron--Phonon Interactions, Charge Transport and Ultrafast Dynamics},
+  year      = {2021},
+  pages     = {107970},
+  volume    = {264},
+  publisher = {Elsevier},
+}
+
+@Article{Deng2020,
+  author    = {Deng, Tianqi and Wu, Gang and Sullivan, Michael B and Wong, Zicong Marvin and Hippalgaonkar, Kedar and Wang, Jian-Sheng and Yang, Shuo-Wang},
+  journal   = {npj Comput. Mater.},
+  title     = {EPIC STAR: a Reliable and Efficient Approach for Phonon-and Impurity-Limited Charge Transport Calculations},
+  year      = {2020},
+  number    = {1},
+  pages     = {46},
+  volume    = {6},
+  publisher = {Nature Publishing Group UK London},
+}
+
+@Article{Graziosi2023,
+  author    = {Graziosi, Patrizio and Li, Zhen and Neophytou, Neophytos},
+  journal   = {Comput. Phys. Commun.},
+  title     = {ElecTra Code: Full-Band Electronic Transport Properties of Materials},
+  year      = {2023},
+  pages     = {108670},
+  volume    = {287},
+  publisher = {Elsevier},
+}
+
 @Comment{jabref-meta: databaseType:bibtex;}