Some amendments

Author: FrancescAlted

examples/slicing_and_beyond.ipynb

@@ -6,7 +6,7 @@
    "source": [
     "# Slicing chunks and beyond\n",
     "\n",
-    "The newest and coolest way to store data in python-blosc2 is through a SChunk (super-chunk) object. Here the data is split into chunks of the same size. So in the past, the only way of working with it was chunk by chunk (see  tutorials-basics.ipynb). But now, python-blosc2 can retrieve, update or append data all at once (i.e. avoiding doing it chunk by chunk). To see how this works, let's first create our SChunk."
+    "The newest and coolest way to store data in python-blosc2 is through a `SChunk` (super-chunk) object. Here the data is split into chunks of the same size. In the past, the only way of working with it was chunk by chunk (see  tutorials-basics.ipynb), but now, python-blosc2 can retrieve, update or append data at item level (i.e. avoiding doing it chunk by chunk). To see how this works, let's first create our SChunk."
    ]
   },
   {
@@ -56,11 +56,7 @@
   {
    "cell_type": "code",
    "execution_count": 3,
-   "metadata": {
-    "pycharm": {
-     "name": "#%%\n"
-    }
-   },
+   "metadata": {},
    "outputs": [
     {
      "name": "stdout",
@@ -85,11 +81,7 @@
   {
    "cell_type": "code",
    "execution_count": 4,
-   "metadata": {
-    "pycharm": {
-     "name": "#%%\n"
-    }
-   },
+   "metadata": {},
    "outputs": [
     {
      "name": "stdout",
@@ -120,11 +112,7 @@
   {
    "cell_type": "code",
    "execution_count": 5,
-   "metadata": {
-    "pycharm": {
-     "name": "#%%\n"
-    }
-   },
+   "metadata": {},
    "outputs": [],
    "source": [
     "start = 34\n",
@@ -143,11 +131,7 @@
   {
    "cell_type": "code",
    "execution_count": 6,
-   "metadata": {
-    "pycharm": {
-     "name": "#%%\n"
-    }
-   },
+   "metadata": {},
    "outputs": [],
    "source": [
     "schunk_nelems = 1000 * 200 * nchunks\n",
@@ -162,9 +146,9 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Getting a SChunk from/as a contiguous buffer\n",
+    "## Building a SChunk from/as a contiguous buffer\n",
     "\n",
-    "Furthermore, you can pass from a SChunk to a contiguous buffer and vice versa. Let's get that buffer:"
+    "Furthermore, you can convert a SChunk to a contiguous, serialized buffer and vice-versa. Let's get that buffer (aka `cframe`) first:"
    ]
   },
   {
@@ -196,95 +180,71 @@
   {
    "cell_type": "code",
    "execution_count": 8,
-   "metadata": {
-    "pycharm": {
-     "name": "#%%\n"
-    }
-   },
+   "metadata": {},
    "outputs": [],
    "source": [
     "schunk2 = blosc2.schunk_from_cframe(cframe=buf, copy=True)"
    ]
   },
   {
    "cell_type": "markdown",
-   "metadata": {
-    "pycharm": {
-     "name": "#%% md\n"
-    }
-   },
+   "metadata": {},
    "source": [
     "In this case we set the `copy` param to `True`. If you do not want to copy the buffer,\n",
-    "be mindful that you will have to keep its reference until you do not\n",
+    "be mindful that you will have to keep a reference to it until you do not\n",
     "want the SChunk anymore.\n",
     "\n",
-    "## Compressing NumPy arrays\n",
+    "## Serializing NumPy arrays\n",
     "\n",
-    "If the object you want to get as a compressed buffer is a NumPy array, you can use the newer and faster functions to store it in-memory or on-disk.\n",
+    "If what you want is to create a serialized, compressed version of a NumPy array, you can use the newer (and faster) functions to store it either in-memory or on-disk.  The specification of such a contiguous compressed representation, aka **cframe** can be seen at: https://github.com/Blosc/c-blosc2/blob/main/README_CFRAME_FORMAT.rst.\n",
     "\n",
     "### In-memory\n",
     "\n",
-    "To store it in-memory you can use `pack_array2`. In comparison with its former version, it is faster (see `pack_compress.py` bench)  and does not have the 2 GB size limitation."
+    "For obtaining an in-memory representation, you can use `pack_array2`. In comparison with its former version (`pack_array`), it is way faster and does not have the 2 GB size limitation:"
    ]
   },
   {
    "cell_type": "code",
    "execution_count": 9,
-   "metadata": {
-    "pycharm": {
-     "name": "#%%\n"
-    }
-   },
+   "metadata": {},
    "outputs": [],
    "source": [
-    "np_array = np.arange(2**30, dtype=np.int32)\n",
+    "np_array = np.arange(2**30 + 1, dtype=np.int32)  # 2 GB (+4) array\n",
     "\n",
     "packed_arr2 = blosc2.pack_array2(np_array)\n",
     "unpacked_arr2 = blosc2.unpack_array2(packed_arr2)"
    ]
   },
   {
    "cell_type": "markdown",
-   "metadata": {
-    "pycharm": {
-     "name": "#%% md\n"
-    }
-   },
+   "metadata": {},
    "source": [
     "### On-disk\n",
     "\n",
-    "To perform the same but store the buffer on-disk you would use `save_array` and `load_array` like so:"
+    "To store the serialized buffer on-disk you want to use `save_array` and `load_array`:"
    ]
   },
   {
    "cell_type": "code",
    "execution_count": 10,
-   "metadata": {
-    "pycharm": {
-     "name": "#%%\n"
-    }
-   },
+   "metadata": {},
    "outputs": [],
    "source": [
     "blosc2.save_array(np_array, urlpath=\"ondisk_array.b2frame\", mode=\"w\")\n",
     "np_array2 = blosc2.load_array(\"ondisk_array.b2frame\")\n",
     "np.array_equal(np_array, np_array2)\n",
     "\n",
-    "# Remove it\n",
+    "# Remove it from disk\n",
     "blosc2.remove_urlpath(\"ondisk_array.b2frame\")"
    ]
   },
   {
    "cell_type": "markdown",
-   "metadata": {
-    "pycharm": {
-     "name": "#%% md\n"
-    }
-   },
+   "metadata": {},
    "source": [
     "# Conclusions\n",
     "\n",
-    "Now python-blosc2 has an easy way of creating, getting, setting, deleting and expanding data in a SChunk. Moreover, you can get a contiguous compressed representation (aka [cframe](https://github.com/Blosc/c-blosc2/blob/main/README_CFRAME_FORMAT.rst)) of it and create it again latter. And you can do the same with NumPy arrays faster than with the former functions.\n"
+    "Now python-blosc2 offers an easy, yet fast way of creating, getting, setting and expanding data via the `SChunk` class.  Moreover, you can get a contiguous compressed representation (aka [cframe](https://github.com/Blosc/c-blosc2/blob/main/README_CFRAME_FORMAT.rst)) of it and re-create it again later with no sweat.\n"
    ]
   }
  ],
@@ -309,4 +269,4 @@
  },
  "nbformat": 4,
  "nbformat_minor": 1
-}
+}