[ewels]

Description of the change

Hi folks! PR to accompany #189

Also fixes / impacts hyperspy/hyperspy#994 and hyperspy/hyperspy#993

Warning

This is for v2 of the eelsdb.eu API, which is not yet live. I'm opening it as a draft to get feedback before we go live. You can test it locally by setting the environment var EELSDB_API_URL:

export EELSDB_API_URL=https://api.dev.eelsdb.eu/v2/spectra

This PR updates exspy.data.eelsdb to work with the new v2 API. Each spectrum is now loaded from its HSPY file, so all spectra load, including gas-phase ones (new phase argument).

Specifically:

• Deprecate the *_compare arguments and string resolution values.
• Ignore unsupported order keys with a warning.
• Raise ValueError with the server's message for invalid arguments.
• Allow overriding the API URL with EELSDB_API_URL.
• Reuse one HTTP session and request only max_n records when small.
• Update the gallery example, which sorted by spectrum type.

Behaviour changes for existing scripts:

• Gas-phase spectra (666 from the Corex database) are now included by default.
  • Are you happy with this change? Users fitting solid-state spectra may not expect molecular spectra, and broad queries download more files. Defaulting to phase=["solid", "liquid"] would keep results as before.
• monochromated=False now means "recorded as not monochromated".
  • The old API ignored it; about 125 older spectra have no recorded value, so they drop out.
• original_metadata.json holds the API v2 record, so scripts reading v1 fields from it will need updating.
• title matches the whole phrase in titles and descriptions; v1 matched word by word.

AI-assisted contribution?

• Is this an AI-assisted contribution? If yes, and non-trivial, link to the accepted proposal:
  - [ ] N/A (human-only contribution or trivial change)
  - [ ] Proposal accepted: <link to PR in hyperspy/hyperspy-proposals>

AI-assisted (Claude Code). No proposal yet: it ports an existing function to the new API, but it does deprecate arguments, so happy to write one if you consider it non-trivial.

Progress of the PR

• if AI-assisted, Assisted-by: <tool>:<model> in every commit and no AI Co-authored-by: trailer,
• Change implemented (can be split into several points),
• docstring updated (if appropriate),
• update user guide (if appropriate),
• added tests,
• add a changelog entry in the upcoming_changes folder (see upcoming_changes/README.rst),
• Check formatting of the changelog entry (and eventual user guide changes) in the docs/readthedocs.org:exspy build of this PR (link in github checks)
• ready for review.

Minimal example of the bug fix or the new feature

Until API v2 is live in production, point at the dev server by setting this before Python starts:

export EELSDB_API_URL=https://api.dev.eelsdb.eu/v2/spectra

import exspy

# Spectra now load from the HSPY file served by API v2, with the DOI when there is one
s = exspy.data.eelsdb(title="MLC Nanotube")[0]
print(s.metadata.General.doi)  # 10.1021/acsnano.9b09284
print(s.original_metadata.json.accession)  # the full API v2 record, e.g. "EELSDB-0290"

# New: filter by specimen phase (gas-phase spectra are now included)
gas = exspy.data.eelsdb(phase="gas", max_n=1)
print(gas[0].original_metadata.json.phase)  # "gas"

# Deprecated: string resolution and the *_compare arguments
exspy.data.eelsdb(element="B", resolution="0.7 eV", max_n=1)  # VisibleDeprecationWarning

[ewels]

pre-commit.ci run

[ewels]

CI for the docs build is failing because the v2 API isn't live yet. It should hopefully pass when the new API is up.