JOSS paper preparation

[danielfromearth]

Manuscript draft

This PR is intended for revisions and improvements to the manuscript draft being prepared for submission to the Journal of Open Source Software (JOSS).

Paper format: The manuscript is prepared as a Markdown (paper.md) file with references in a paper.bib file, following the JOSS formatting guidelines.

For a PDF preview: With docker installed locally, a PDF preview of the draft manuscript can be generated, by running the following from the earthaccess root directory (as described in the JOSS guidelines's docker section):

docker run --rm \
    --volume $PWD/paper:/data \
    --user $(id -u):$(id -g) \
    --env JOURNAL=joss \
    openjournals/inara

---

📚 Documentation preview 📚: https://earthaccess--1249.org.readthedocs.build/en/1249/

[github-actions]

👈 Launch a binder notebook on this branch for commit 16fb7b9

I will automatically update this comment whenever this PR is modified

👈 Launch a binder notebook on this branch for commit 38cad6a

👈 Launch a binder notebook on this branch for commit 6af0701

👈 Launch a binder notebook on this branch for commit 767ad52

👈 Launch a binder notebook on this branch for commit dce192c

👈 Launch a binder notebook on this branch for commit ae74db7

👈 Launch a binder notebook on this branch for commit 05f7616

👈 Launch a binder notebook on this branch for commit bb5fd2f

👈 Launch a binder notebook on this branch for commit db3a969

👈 Launch a binder notebook on this branch for commit cf0f975

👈 Launch a binder notebook on this branch for commit 5852fa8

👈 Launch a binder notebook on this branch for commit 1b479c5

👈 Launch a binder notebook on this branch for commit 5029e59

👈 Launch a binder notebook on this branch for commit 2f8cab3

👈 Launch a binder notebook on this branch for commit 0e89b5e

👈 Launch a binder notebook on this branch for commit 5691bf8

👈 Launch a binder notebook on this branch for commit 1af1724

[jules32]

Hi! Great work on this Danny! A few commits and some suggestions to consider.

[jules32]

I know some decisions of what not to do were really important. If I remember correctly, it was features that were discussed then developed elsewhere rather than earthaccess. I'd suggest emphasizing this here, it's a big deal!

[danielfromearth]

I put in a blurb about this below ("Contribute upstream, don't accumulate") – could really use more eyes on it!

[mfisher87]

We could symlink this in to our docs!

[mfisher87]

after the v1.0.0 release

I would say let's not wait. We've demonstrated impact and I think that matters more.

Alternatively, let's just go 1.0.0 in the short term and be OK with quickly moving to a 2.0.0 release with breaking changes.

I think both are fine, but the latter sets more a precedent of maintainers taking the user impact of breaking changes too lightly.

[danielfromearth]

after the v1.0.0 release

I would say let's not wait. We've demonstrated impact and I think that matters more.

Alternatively, let's just go 1.0.0 in the short term and be OK with quickly moving to a 2.0.0 release with breaking changes.

I think both are fine, but the latter sets more a precedent of maintainers taking the user impact of breaking changes too lightly.

I'm fine with either too. I also think the decision could be on hold until one of the two things – (i) co-author reviews/revisions, (ii) development for v1.0.0 – is completely ready-to-go.

done

[JessicaS11]

Suggested change

	The target audience includes Earth scientists, remote sensing researchers, climate modelers,
	hydrologists, ecologists, and any researcher, application developer, or educator who needs
	to work with NASA Earth science data. The library is designed to be approachable for those new to Python -- with a
	The target audience includes Earth scientists, remote sensing researchers, modelers, and any researcher, data user, application developer, or educator who needs
	to work with NASA Earth science data. The library is designed to be approachable for those new to Python -- with a

We could add a more specific list of Earth scientists (hydrologists, ecologists, oceanographers, cryospheric scientists, climate modelers, some other broad categories, etc.) as another sentence (not sure how close to the word limit we are).

[danielfromearth]

sure, that sounds fine to me. How about flipping the order and expanding it to something like...

Suggested change

	The target audience includes Earth scientists, remote sensing researchers, climate modelers,
	hydrologists, ecologists, and any researcher, application developer, or educator who needs
	to work with NASA Earth science data. The library is designed to be approachable for those new to Python -- with a
	The target audience spans the breadth of Earth system science, including atmospheric scientists, oceanographers, cryospheric researchers, hydrologists, ecologists, biogeochemists, land surface modelers, air quality researchers, natural hazards researchers, and agricultural scientists. It also serves remote sensing researchers, application developers, natural resource and environmental decision makers, and educators who work with NASA Earth science data. The library is designed to be approachable for those new to Python -- with a

[asteiker]

I know the list can go on and on but I think another important audience to emphasize is in regards to operational weather and natural disaster monitoring.

[JessicaS11]

@asteiker If you propose suggested text I'm happy to read it over and commit it.

[danielfromearth]

@asteiker, @JessicaS11,
I don't know, this list is already quite long. Maybe we should go the other direction – consolidate it to be shorter, but not as short as the original? How about this:

Suggested change

	The target audience includes Earth scientists, remote sensing researchers, climate modelers,
	hydrologists, ecologists, and any researcher, application developer, or educator who needs
	to work with NASA Earth science data. The library is designed to be approachable for those new to Python -- with a
	The target audience spans Earth system science — from atmospheric scientists and oceanographers to ecologists and land surface modelers — as well as operational communities such as weather forecasters and disaster response practitioners. It also serves remote sensing researchers, application developers, educators, and decision-makers who work with NASA Earth science data. The library is designed to be approachable for those new to Python -- with a

[asteiker]

I like this update!

[JessicaS11]

Suggested change

	University of New Hampshire), private industry (Coiled, Development Seed),
	Goddard, University of New Hampshire, University of Maryland), private industry (Coiled, Development Seed),

