JOSS paper

.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@v4
+      - 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: joss_paper/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: joss_paper/paper.pdf

joss_paper/paper.bib

@@ -0,0 +1,189 @@
+@article{bennett1976efficient,
+  title={Efficient estimation of free energy differences from Monte Carlo data},
+  author={Bennett, C. H.},
+  journal={Journal of Computational Physics},
+  volume={22},
+  number={2},
+  pages={245-268},
+  year={1976},
+}
+
+@article{case2014ff14sb,
+  title={The FF14SB force field},
+  author={Case, D. and Babin, V. and Berryman, J. and Betz, R. and Cai, Q. and Cerutti, D. and et al.},
+  journal={Amber},
+  volume={14},
+  pages={29-31},
+  year={2014},
+}
+
+@article{chodera2007use,
+  title={Use of the Weighted Histogram Analysis Method for the Analysis of Simulated and Parallel Tempering Simulations},
+  author={Chodera, J. D. and Swope, W. C. and Pitera, J. W. and Seok, C. and Dill, K. A.},
+  journal={J Chem Theory Comput},
+  volume={3},
+  number={1},
+  pages={26-41},
+  year={2007},
+  doi={10.1021/ct0502864},
+}
+
+@article{cummings2021open,
+  title={Open-source molecular modeling software in chemical engineering focusing on the Molecular Simulation Design Framework},
+  author={Cummings, P. T. and McCabe, C. and Iacovella, C. R. and Ledeczi, A. and Jankowski, E. and Jayaraman, A. and et al.},
+  journal={AIChE Journal},
+  volume={67},
+  number={3},
+  pages={e17206},
+  year={2021},
+  doi={https://doi.org/10.1002/aic.17206},
+}
+
+@article{deng2009computations,
+  title={Computations of standard binding free energies with molecular dynamics simulations},
+  author={Deng, Y. and Roux, B.},
+  journal={J Phys Chem B},
+  volume={113},
+  number={8},
+  pages={2234-2246},
+  year={2009},
+  doi={10.1021/jp807701h},
+}
+
+@article{gusev2023active,
+  title={Active Learning Guided Drug Design Lead Optimization Based on Relative Binding Free Energy Modeling},
+  author={Gusev, F. and Gutkin, E. and Kurnikova, M. G. and Isayev, O.},
+  journal={Journal of Chemical Information and Modeling},
+  volume={63},
+  number={2},
+  pages={583-594},
+  year={2023},
+  doi={10.1021/acs.jcim.2c01052},
+}
+
+@article{hedges2023suite,
+  title={A Suite of Tutorials for the BioSimSpace Framework for Interoperable Biomolecular Simulation [Article v1.0]},
+  author={Hedges, L. O. and Bariami, S. and Burman, M. and Clark, F. and Cossins, B. P. and Hardie, A. and et al.},
+  journal={Living Journal of Computational Molecular Science},
+  volume={5},
+  number={1},
+  pages={2375},
+  year={2023},
+  doi={10.33011/livecoms.5.1.2375},
+}
+
+@article{kirkwood1935statistical,
+  title={Statistical mechanics of fluid mixtures},
+  author={Kirkwood, J. G.},
+  journal={The Journal of Chemical Physics},
+  volume={3},
+  number={5},
+  pages={300-313},
+  year={1935},
+}
+
+@article{klimovich2015guidelines,
+  title={Guidelines for the analysis of free energy calculations},
+  author={Klimovich, P. V. and Shirts, M. R. and Mobley, D. L.},
+  journal={J Comput Aided Mol Des},
+  volume={29},
+  number={5},
+  pages={397-411},
+  year={2015},
+  doi={10.1007/s10822-015-9840-9},
+}
+
+@book{merz2010drug,
+  title={Drug design: structure-and ligand-based approaches},
+  author={Merz Jr, K. M. and Ringe, D. and Reynolds, C. H.},
+  year={2010},
+  publisher={Cambridge University Press},
+}
+
+@article{paliwal2011benchmark,
+  title={A Benchmark Test Set for Alchemical Free Energy Transformations and Its Use to Quantify Error in Common Free Energy Methods},
+  author={Paliwal, H. and Shirts, M. R.},
+  journal={J Chem Theory Comput},
+  volume={7},
+  number={12},
+  pages={4115-4134},
+  year={2011},
+  doi={10.1021/ct2003995},
+}
+
+@article{pham2011identifying,
+  title={Identifying low variance pathways for free energy calculations of molecular transformations in solution phase},
+  author={Pham, T. T. and Shirts, M. R.},
+  journal={J Chem Phys},
+  volume={135},
+  number={3},
+  pages={034114},
+  year={2011},
+  doi={10.1063/1.3607597},
+}
+
+@article{phillips2020scalable,
+  title={Scalable molecular dynamics on CPU and GPU architectures with NAMD},
+  author={Phillips, J. C. and Hardy, D. J. and Maia, J. D. C. and Stone, J. E. and Ribeiro, J. V. and Bernardi, R. C. and et al.},
+  journal={The Journal of Chemical Physics},
+  volume={153},
+  number={4},
+  pages={044130},
+  year={2020},
+  doi={10.1063/5.0014475},
+}
+
+@article{pohorille2010good,
+  title={Good practices in free-energy calculations},
+  author={Pohorille, A. and Jarzynski, C. and Chipot, C.},
+  journal={J Phys Chem B},
+  volume={114},
+  number={32},
+  pages={10235-10253},
+  year={2010},
+  doi={10.1021/jp102971x},
+}
+
+@article{pronk2013gromacs,
+  title={GROMACS 4.5: a high-throughput and highly parallel open source molecular simulation toolkit},
+  author={Pronk, S. and Páll, S. and Schulz, R. and Larsson, P. and Bjelkmar, P. and Apostolov, R. and et al.},
+  journal={Bioinformatics},
+  volume={29},
+  number={7},
+  pages={845-854},
+  year={2013},
+  doi={10.1093/bioinformatics/btt055},
+}
+
+@article{shirts2008statistically,
+  title={Statistically optimal analysis of samples from multiple equilibrium states},
+  author={Shirts, M. R. and Chodera, J. D.},
+  journal={J Chem Phys},
+  volume={129},
+  number={12},
+  pages={124105},
+  year={2008},
+  doi={10.1063/1.2978177},
+}
+
+@article{yang2004free,
+  title={Free energy simulations: use of reverse cumulative averaging to determine the equilibrated region and the time required for convergence},
+  author={Yang, W. and Bitetti-Putzer, R. and Karplus, M.},
+  journal={J Chem Phys},
+  volume={120},
+  number={6},
+  pages={2618-2628},
+  year={2004},
+  doi={10.1063/1.1638996},
+}
+
+@article{zwanzig1954high,
+  title={High‐temperature equation of state by a perturbation method. I. Nonpolar gases},
+  author={Zwanzig, R. W.},
+  journal={The Journal of Chemical Physics},
+  volume={22},
+  number={8},
+  pages={1420-1426},
+  year={1954},
+}
+

joss_paper/paper.md

@@ -0,0 +1,126 @@
+---
+title: 'Alchemlyb: The Simple Alchemistry Library'
+tags:
+  - Python
+  - alchemistry
+  - molecular dynamics
+  - free energy
+authors:
+  - name: Zhiyi Wu
+    orcid: 0000-0002-7615-7851
+    equal-contrib: true
+    affiliation: 1
+  - name: David L. Dotson
+    equal-contrib: true # (This is how you can denote equal contributions between multiple authors)
+    orcid: 0000-0001-5879-2942
+    affiliation: 2
+  - name: Michael R. Shirts
+    orcid: 0000-0003-3249-1097
+    affiliation: 3
+  - name: Author with no affiliation
+    corresponding: true # (This is how to denote the corresponding author)
+    affiliation: 3
+affiliations:
+ - name: Exscientia, Oxford, UK
+   index: 1
+ - name: Datryllic LLC, Phoenix, AZ, USA
+   index: 2
+ - name: University of Colorado Boulder, Boulder, Colorado, USA
+   index: 3
+
+date: 29 December 2023
+bibliography: paper.bib
+
+---
+
+# Summary
+
+*Alchemlyb* is a dedicated open-source software package tailored for the analysis of alchemical free energy calculations,
+    an integral part of computational chemistry and biology,
+    most notably in the field of drug discovery.
+The software spans a wide range of functions,
+    starting with the extraction of raw data from molecular dynamics (MD) engines,
+    moving on to data preprocessing tasks such as decorrelation of time series,
+    using various estimators to derive free energy estimates from simulation samples,
+    and finally providing quality analysis tools for data convergence checking.
+
+A distinctive attribute of *alchemlyb* is its streamlined, end-to-end analysis workflow.
+This user-friendly workflow facilitates navigation through the entire analysis pipeline,
+    from the initial data input stage to the final result derivation.
+This attribute enhances accessibility,
+    enabling researchers from diverse scientific backgrounds,
+    and not solely computational chemistry specialists,
+    to utilize *alchemlyb* effectively.
+
+
+# Statement of need
+
+In the pharmaceutical sector, computational chemistry techniques are integral for evaluating potential drug compounds based on their protein binding affinity [@deng2009computations].
+Notably, absolute binding free energy calculations between proteins and ligands or relative binding affinity of ligands to the same protein are routinely employed for this purpose [@merz2010drug].
+The resultant estimates of these free energies are essential for understanding binding affinity throughout various stages of drug discovery, such as hit identification and lead optimization [@merz2010drug].
+Other free energies extracted from simulations are useful in solution thermodynamics, chemical engineering, environmental science, and material science.
+The *alchemlyb* software processes the raw data from MD simulations using key estimators from statistical mechanics, drastically simplifying the process of extracting crucial thermodynamic insights from molecular simulations.
+
+Various molecular dynamics (MD) engines, including GROMACS [@pronk2013gromacs], AMBER [@case2014ff14sb], GOMC [@cummings2021open], and NAMD [@phillips2020scalable],
+    offer distinct tools for performing free energy calculations.
+However, the diversity in output formats and analysis tools among different MD engines complicates the research process.
+Data generated by each engine requires individualized processing and analysis methods,
+    hindering seamless collaboration and comparison of results.
+
+
+The [alchemical-analysis.py](https://github.com/MobleyLab/alchemical-analysis) tool [@klimovich2015guidelines], which preceeded *alchemlyb*, addressed this problem.
+Now that [alchemical-analysis.py](https://github.com/MobleyLab/alchemical-analysis) has been deprecated,
+    *alchemlyb* continues to provide a unified, engine-agnostic analysis workflow.
+Unlike its predecessor, *alchemlyb* breaks down components of the workflow into modular tools, 
+    allowing users to more easily customize their analysis.
+This innovation enables consistent processing of free energy data from diverse MD engines, 
+    facilitating streamlined comparison and combination of results.
+
+Notably, *alchemlyb*'s robust and user-friendly nature has led to its integration into other automated workflow libraries such as BioSimSpace [@hedges2023suite].
+This further enhances its accessibility and usability within broader scientific workflows,
+    reinforcing its position as a versatile and essential tool in the field of computational chemistry [^1].
+
+[^1]: As of 29/12/2023, *alchemlyb* has been downloaded 23,922 times from [conda-forge](https://anaconda.org/conda-forge/alchemlyb/files).
+
+# Implementation
+
+Solvation free energy, a key physical property often computed by computational chemists, involves constructing two end states:
+    one where the ligand interacts with water and itself (coupled state),
+    and the other where the ligand interacts only with itself, mimicking the pure solvent and ligand in the gas phase (decoupled state).
+The solvation free energy is then obtained by calculating the free energy difference between these two end states.
+To achieve this, it is crucial to ensure sufficient overlap in phase space between the coupled and decoupled states, a condition often challenging to achieve.
+Overlapping is facilitated by introducing a parameter `lambda` ($\lambda $) that connects the two end-states, resulting in a series of intermediate states.
+MD engines simulate the system at these states, generating and accumulating free energy data.
+
+*alchemlyb* offers specific parsers designed to load raw free energy data from various MD engines, converting them into standard `pandas` `DataFrames`.
+Two types of free energy data are considered: 
+    Hamiltonian gradients (`dHdl`, $dH/d\lambda$) at all lambda states, suitable for thermodynamic integration (TI) estimators [@kirkwood1935statistical],
+    and reduced potential energy differences between lambda states (`u_nk`, $u_{nk}$), which are used for free energy perturbation (FEP) estimators [@zwanzig1954high],
+
+In *alchemlyb*, TI [@paliwal2011benchmark] and TI with Gaussian quadrature [@gusev2023active] estimators are implemented in the TI category of estimators.
+FEP category estimators include Bennett Acceptance Ratio (BAR) [@bennett1976efficient] and Multistate BAR (MBAR) [@shirts2008statistically].
+These estimators assume uncorrelated samples, and *alchemlyb* provides tools for data resampling based on autocorrelation times [@chodera2007use].
+
+To evaluate the accuracy of the free energy estimate, *alchemlyb* offers a range of assessment tools.
+The error of the TI method is correlated with the average curvature [@pham2011identifying],
+    while the error of FEP estimators depends on the overlap in sampled energy distributions [@pohorille2010good].
+*alchemlyb* visualizes the smoothness of the integrand for TI estimators and the overlap matrix for FEP estimators.
+Additionally, the accumulated samples should be collected from equilibrated simulations,
+    and *alchemlyb* has tools for plotting the convergence of the free energy estimate as a function of simulation time [@yang2004free] to detect potentially un-equilibrated data.
+
+*Alchemlyb* offers all these tools as a library for users to customize each stage of the analysis (Figure 1).
+Additionally, *alchemlyb* provides an automated end-to-end workflow that reads in the raw input data and performs decorrelation, estimation, and quality plotting of the estimate.
+This workflow allows for the estimation of quantities such as solvation free energy with minimal code.
+Moreover, this facilitates more complex calculations, such as absolute binding free energy, which is the free energy difference between the solvation free energy of the ligand in water and the solvation free energy of the ligand in the protein's binding pocket. 
+
+![The building blocks of *alchemlyb*](Fig1.pdf)
+
+
+
+# Acknowledgements
+
+O.B. and D.D. designed the project. Z.W., D.D., contributed to the new features. Z.W., D.D., O.B. maintain the codebase. Z.W., M.R.S wrote the manuscript.
+
+# References
+
+