Skip to content

Commit 2cd7c83

Browse files
HadenSmithHadenSmith
committed
Editing and improving JOSS paper
1 parent 6fcd54d commit 2cd7c83

7 files changed

Lines changed: 343 additions & 54 deletions

File tree

‎CITATION.cff‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ message: "If you use this software, please cite it as below."
33
type: software
44
title: "Numerics"
55
version: "2.0.0"
6-
date-released: "2025-01-01"
6+
date-released: "2026-03-08"
77
license: BSD-3-Clause
88
repository-code: "https://github.com/USACE-RMC/Numerics"
99
url: "https://github.com/USACE-RMC/Numerics"
@@ -27,7 +27,7 @@ authors:
2727
given-names: "C. Haden"
2828
email: "cole.h.smith@usace.army.mil"
2929
affiliation: "U.S. Army Corps of Engineers, Risk Management Center"
30-
orcid: "https://orcid.org/0000-0001-7881-5814"
30+
orcid: "https://orcid.org/0000-0002-4651-9890"
3131
- family-names: "Fields"
3232
given-names: "Woodrow L."
3333
affiliation: "U.S. Army Corps of Engineers, Risk Management Center"
@@ -39,7 +39,7 @@ authors:
3939
affiliation: "U.S. Army Corps of Engineers, Risk Management Center"
4040
- family-names: "Beam"
4141
given-names: "Brennan"
42-
affiliation: "U.S. Army Corps of Engineers, Risk Management Center"
42+
affiliation: "U.S. Army Corps of Engineers, Hydrologic Engineering Center"
4343
- family-names: "Skahill"
4444
given-names: "Brian"
45-
affiliation: "U.S. Army Corps of Engineers, Risk Management Center"
45+
affiliation: "Fariborz Maseeh Department of Mathematics and Statistics, Portland State University"

‎JOSS_TODO.md‎

