Help & Instructions

1What ESRA Data Platform is

A FAIR (Findable, Accessible, Interoperable and Reusable) data platform for energy-storage experiments: upload the raw instrument files with structured metadata, and the platform gives them a permanent ID, makes them searchable, and lets anyone, or any machine, find, read and reuse them.

2What you can do

Reading needs no account. Downloading files and writing to the catalog do.

3Globus in one minute

Globus is a not-for-profit research service run by the University of Chicago. ESRA uses it for two things: to sign in, and to move large files.

Installing Globus Connect Personal

Globus Connect Personal is what carries out the transfer onto personal devices, authenticated by the same Globus login. Download it for Windows, macOS or Linux from globus.org/globus-connect-personal.

4The pages

Reading and searching are open to everyone. Running a workflow needs upload-level access, because it reads the raw files.

Nothing published here silently disappears. A withdrawn record leaves the catalog but keeps its page, marked as withdrawn, so a citation to it never dead-ends. If an administrator erases one for good, its ESRA ID still resolves — to a short notice giving the date and the reason — and that ID is retired rather than handed to another dataset.

5Uploading your data

Organising your folder

One folder per experiment type, a subfolder per technique where that applies, and raw instrument files only (no processed files).

EIS/     NaK50_cell01_PEIS_OCV.mpr
         NaK50_cell01_GEIS_5mVpp.mpr
         README.txt                       optional — what differs between the runs
TEM/
  EELS/  Cell01_EELS_O-K-edge.emd
  SAED/  Cell01_SAED_[110]-zone-axis.emd
XCT/     raw synchrotron projection files
DFT/     https://github.com/lab/NaK-DFT   a URL is enough — nothing to upload

• Name each file so it describes itself — [Cell-ID]_[technique or variable].[ext]
• A README.txt is optional and worth writing where the file names do not already say what changed between runs.
• If the code, model or trajectory already sits in a public repository, an external URL on the form satisfies the data-source requirement on its own.

Using a JSON-LD file instead of typing

1. Get a starting file. Download the LLM kit from the upload page, or export the JSON-LD of an existing dataset and edit that.
2. Let an assistant fill it in. The kit has three files: the reference JSON-LD, an authoring guide for the assistant, and a message to paste. Attach the first two, paste the message, then describe your experiment or attach your notes. It will ask you for anything it cannot find.
3. Or fill it in yourself. The template has one hasPart block per experiment type. Delete the ones you do not need and type the values. Leave propertyID and esra:fieldKey as they are.
4. Load it. On the upload page, pick the file and press Load Metadata. The experiment cards, declared materials and external data URLs fill in together. Check it, add the data source, submit.

The upload form is accessible only for authorized members; Check section 10 for more information.

6Legend: experiment types

The coloured chip on every record names the experiment type. Hovering a chip anywhere on the site shows the same expansion.

Sub-techniques and imaging modes

Not upload types of their own: they describe how a microscopy dataset was acquired, and appear as chips in Chat and as the imaging mode on TEM records.

7Legend: materials

Chemistry is declared once per study, against the cell or sample ID rather than against one file, so every dataset from that study inherits it. Declare NMC on the electrochemistry form and the microscopy of the same cell becomes findable by “NMC” too.

Family, grouped by class

The class is derived from the family: uploaders pick from available families or use the free-text box, the platform assigns the class.

Working ion

The ion that shuttles between the electrodes and carries the charge: Li in a lithium-ion cell, OH in an alkaline one. It is what a chemistry is named after, and is blank where nothing shuttles.

Role in the cell

What the material does in that study. One material can hold several roles, such as a salt that is also the redox-active species.

8Legend: status badges

Small badges next to an ESRA ID describe the state of the record.

9Code and AI agents

Every page here is backed by an endpoint, so a script, a notebook, or an AI agent can do the same things without a browser. There is no separate product and no API key to request: reading is open, and anything that acts on your behalf uses the same Globus login the pages do.

curl -s "https://data-dev.energystoragera.org/api/v1/browse?q=NMC&limit=5"

ESRA issues no API keys. The open rows above need nothing at all; the gated rows authenticate with the ordinary Globus session cookie, the same one the pages use, so a script reuses a logged-in browser session rather than sending a token.

The whole surface is described by an OpenAPI 3.1 spec at /api/v1/openapi.json, with a live console at /api/v1/docs — enough for an agent to call ESRA with no client written for it. The analysis workflows are Model Context Protocol tools reached through that one chat endpoint, rather than a second API to learn.

What comes back is self-describing. Dataset JSON-LD is schema.org carrying BattINFO/EMMO identifiers on the properties and QUDT identifiers on the units, so a number arrives with its meaning and its unit attached instead of a bare column name. It is an input format too (section 5). Export CSV on Browse Data gives the flat version of whatever is currently filtered.

10Getting help

• To be added to the ESRA Globus group (needed to upload data and run workflows) you will need a NERSC username first (docs.nersc.gov/accounts). Then email mgalib@anl.gov with your name, your PI, and NERSC username.
• Something broken, or a technique missing? Open an issue on GitHub.
• Citing ESRA in a paper? See How to Cite.