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. The ESRA Data Platform 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 public datasets 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 its link still opens a page saying it was 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.

What a Sample ID means

A Sample ID names one physical thing you measured: one cell, pellet, electrode or powder batch (for a computation, one simulated system). Every dataset measured on that same thing carries the same ID, which is how its EIS, cycling and microscopy are linked. Two cells built the same way are two samples, so give each its own ID, with a shared prefix to show they belong together (NMC811-A-01, NMC811-A-02). Same conditions do not make the same sample; the conditions belong in the experiment fields.

Private now, public later

New uploads start as Private; choose Public on the upload form only for data you can share now. When the paper is out, press Make Public on the dataset’s page; once public, only an admin can make it private again (an admin can allow the authors to). Upload when you are ready to share, not as personal storage. What stays private and what does not: Data access and visibility.

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.

Every field of every experiment type, with its unit, whether it is required, its allowed values and its ontology term, is listed in the metadata dictionary (a spreadsheet, one sheet per experiment type).

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 change whether it is 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 The ESRA Data Platform 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.
• Notifications. The bell at the top of every page tells you what happens to your datasets; see Notifications.

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.

8Notifications

The bell at the top right of every page (for ESRA group members) tells you about your own datasets (the ones you uploaded or co-edit) and about replies to your comments, nothing else. A red number means something is new. Nobody else sees your notices, and nobody, administrators included, gets notices about other people’s datasets.

• Someone comments on one of your datasets, or replies to a comment you wrote.
• Someone suggests a new value for a field.
• A co-editor saves a change.
• Your upload finishes, or fails (with the reason).

You are never told about your own actions. A notice is kept for 90 days after you read it. The ESRA Data Platform never sends email.

The same notices on Slack (ESRA Bot)

There is nothing to install. ESRA Bot is already part of the ESRA Slack workspace; its messages simply appear for you when step 1 below is true.

1. Be a member of the ESRA Slack workspace, with the same email you sign in here with. Slack matches you by that email; if your Slack account uses a different one, you get no Slack messages, and the bell still has everything.
2. When it matches, the bell shows Also send these to me on Slack, ticked.
3. In Slack, open Apps → ESRA Bot in the left sidebar (or search for “ESRA Bot”). It is a private chat between you and the bot. Each message is the bell’s sentence with a link to the dataset; it never contains the text of a comment.
4. To stop, untick Also send these to me on Slack in the bell. Tick it again to start.

At most ten Slack messages an hour reach one person; anything beyond that is only in the bell. If Slack is down, nothing is lost: the bell is the record.

9Data access and visibility

Every dataset is public or private. Public data is open to everyone. Private is for work not yet published: its description and files are visible to ESRA group members only. Some parts of every dataset, like its comments and change history, are for the group whether it is public or not.

Who can change it

A dataset whose upload failed is seen only by its uploader and admins, until it is retried. A withdrawn dataset is no longer listed. Group members can still open it; anyone else who follows its link sees a short page saying it was withdrawn.

“ESRA group members” means people in the ESRA Globus group, signed in. Admins and a dataset’s uploader and co-editors are group members too.

10Synthesis cards

A synthesis card records one batch you made: what went in, how, and each sample it produced. The card gets an ID (ESRA-SYN-0001) and so does each sample (ESRA-SYN-0001-S05). Your lab codes (E_05) and the names an instrument wrote (SC3_05) stay with the sample, so any of them finds it. Datasets link to samples and show their chemistry. Cards are listed under Browse Data, By synthesis.

• Create. On Upload Data, choose Synthesis and give a spreadsheet, Markdown or JSON-LD file with one row per sample (starters: spreadsheet, Markdown, JSON-LD), or start without a file. Preview shows what will be made; fix any row, then Create card. Nothing is saved before that.
• Link datasets. On the upload form, with a card’s Link datasets, or in the Sample section of a dataset’s editor. Data uploaded earlier links when the card is created, if the names match. Undo all removes the links one run made.
• Change. The owner edits a card with Edit this card, and its History keeps every change. The owner or an administrator can withdraw it.
• Chains. A sample can be made from another card’s sample; the card shows Made from and Used by.
• Search. In Chat, ask “what is ESRA-SYN-0001” or “which datasets measured E_05”. AI agents use the read-only MCP tools list_synthesis_cards, get_synthesis_card and search_samples (see Code and AI agents).

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

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

13Legend: status badges

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

14Code 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-dev.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-dev.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-dev.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 the ESRA Data Platform 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).

Which MCP server?

An MCP server is a set of tools an AI assistant can call. The ESRA Data Platform has more than one, each for a different job, so add only the ones you need.

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

In ChatGPT: add a second server the same way, URL …/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.

15Troubleshooting

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

16Getting 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 the ESRA Data Platform in a paper? See How to Cite.