Update README.md and examples

examples/lindi_demo.ipynb

@@ -0,0 +1,208 @@
+{
+ "cells": [
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "52802664-85e7-433a-a8c3-f2645847423b",
+   "metadata": {
+    "scrolled": true
+   },
+   "outputs": [],
+   "source": [
+    "%pip install -q lindi\n",
+    "%pip install -q pynwb"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "94dadefb-c04a-4aea-b906-b4cc3a263570",
+   "metadata": {},
+   "source": [
+    "### Lazy-load a remote NWB/HDF5 file for efficient access to metadata and data"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "65b50dec-5c6e-40cf-aa93-c18d220b74bb",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import pynwb\n",
+    "import lindi\n",
+    "\n",
+    "# URL of the remote NWB file\n",
+    "h5_url = \"https://api.dandiarchive.org/api/assets/11f512ba-5bcf-4230-a8cb-dc8d36db38cb/download/\"\n",
+    "\n",
+    "# Set up a local cache\n",
+    "local_cache = lindi.LocalCache(cache_dir='lindi_cache')\n",
+    "\n",
+    "# Create the h5py-like client\n",
+    "client = lindi.LindiH5pyFile.from_hdf5_file(h5_url, local_cache=local_cache)\n",
+    "\n",
+    "# Open using pynwb\n",
+    "with pynwb.NWBHDF5IO(file=client, mode=\"r\") as io:\n",
+    "    nwbfile = io.read()\n",
+    "    print(nwbfile)\n",
+    "\n",
+    "# The downloaded data will be cached locally, so subsequent reads will be faster"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "79a2ce81-c3da-4c9c-a013-fd5fa34762f7",
+   "metadata": {},
+   "source": [
+    "### Represent a remote NWB/HDF5 file as a .nwb.lindi.json file"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "d11db473-ab25-4d1e-ac15-7a16654c4bcf",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import json\n",
+    "import lindi\n",
+    "\n",
+    "# URL of the remote NWB file\n",
+    "h5_url = \"https://api.dandiarchive.org/api/assets/11f512ba-5bcf-4230-a8cb-dc8d36db38cb/download/\"\n",
+    "\n",
+    "# Create the h5py-like client\n",
+    "client = lindi.LindiH5pyFile.from_hdf5_file(h5_url)\n",
+    "\n",
+    "client.write_lindi_file('example.lindi.json')\n",
+    "\n",
+    "# See the next example for how to read this file"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "2550661e-ee88-45d8-b6b2-8c6f8fe4dfaa",
+   "metadata": {},
+   "source": [
+    "### Read a local or remote .nwb.lindi.json file using pynwb or other tools"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "9973c935-db2e-468f-ba9c-7f5e7153b319",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import pynwb\n",
+    "import lindi\n",
+    "\n",
+    "# URL of the remote .nwb.lindi.json file\n",
+    "url = 'https://lindi.neurosift.org/dandi/dandisets/000939/assets/56d875d6-a705-48d3-944c-53394a389c85/nwb.lindi.json'\n",
+    "\n",
+    "# Load the h5py-like client\n",
+    "client = lindi.LindiH5pyFile.from_lindi_file(url)\n",
+    "\n",
+    "# Open using pynwb\n",
+    "with pynwb.NWBHDF5IO(file=client, mode=\"r\") as io:\n",
+    "    nwbfile = io.read()\n",
+    "    print(nwbfile)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "ea03ad43-7d0b-4cfd-9992-bdb1ada6b13c",
+   "metadata": {},
+   "source": [
+    "### Edit a .nwb.lindi.json file using pynwb or other tools"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "1c66931b-3ea9-4222-afc8-a93b25457e37",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import json\n",
+    "import lindi\n",
+    "\n",
+    "# URL of the remote .nwb.lindi.json file\n",
+    "url = 'https://lindi.neurosift.org/dandi/dandisets/000939/assets/56d875d6-a705-48d3-944c-53394a389c85/nwb.lindi.json'\n",
+    "\n",
+    "# Load the h5py-like client for the reference file system\n",
+    "# in read-write mode\n",
+    "client = lindi.LindiH5pyFile.from_lindi_file(url, mode=\"r+\")\n",
+    "\n",
+    "# Edit an attribute\n",
+    "client.attrs['new_attribute'] = 'new_value'\n",
+    "\n",
+    "# Save the changes to a new .nwb.lindi.json file\n",
+    "client.write_lindi_file('new.nwb.lindi.json')"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "fe19e0f6-1c62-42e9-9af0-4a57c8a61364",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Now load that file\n",
+    "client2 = lindi.LindiH5pyFile.from_lindi_file('new.nwb.lindi.json')\n",
+    "print(client2.attrs['new_attribute'])"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "4a2addfc-58ed-4e79-9c64-b7ec95cb12f5",
+   "metadata": {},
+   "source": [
+    "### Add datasets to a .nwb.lindi.json file using a local staging area"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "6e87640d-1927-43c1-89c1-c1274a11f185",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import lindi\n",
+    "\n",
+    "# URL of the remote .nwb.lindi.json file\n",
+    "url = 'https://lindi.neurosift.org/dandi/dandisets/000939/assets/56d875d6-a705-48d3-944c-53394a389c85/nwb.lindi.json'\n",
+    "\n",
+    "# Load the h5py-like client for the reference file system\n",
+    "# in read-write mode with a staging area\n",
+    "with lindi.StagingArea.create(base_dir='lindi_staging') as staging_area:\n",
+    "    client = lindi.LindiH5pyFile.from_lindi_file(\n",
+    "        url,\n",
+    "        mode=\"r+\",\n",
+    "        staging_area=staging_area\n",
+    "    )\n",
+    "    # add datasets to client using pynwb or other tools\n",
+    "    # upload the changes to the remote .nwb.lindi.json file"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.9.0"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}