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.

Getting upload access

1. Get a NERSC account in project m4845 Apply at docs.nersc.gov/accounts, naming project m4845. NERSC checks your identity first, which can take up to a week, and only then does the request reach us. Still waiting? Email accounts@nersc.gov with your name, the username you asked for and project m4845. We approve it as soon as it arrives.
2. Email us Send mgalib@anl.gov your name, PI and NERSC username. We add you to the ESRA group (and chat, if you ask). If you have never used Globus, Globus emails you an invitation instead: open it, log in and accept.
3. Link your NERSC login to your Globus account If you also use Globus with Google, ORCID or your university, add NERSC to that account: open the Identities page in Globus, choose Link another identity, pick NERSC and sign in. Your group membership then works whichever of these you log in with. If you only ever log in to Globus with NERSC, skip this step.
4. Sign in with NERSC Login → Sign in with NERSC. Use the same email in Globus Connect Personal.

3NERSC status

4Globus 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.

5The pages

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

How Chat answers a question

Each question is tried against five steps in order, and the first one that fits answers it. Most questions never reach a language model, so the answer is exact and repeatable. The grey label above each answer names the step that produced it.

1. 1Direct lookupcounts, who uploaded, one person’s datasets, read straight from the database how many datasets are there?
2. 2Ontology & graphmaterials and measured properties, matched through BattINFO / EMMO terms show all NASICON data
3. 3Search by meaningfinds datasets whose description is close, even with no keyword in common anything about battery degradation
4. 4Analysis toolsthe sidebar workflows, run on one dataset, step by step browse all TEM data
5. 5Text-to-SQLanything else: a small local model writes a read-only query. Can be slow, and can be wrong, so check the answer how many projects are there?

The workflows are for checking a method on one dataset at a time. They run on a shared web server; large or batch analysis does not belong here.

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.

A record can grow while the study runs. Every change is recorded (who, when, the old and the new value). A file taken out, or overwritten by Add files or Replace files, is kept aside and can be restored; only an administrator deletes it for good. A version freezes the description and the file list at one moment — automatically when a dataset is made public, and by hand with Save version — so a paper can say which one it used. The ESRA ID never changes.

6Uploading your data

1. Get a metadata file Download the LLM kit from the upload page and let an AI assistant write it from your notes, or type it in by hand.
2. Load it and fill the gaps Load Metadata fills the form; only who you are and where the data is are compulsory.
3. Point at your data Pick the folder on Globus, attach files, or give an external URL.
4. Submit You get a permanent ESRA ID at once; the files copy in the background.

▶ See it done: uploading data in the walkthrough (8:56).

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 — [Sample-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.

Private now, public later

Choose Private when you upload. The metadata is public and citable at once; the raw files can be downloaded only by ESRA group members. When the paper is out, press Make Public on the dataset’s page. Upload when you are ready to share, not as personal storage. File names, sizes and saved versions are visible to everyone too, so name your files with that in mind.

After you upload

Open My datasets from the menu under your initials. It lists everything you uploaded, what needs fixing, and how often others downloaded it. Tick several rows to make them public, add a co-editor or save a version in one go.

To change a dataset after uploading it, see Editing a dataset.

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 (START_HERE.txt). 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 only for authorized members: see Getting upload access.

7Editing a dataset

Press Edit on the dataset’s page. The editor lists the parts of the dataset on the left: description, technique fields, materials, comments, files, versions, history and JSON-LD.

• Saving. Press Save changes, or Cmd S (Ctrl S on Windows). Unsaved edits stay in your browser until you save or discard them. If someone else changed the same field while you were editing, both values are shown and nothing is saved until you choose.
• History. Every save is listed with who made it and when. Undo this save puts the old values back, except where a field was changed again later.
• Versions. Save version records the description and the file list as they are now. Cite a version in your paper so readers know exactly what you used. A version is also saved when a dataset goes public. Open one to see what changed since the last, or compare any version with the dataset now.
• Co-editors. Under Co-editors, type a colleague’s name and pick them from the list. They can edit the description, add, replace or remove files, and save versions. They can’t make the files public or private, withdraw the dataset, or add other co-editors. The list shows ESRA group members who have signed in here at least once.
• Removing a file. Remove takes a file out straight away, but ESRA keeps a copy, so you can put it back. Only an administrator can delete it for good. Add and Replace also keep a copy of anything they overwrite.
• Comments. Any ESRA group member can comment on a field or suggest a new value, with Comment next to the field or Suggest a change at the top. The uploader, a co-editor or an administrator accepts a suggestion into the form and saves it, or rejects it.

Editing through JSON-LD

1. Open JSON-LD in the editor. Edit the text there, or download it, change it (by hand or with an AI assistant) and press Upload file. The file must be this dataset’s own.
2. Press Review changes. Saved values are red, yours are green. Press Undo on any change you don’t want.
3. Press Apply to form, then Save changes.

You can change values and add parameters of your own. Give a new parameter a name, a value and a unit, and mark it "esra:authorAdded": true. Names of existing fields can’t be reused, and nothing is deleted through a file.

8Legend: 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.

9Legend: materials

Chemistry is declared once per study, against the 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 sample 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.

10Legend: status badges

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

11Code 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: only reading is open. To download globus login is needed.

Search the catalog — q matches ESRA ID, researcher, PI, project, cell and technique:

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

Then take the ESRA ID of the first result and pull that dataset’s JSON-LD.

ID=$(curl -s "https://data.energystoragera.org/api/v1/browse?q=EIS&limit=1" | python3 -c "import json,sys; print(json.load(sys.stdin)['files'][0]['esra_id'])")
curl -sOJ "https://data.energystoragera.org/api/v1/datasets/$ID/jsonld"

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.

▶ See it done in the walkthrough: downloading via the API (1:25) · connecting an AI assistant over MCP (5:11).

Any client that speaks the protocol can connect. Each wants the same address:

Downloading through an AI assistant

A second address lets the assistant download a public dataset to your computer. It gives you a link: open it, sign in to Globus and press Allow; when the page says Connected, go back to the chat and say "done". Nothing is pasted, so it works the same in Claude, ChatGPT and other assistants. Globus Connect Personal must be running.

claude mcp add --transport http esra-transfer …/mcp-transfer

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 (see Uploading your data). Export CSV on Browse Data gives the flat version of whatever is currently filtered.

12Troubleshooting

Most problems are one of these. Each says what you see, then what to do.

13Getting help

• To upload data, run workflows or use chat see Getting upload access, or email mgalib@anl.gov.
• Something broken, or a technique missing? Open an issue on GitHub.
• Citing ESRA in a paper? See How to Cite.