Lines changed: 124 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,124 @@
1+
# JOSS Submission Checklist
2+
3+
Pre-submission checklist for the Journal of Open Source Software (JOSS).
4+
JOSS review criteria: https://joss.readthedocs.io/en/latest/review_criteria.html
5+
JOSS paper format: https://joss.readthedocs.io/en/latest/paper.html (750-1,750 words)
6+
7+
---
8+
9+
## Section A: JOSS Requirements Compliance
10+
11+
### Software Requirements
12+
13+
| # | Requirement | Status | Evidence |
14+
|---|-------------|--------|----------|
15+
| 1 | Open source license (OSI-approved) | MET | BSD-3-Clause in `LICENSE`; declared in `CITATION.cff` |
16+
| 2 | Version control (public repository) | MET | https://github.com/USACE-RMC/Numerics |
17+
| 3 | README with project description | MET | `README.md` with description, install, docs, badges |
18+
| 4 | Installation instructions | MET | NuGet install in `README.md` and `docs/getting-started.md` |
19+
| 5 | Usage examples | MET | `docs/getting-started.md`, `docs/index.md` Quick Start, paper Example section |
20+
| 6 | API documentation | MET | 25+ Markdown files in `docs/`; XML documentation generated from source |
21+
| 7 | Community guidelines (CONTRIBUTING) | MET | `CONTRIBUTING.md` with bug reports, PRs, DCO, security policy |
22+
| 8 | Code of Conduct | MET | `CODE_OF_CONDUCT.md` (Contributor Covenant v2.1) |
23+
| 9 | Automated tests | MET | 1,001 MSTest methods across 149 test classes in `Test_Numerics/` |
24+
| 10 | Continuous integration | MET | 3 GitHub Actions workflows (`Integration.yml`, `Snapshot.yml`, `Release.yml`) |
25+
| 11 | Substantial scholarly effort | MET | 60,000+ LOC library, 34,000+ LOC tests, 224 source files |
26+
| 12 | Sustained development history | MET | 2.5 years (Sep 2023 - Mar 2026), 270+ commits, 7+ contributors |
27+
| 13 | Statement of need | MET | Paper includes Statement of Need section |
28+
| 14 | State of the field / related work | MET | Paper includes State of the Field section |
29+
| 15 | Zero or documented dependencies | MET | Zero runtime dependencies for .NET 8+; polyfills only for .NET Framework 4.8.1 |
30+
| 16 | Functionality matches claims | MET | All claims verified: 43 distributions, 8 MCMC samplers, 5+ optimizers, copulas, ML, bootstrap |
31+
| 17 | Software installable | REMAINING | Verify NuGet package `RMC.Numerics` is published and accessible on nuget.org |
32+
33+
### Paper Requirements
34+
35+
| # | Requirement | Status | Evidence |
36+
|---|-------------|--------|----------|
37+
| 18 | Paper in `paper/paper.md` | MET | `paper/paper.md` with YAML frontmatter |
38+
| 19 | Bibliography in `paper/paper.bib` | MET | `paper/paper.bib` with 23 references |
39+
| 20 | Summary section | MET | Lines 39-41 |
40+
| 21 | Statement of Need section | MET | Lines 43-54 |
41+
| 22 | State of the Field section | MET | Lines 56-62 |
42+
| 23 | Research impact / ongoing projects | MET | Lines 64-75 (6 production applications) |
43+
| 24 | Acknowledgements | MET | Lines 119-121 |
44+
| 25 | AI Usage Disclosure | MET | Lines 115-117 |
45+
| 26 | Word count 750-1,750 | MET | ~1,215 words (within range) |
46+
| 27 | Submitting author ORCID | MET | `0000-0002-4651-9890` for C. Haden Smith |
47+
| 28 | Author affiliations | MET | 3 affiliations listed |
48+
| 29 | All references have DOIs where available | MET | 15 DOIs + 7 URLs for web-only resources |
49+
| 30 | Code example in paper | MET | Lines 85-113 (bootstrap uncertainty analysis) |
50+
51+
### Repository Metadata
52+
53+
| # | Requirement | Status | Evidence |
54+
|---|-------------|--------|----------|
55+
| 31 | CITATION.cff | MET | `CITATION.cff` (CFF v1.2.0, BSD-3-Clause) |
56+
| 32 | codemeta.json | MET | `codemeta.json` created |
57+
| 33 | Version tag matching submission | REMAINING | Need to create `v2.0.0` tag |
58+
| 34 | Archived release with DOI | REMAINING | Need Zenodo archive |
59+
60+
---
61+
62+
## Section B: Step-by-Step Pre-Submission Actions
63+
64+
Complete these steps in order before submitting to JOSS.
65+
66+
### Step 1: Review and Finalize Paper Edits
67+
- [ ] Review all changes made to `paper/paper.md` (code example, Software Design rewrite, claim softening, ML mention, Gelman-Rubin citation)
68+
- [ ] Review all changes to `paper/paper.bib` (ribatet fix, hoffman URL, Gelman-Rubin 1992 addition)
69+
- [ ] Review `CITATION.cff` changes (ORCID, affiliations, date)
70+
- [ ] Review `README.md` changes (badges, contributing link, doc table reorder)
71+
- [ ] Proofread final paper for any remaining issues
72+
- [ ] Optionally encourage co-authors to register ORCIDs and add them to `paper.md`
73+
74+
### Step 2: Verify NuGet Package
75+
- [ ] Confirm `RMC.Numerics` is published and accessible at https://www.nuget.org/packages/RMC.Numerics/
76+
- [ ] If not on nuget.org, consider publishing there (JOSS reviewers will try to install it)
77+
- [ ] Verify installation works: `dotnet add package RMC.Numerics`
78+
79+
### Step 3: Run Full Test Suite
80+
- [ ] Run `dotnet test` across all target frameworks to confirm no regressions
81+
- [ ] Verify all 1,001+ tests pass
82+
83+
### Step 4: CI Pipeline Transparency (Recommended)
84+
- [ ] The CI uses shared workflows from `HydrologicEngineeringCenter/dotnet-workflows` which are opaque to reviewers
85+
- [ ] Consider adding a brief comment in the workflow YAML or a CI section in the README explaining what the pipeline does
86+
- [ ] The CI config specifies `dotnet-version: '9.0.x'` — consider testing against all target frameworks (8.0, 9.0, 10.0) or documenting that the shared workflow handles multi-targeting
87+
88+
### Step 5: Create Release Tag
89+
- [ ] Merge the `bugfixes-and-enhancements` branch to `main`
90+
- [ ] Create git tag: `git tag v2.0.0`
91+
- [ ] Push tag: `git push origin v2.0.0`
92+
- [ ] Create a GitHub Release from the tag with release notes
93+
94+
### Step 6: Archive on Zenodo
95+
- [ ] Go to https://zenodo.org and log in with GitHub
96+
- [ ] Enable the `USACE-RMC/Numerics` repository in Zenodo's GitHub integration
97+
- [ ] Zenodo will automatically archive the GitHub Release and mint a DOI
98+
- [ ] Copy the Zenodo DOI badge and add it to `README.md`
99+
- [ ] Update `CITATION.cff` with the Zenodo DOI if desired
100+
101+
### Step 7: Submit to JOSS
102+
- [ ] Go to https://joss.theoj.org/papers/new
103+
- [ ] Enter the repository URL: `https://github.com/USACE-RMC/Numerics`
104+
- [ ] Enter the Zenodo archive DOI
105+
- [ ] Confirm software version matches the tagged release
106+
- [ ] Submit the paper
107+
- [ ] The JOSS editorial bot will open a review issue — respond promptly to any reviewer questions
108+
109+
### Step 8: Post-Submission
110+
- [ ] Add the JOSS status badge to `README.md` once the review issue is created:
111+
```markdown
112+
[![status](https://joss.theoj.org/papers/<DOI>/status.svg)](https://joss.theoj.org/papers/<DOI>)
113+
```
114+
- [ ] Monitor the review issue for editor/reviewer feedback
115+
- [ ] Address any review comments promptly (JOSS reviews typically take 4-8 weeks)
116+
117+
---
118+
119+
## Notes
120+
121+
- **Word limit**: JOSS papers should be 750-1,750 words (https://joss.readthedocs.io/en/latest/paper.html). Current paper is ~1,215 words.
122+
- **"Jery R. Stedinger"**: This spelling in `paper.bib` is correct (confirmed on USGS publications). Be prepared to explain if a reviewer questions it.
123+
- **England 2019 vs 2018**: Bulletin 17C was originally published March 2018; the `2019` date refers to the v1.1 revision. Both are acceptable in the literature.
124+
- **ter Braak citation**: The 2008 paper describes DE-MCzs (with snooker updater). The library has both `DEMCz` and `DEMCzs` classes. The citation is appropriate since the 2008 paper supersedes the 2006 original.

‎Numerics.sln‎

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,18 @@
11

22
Microsoft Visual Studio Solution File, Format Version 12.00
3-
# Visual Studio Version 17
4-
VisualStudioVersion = 17.9.34723.18
3+
# Visual Studio Version 18
4+
VisualStudioVersion = 18.2.11430.68 d18.0
55
MinimumVisualStudioVersion = 10.0.40219.1
66
Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Numerics", "Numerics\Numerics.csproj", "{9C8B75DE-ABF2-42D3-96C7-18405AD16488}"
77
EndProject
88
Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Test_Numerics", "Test_Numerics\Test_Numerics.csproj", "{C6800F28-6FBE-48D8-A2F8-B1B396671D36}"
99
EndProject
10+
Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Solution Items", "Solution Items", "{1D4228F2-A9A8-449E-A6EB-99E60638A048}"
11+
ProjectSection(SolutionItems) = preProject
12+
paper\paper.bib = paper\paper.bib
13+
paper\paper.md = paper\paper.md
14+
EndProjectSection
15+
EndProject
1016
Global
1117
GlobalSection(SolutionConfigurationPlatforms) = preSolution
1218
Debug|Any CPU = Debug|Any CPU

‎README.md‎

Lines changed: 12 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,9 @@
11
# Numerics
22

3+
[![CI](https://github.com/USACE-RMC/Numerics/actions/workflows/Integration.yml/badge.svg)](https://github.com/USACE-RMC/Numerics/actions/workflows/Integration.yml)
4+
[![NuGet](https://img.shields.io/nuget/v/RMC.Numerics)](https://www.nuget.org/packages/RMC.Numerics/)
5+
[![License: BSD-3-Clause](https://img.shields.io/badge/License-BSD_3--Clause-blue.svg)](LICENSE)
6+
37
***Numerics*** is a free and open-source numerical computing library for .NET developed by the U.S. Army Corps of Engineers Risk Management Center (USACE-RMC). It provides methods and algorithms for probability distributions, statistical analysis, numerical methods, optimization, machine learning, and Bayesian MCMC sampling — with a focus on hydrological and risk assessment applications.
48

59
## Supported Frameworks
@@ -21,12 +25,12 @@ Or search for [RMC.Numerics](https://www.nuget.org/packages/RMC.Numerics/) in th
2125

2226
| Section | Topics |
2327
|---------|--------|
24-
| [Distributions](docs/distributions/univariate.md) | 40+ univariate distributions, parameter estimation, uncertainty analysis, copulas, multivariate distributions |
25-
| [Statistics](docs/statistics/descriptive.md) | Descriptive statistics, goodness-of-fit metrics, hypothesis tests |
28+
| [Mathematics](docs/mathematics/integration.md) | Integration, differentiation, optimization, root finding, linear algebra, ODE solvers, special functions |
2629
| [Data](docs/data/interpolation.md) | Interpolation, linear regression, time series analysis |
27-
| [Machine Learning](docs/machine-learning.md) | GLM, decision trees, random forests, KNN, naive Bayes, k-means, GMM |
30+
| [Statistics](docs/statistics/descriptive.md) | Descriptive statistics, goodness-of-fit metrics, hypothesis tests |
31+
| [Distributions](docs/distributions/univariate.md) | 40+ univariate distributions, parameter estimation, uncertainty analysis, copulas, multivariate distributions |
32+
| [Machine Learning](docs/machine-learning/machine-learning.md) | GLM, decision trees, random forests, KNN, naive Bayes, k-means, GMM |
2833
| [Sampling](docs/sampling/mcmc.md) | MCMC (RWMH, ARWMH, DE-MCz, HMC, NUTS, Gibbs), random generation, convergence diagnostics |
29-
| [Mathematics](docs/mathematics/integration.md) | Integration, differentiation, optimization, root finding, linear algebra, ODE solvers, special functions |
3034
| [References](docs/references.md) | Consolidated bibliography |
3135

3236
## Support
@@ -35,6 +39,10 @@ USACE-RMC is committed to maintaining and supporting the library with regular up
3539

3640
The repository includes a unit testing library with over 1,000 tests that also serve as usage examples for the classes and methods in the library.
3741

42+
## Contributing
43+
44+
Contributions are welcome. Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on bug reports, feature requests, and pull requests.
45+
3846
## License
3947

4048
See [LICENSE](LICENSE) for details.

‎codemeta.json‎

Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
{
2+
"@context": "https://doi.org/10.5063/schema/codemeta-2.0",
3+
"@type": "SoftwareSourceCode",
4+
"name": "Numerics",
5+
"description": "A free and open-source .NET library providing numerical methods, probability distributions, statistical analysis, and Bayesian inference tools for quantitative risk assessment in water resources engineering.",
6+
"version": "2.0.0",
7+
"dateCreated": "2023-09-28",
8+
"dateModified": "2026-03-08",
9+
"license": "https://spdx.org/licenses/BSD-3-Clause",
10+
"codeRepository": "https://github.com/USACE-RMC/Numerics",
11+
"issueTracker": "https://github.com/USACE-RMC/Numerics/issues",
12+
"programmingLanguage": {
13+
"@type": "ComputerLanguage",
14+
"name": "C#",
15+
"url": "https://learn.microsoft.com/en-us/dotnet/csharp/"
16+
},
17+
"runtimePlatform": ".NET 8.0, 9.0, 10.0, .NET Framework 4.8.1",
18+
"operatingSystem": "Windows, Linux, macOS",
19+
"keywords": [
20+
"statistics",
21+
"probability distributions",
22+
"MCMC",
23+
"hydrology",
24+
"flood frequency analysis",
25+
"copulas",
26+
"L-moments",
27+
"optimization",
28+
".NET",
29+
"C#",
30+
"numerical methods",
31+
"Bayesian inference",
32+
"machine learning",
33+
"risk assessment"
34+
],
35+
"author": [
36+
{
37+
"@type": "Person",
38+
"givenName": "C. Haden",
39+
"familyName": "Smith",
40+
"@id": "https://orcid.org/0000-0002-4651-9890",
41+
"affiliation": {
42+
"@type": "Organization",
43+
"name": "U.S. Army Corps of Engineers, Risk Management Center"
44+
}
45+
},
46+
{
47+
"@type": "Person",
48+
"givenName": "Woodrow L.",
49+
"familyName": "Fields",
50+
"affiliation": {
51+
"@type": "Organization",
52+
"name": "U.S. Army Corps of Engineers, Risk Management Center"
53+
}
54+
},
55+
{
56+
"@type": "Person",
57+
"givenName": "Julian",
58+
"familyName": "Gonzalez",
59+
"affiliation": {
60+
"@type": "Organization",
61+
"name": "U.S. Army Corps of Engineers, Risk Management Center"
62+
}
63+
},
64+
{
65+
"@type": "Person",
66+
"givenName": "Sadie",
67+
"familyName": "Niblett",
68+
"affiliation": {
69+
"@type": "Organization",
70+
"name": "U.S. Army Corps of Engineers, Risk Management Center"
71+
}
72+
},
73+
{
74+
"@type": "Person",
75+
"givenName": "Brennan",
76+
"familyName": "Beam",
77+
"affiliation": {
78+
"@type": "Organization",
79+
"name": "U.S. Army Corps of Engineers, Hydrologic Engineering Center"
80+
}
81+
},
82+
{
83+
"@type": "Person",
84+
"givenName": "Brian",
85+
"familyName": "Skahill",
86+
"@id": "https://orcid.org/0000-0002-2164-0301",
87+
"affiliation": {
88+
"@type": "Organization",
89+
"name": "Fariborz Maseeh Department of Mathematics and Statistics, Portland State University"
90+
}
91+
}
92+
],
93+
"funder": {
94+
"@type": "Organization",
95+
"name": "U.S. Army Corps of Engineers"
96+
},
97+
"developmentStatus": "active"
98+
}

‎paper/paper.bib‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -197,3 +197,52 @@ @book{rao2000
197197
year = {2000},
198198
isbn = {978-0849300837}
199199
}
200+
201+
@manual{viglione2024nsrfa,
202+
author = {Viglione, Alberto},
203+
title = {nsRFA: Non-supervised Regional Frequency Analysis},
204+
year = {2024},
205+
note = {R package version 0.7-17},
206+
url = {https://CRAN.R-project.org/package=nsRFA}
207+
}
208+
209+
@manual{ribatet2022spatialextremes,
210+
author = {Ribatet, Mathieu},
211+
title = {SpatialExtremes: Modelling Spatial Extremes},
212+
year = {2022},
213+
note = {R package version 2.1-0},
214+
url = {https://CRAN.R-project.org/package=SpatialExtremes}
215+
}
216+
217+
@article{rinnooy1987,
218+
author = {Rinnooy Kan, A. H. G. and Timmer, G. T.},
219+
title = {Stochastic global optimization methods part {II}: Multi level methods},
220+
journal = {Mathematical Programming},
221+
volume = {39},
222+
number = {1},
223+
pages = {57--78},
224+
year = {1987},
225+
doi = {10.1007/BF02592071}
226+
}
227+
228+
@article{hoffman2014,
229+
author = {Hoffman, Matthew D. and Gelman, Andrew},
230+
title = {The {No-U-Turn} Sampler: Adaptively setting path lengths in {Hamiltonian Monte Carlo}},
231+
journal = {Journal of Machine Learning Research},
232+
volume = {15},
233+
number = {47},
234+
pages = {1593--1623},
235+
year = {2014},
236+
url = {https://jmlr.org/papers/v15/hoffman14a.html}
237+
}
238+
239+
@article{gelmanrubin1992,
240+
author = {Gelman, Andrew and Rubin, Donald B.},
241+
title = {Inference from Iterative Simulation Using Multiple Sequences},
242+
journal = {Statistical Science},
243+
volume = {7},
244+
number = {4},
245+
pages = {457--472},
246+
year = {1992},
247+
doi = {10.1214/ss/1177011136}
248+
}

0 commit comments

Comments
 (0)