[danielfromearth]

@JessicaS11 Perhaps we need to be more specific than "Goddard" here? GES DISC is included in the DAAC listing, so is it the Ocean Ecology Lab that's not yet represented?

[JessicaS11]

Or we could list GES DISC - I was just trying to have more than one "federal and academic institutions" listed.

[danielfromearth]

@JessicaS11
Hmm, GES DISC is already in the previous phrase that lists the DAACs.

Not sure if this would be better, but perhaps we simply list these organizations (USGS, Univ. New Hampshire, Univ. Maryland) without saying "federal and academic institutions"?

[JessicaS11]

@danielfromearth Love this - thank you so much for putting it together!

Sorry it looks like a lot of edits - most of them are pretty minor (grammatical or editorial), with a few suggestions for the text. All that said, none of them are non-starters for me.

[asteiker]

Such great work @danielfromearth - Thank you for spearheading this!

[asteiker]

Noting for now, but this may be described below: A key feature worth emphasizing is the fact that the code does not need to be modified depending on compute location, which was a notable Earthdata Cloud pain point based on direct user engagement.

[asteiker]

How did you perform this search, @danielfromearth ? I'm interested in a better way to surface research outcomes utilizing earthaccess (see #1216) so maybe your process could be applied somehow here.

[danielfromearth]

@asteiker, I think I found them using Google Scholar, but unfortunately don't remember exactly the search terms. I seem to remember searching via the Zenodo DOI too.

[asteiker]

Cool, thanks!

[asteiker]

Suggested change

	Earthdata tutorials, including <https://www.earthdata.nasa.gov/data/tools/earthaccess>, has been presented at multiple large professional meetings (including several American Geophysical Union Annual and Earth System Information Partnership (ESIP) meetings), and was the subject of
	Earthdata tools catalog, including <https://www.earthdata.nasa.gov/data/tools/earthaccess>, and other NASA Earthdata tutorials, and has been presented at multiple large professional meetings (including several American Geophysical Union Annual and Earth System Information Partnership (ESIP) meetings), and was the subject of

[JessicaS11]

Suggested change

	Earthdata tutorials, including <https://www.earthdata.nasa.gov/data/tools/earthaccess>, has been presented at multiple large professional meetings (including several American Geophysical Union Annual and Earth System Information Partnership (ESIP) meetings), and was the subject of
	Earthdata tools catalog (<https://www.earthdata.nasa.gov/data/tools/earthaccess>) and other NASA Earthdata tutorials and has been presented at multiple large professional meetings (including several American Geophysical Union Annual and Earth System Information Partnership (ESIP) meetings), and was the subject of

[danielfromearth]

@JessicaS11, @asteiker,

Suggested change

	Earthdata tutorials, including <https://www.earthdata.nasa.gov/data/tools/earthaccess>, has been presented at multiple large professional meetings (including several American Geophysical Union Annual and Earth System Information Partnership (ESIP) meetings), and was the subject of
	Earthdata tools catalog (<https://www.earthdata.nasa.gov/data/tools/earthaccess>) and in other NASA Earthdata tutorials. It has been presented at multiple large professional meetings -- including several American Geophysical Union (AGU) Annual Meetings and Earth System Information Partnership (ESIP) meetings -- and was the subject of

[asteiker]

I like it!

[danielfromearth]

Hey all, it's been a couple weeks since activity here, so pinging to keep this moving. Would be great to have a complete draft ready to submit before Northern Hemisphere summer!

If there's not a specific note next to your username, a general read-through and comments are welcome:

@andypbarrett
@betolink (there's also this specific question about region-detection)
@chuckwondo (there's also this specific question about region-detection)
@jhkennedy
@jrbourbeau
@battistowx
@Sherwin-14
@jules32 (there's a placeholder to fill in the Openscapes award number)
@asteiker (there are a few follow-ups to your previous comments to address)
@JessicaS11 (there are a few follow-ups to your previous comments to address)

[jules32]

Suggested change

	(ESDS) program through the Openscapes project (NASA award **______**, PIs Julia
	(ESDS) program through the NASA Openscapes project (NASA award #20-TWSC20-2-0003 “Openscapes: Enabling a new era of science on the cloud, in response to the 2020 NASA ROSES Element E2”,

[jules32]

Suggested change

	a NASA ESDS Tech Spotlight presentation. The documentation includes executable Jupyter
	a NASA ESDS Tech Spotlight presentation (see <https://earthaccess.readthedocs.io> homepage for links to recent slides and recordings). The documentation includes executable Jupyter

[jules32]

Thank you @danielfromearth ! I've added the award number. Thanks for leading this!

[asteiker]

I like this update!

[asteiker]

Suggested change

	3. **Access**: Detects at runtime whether the process is running within AWS `us-west-2`
	3. **Access**: Attempts to detect at runtime whether the process is running within AWS `us-west-2`

[asteiker]

Suggested change

	access or HTTPS downloads otherwise. Files can be opened as `fsspec`-compatible
	access or HTTPS downloads otherwise. Users can manually specify an access path if needed. Files can be opened as `fsspec`-compatible

[asteiker]

Cool, thanks!

[asteiker]

I like it!