diff --git a/examples/example_superDB.png b/examples/example_superDB.png
new file mode 100644
index 00000000..4fed6809
Binary files /dev/null and b/examples/example_superDB.png differ
diff --git a/examples/examples.ipynb b/examples/examples.ipynb
index 1f1cef7a..65c05a67 100644
--- a/examples/examples.ipynb
+++ b/examples/examples.ipynb
@@ -12,27 +12,27 @@
     "\n",
     "This library extract useful information from IAM model output files (such as those of REMIND or IMAGE) and aligns inventories in the ecoinvent database accordingly.\n",
     "\n",
-    "With version 1.5.0, the following transformation are available:\n",
-    "\n",
-    "* `update(\"biomass\")`: creates regional biomass markets, adjusting the share of residual vs. purpose-grown boimass for use in heat and power generation\n",
-    "* `update(\"battery\")`: creates a global mix for stationary and mobile battery technologies.\n",
-    "* `update(\"electricity\")`: creates regional electricity markets and adjust efficiency of power plants, including that of photovoltaic panels\n",
-    "* `update(\"cement\")`: creates regional markets for clinker production and adjust clinker production efficiency\n",
-    "* `update(\"steel\")`: creates regional markets for steel and adjust steel production efficiency and the supply of secondary steel\n",
-    "* `update(\"dac\")`: creates region- and scenario-specific inventories for Direct Air Capture (DAC) and Carbon Storage (DACCS) systems.\n",
+    "With version `2.2.0`, the following transformations are available:\n",
+    "\n",
+    "* `update(\"biomass\")`: creates regional biomass markets, adjusting the share of residual vs. purpose-grown biomass for use in heat and power generation\n",
+    "* `update(\"battery\")`: creates a global mix of stationary and mobile battery technologies.\n",
+    "* `update(\"electricity\")`: creates regional electricity markets and adjusts the efficiency of power plants, including that of photovoltaic panels\n",
+    "* `update(\"cement\")`: creates regional markets for clinker production and adjusts clinker production efficiency\n",
+    "* `update(\"steel\")`: creates regional markets for steel and adjusts steel production efficiency and the supply of secondary steel\n",
+    "* `update(\"dac\")` creates region- and scenario-specific inventories for Direct Air Capture (DAC) and Carbon Storage (DACCS) systems.\n",
     "* `update(\"fuels\")`: creates regional markets for liquid and gaseous fuels\n",
-    "* `update(\"heat\")`: regionalizes some heat and steam generation datasets (working on diesel, biomass and natural gas)\n",
-    "* `update(\"emissions\")`: adjusts emission of pollutants (PM, NOx, VOCs) for various activities, based on GAINS model projections.\n",
+    "* `update(\"heat\")`: regionalizes some heat and steam generation datasets (working on diesel, biomass, and natural gas)\n",
+    "* `update(\"emissions\")`: adjusts emission of pollutants (PM, NOx, VOCs) for various activities based on GAINS model projections.\n",
     "* `update(\"two_wheelers\")`: imports two-wheelers (bicycles, motorbikes, etc.)\n",
-    "* `update(\"cars\")`: produces fleet average cars and relinks to activities consuming pasenger car transport\n",
+    "* `update(\"cars\")`: produces fleet average cars and relinks to activities consuming passenger car transport\n",
     "* `update(\"trucks\")`: produces fleet average trucks and relinks to activities consuming lorry transport\n",
     "* `update(\"buses\")`: imports buses (urban and coach buses, single-deckers and double-deckers)\n",
     "* `update(\"trains\")`: imports buses (urban and coach buses, single-deckers and double-deckers)\n",
     "* `update(\"external\")`: runs any external scenarios provided.\n",
     "\n",
-    "Alternatively, `update()` performs all the above-mentioned transformations.\n",
+    "Alternatively, `update()` performs all the transformations mentioned above.\n",
     "\n",
-    "There is also the possibility to integrate user-defined scenarios (i.e., `update(\"external\")`), for which we have a separate notebook.\n",
+    "Integration of user-defined scenarios (e.g., `update(\"external\")`) is also possible, and we have a separate notebook for this.\n",
     "\n",
     "Additional documentation on the methodology is available [here](https://premise.readthedocs.io/en/latest/introduction.html).\n",
     "\n",
@@ -57,18 +57,18 @@
   },
   {
    "cell_type": "code",
+   "execution_count": 3,
    "metadata": {
     "ExecuteTime": {
      "end_time": "2024-08-13T09:59:07.856284Z",
      "start_time": "2024-08-13T09:59:07.854148Z"
     }
    },
+   "outputs": [],
    "source": [
     "from premise import *\n",
     "import bw2data"
-   ],
-   "outputs": [],
-   "execution_count": 3
+   ]
   },
   {
    "cell_type": "markdown",
@@ -141,10 +141,10 @@
    ]
   },
   {
-   "metadata": {},
    "cell_type": "code",
-   "outputs": [],
    "execution_count": null,
+   "metadata": {},
+   "outputs": [],
    "source": [
     "ndb = NewDatabase(\n",
     "    scenarios=[\n",
@@ -162,8 +162,8 @@
    ]
   },
   {
-   "metadata": {},
    "cell_type": "markdown",
+   "metadata": {},
    "source": [
     "Here is a list of all arguments that can be passed to `NewDatabase()`:\n",
     "    \n",
@@ -222,7 +222,9 @@
   {
    "cell_type": "markdown",
    "metadata": {},
-   "source": "However, if you wish first to proceed with the IAM integration, you need to use the `update()` method, like so for the electricity sector:"
+   "source": [
+    "However, if you wish first to proceed with the IAM integration, you need to use the `update()` method, like so for the electricity sector:"
+   ]
   },
   {
    "cell_type": "code",
@@ -324,9 +326,9 @@
    "source": [
     "### Consequential\n",
     "\n",
-    "`premise` can read in the consequential version of ecoinvent (v.3.8 and 3.9 only).\n",
+    "`premise` can read in the consequential version of ecoinvent.\n",
     "Based on the publication of Maes et al. 2023 (https://doi.org/10.1016/j.rser.2023.113830), `premise` builds marginal market mixes for electricity and fuels.\n",
-    "The identification of marginal suppliers can be influenced by passing a series of arguments to `NewDatabase()`.\n",
+    "Passing a series of arguments to `NewDatabase()` can influence the identification of marginal suppliers.\n",
     "Additionally, `premise` removes secondary steel technologies from steel markets."
    ]
   },
@@ -364,7 +366,7 @@
    "source": [
     "### Database creation from non-default scenarios\n",
     "\n",
-    "If you have some specific IAM scenarios (one that is not included in `premise`) you would like to build a database from, you can specify the directory to those.\n",
+    "If you have some specific IAM scenarios (one that is not included in `premise`) from which you would like to build a database, you can specify the directory for those.\n",
     "\n",
     "**Important remark**: your scenario file must begin with \"remind_\" or \"image_\". When using a non-default scenario that you provide yourself, you do not have to provide a decryption key."
    ]
@@ -432,9 +434,9 @@
     "The source database does not have to be from a brightway2 project.\n",
     "It can be directly extracted from the bunch of ecospold2 files one gets when downloaded from the [ecoinvent website](https://ecoinvent.org).\n",
     "\n",
-    "For this, one needs to specify the argument `source_db = \"ecospold\"` as well as `source_file_path`, which is the directory leading to the ecospold files.\n",
+    "For this, one needs to specify the argument `source_db = \"ecospold\"` and `source_file_path`, which is the directory leading to the ecospold files.\n",
     "\n",
-    "For example, here we combine the use of a specific (non-default) IAM scenario file with the use of ecospold2 files as data source (ecoinvent 3.5 in this case)."
+    "For example, here we combine the use of a specific (non-default) IAM scenario file with the use of ecospold2 files as data source (ecoinvent 3.6 in this case)."
    ]
   },
   {
@@ -450,7 +452,7 @@
     "        ],        \n",
     "        source_type=\"ecospold\", # <--- this is NEW\n",
     "        source_file_path=r\"C:\\filepath\\to\\your\\ecosposld\\folder\\datasets\", # <-- this is NEW\n",
-    "        source_version=\"3.5\",\n",
+    "        source_version=\"3.6\",\n",
     "    )"
    ]
   },
@@ -462,27 +464,31 @@
     "\n",
     "These functions modify the extracted database:\n",
     "\n",
-    "* **update(\"electricity\")**: alignment of regional electricity production mixes as well as efficiencies for a number of electricity production technologies, including Carbon Capture and Storage technologies and photovoltaic panels. Also updated the natural gas extraction datasets.\n",
+    "* **update(\"biomass\")**: create scenario- and region-specific markets for biomass used for power generation. Distinguish between purpose-grown and residual biomass.\n",
+    "\n",
+    "* **update(\"electricity\")**: alignment of regional electricity production mixes as well as efficiencies for several electricity production technologies, including Carbon Capture and Storage technologies and photovoltaic panels.\n",
     "\n",
     "* **update(\"cement\")**: adjustment of technologies for cement production (dry, semi-dry, wet, with pre-heater or not), fuel efficiency of kilns, fuel mix of kilns (including biomass and waste fuels).\n",
     "\n",
     "* **update(\"steel\")**: adjustment of process efficiency, fuel mix and share of secondary steel in steel markets.\n",
     "\n",
-    "* **update(\"dac\")**: creates region- and scenario-specific inventories for DAC and DACCS systems. Applies a learning rate on energy and infrastructure needs if the IAM provides the variable.\n",
+    "* **update(\"dac\")**: This function creates region—and scenario-specific inventories for DAC and DACCS systems and adjusts efficiency.\n",
     "\n",
-    "* **update(\"fuels\")**: creates regional markets for liquid and gaseous fuels and relinks fuel-conusming activities to them.\n",
+    "* **update(\"fuels\")**: This method creates regional markets for liquid and gaseous fuels and relinks consuming activities to them.\n",
     "\n",
-    "* **update(\"heat\")**: creates regionalized versions of heat and steam production datasets and relink them to heat-consuming activities.\n",
+    "* **update(\"heat\")**: This function creates regionalized versions of heat and steam production datasets and relinks them to heat-consuming activities.\n",
     "\n",
-    "* **update(\"emissions\")**: adjusts emission of local air pollutants according to GAINS projections.\n",
+    "* **update(\"emissions\")**: adjust emission of local air pollutants according to GAINS projections.\n",
     "\n",
     "* **update(\"cars\")**: creates updated inventories for fleet average passenger cars and links back to activities that consume transport.\n",
     "\n",
     "* **update(\"trucks\")**: creates updated inventories for fleet average lorry trucks and links back to activities that consume transport.\n",
     "\n",
-    "* **update(\"two_wheelers\")**: create inventories for two-wheelers.\n",
+    "* **update(\"two_wheelers\")**: creates updated inventories for fleet average two-wheelers and links back to activities that consume transport.\n",
+    "\n",
+    "* **update(\"buses\")**: creates updated inventories for fleet average buses and links back to activities that consume transport.\n",
     "\n",
-    "* **update(\"buses\")**: create inventories for buses.\n",
+    "* **update(\"buses\")**: creates updated inventories for fleet average trains and links back to activities that consume transport.\n",
     "\n",
     "A look at the documentation is advised.\n",
     "\n",
@@ -535,6 +541,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
+    "# write back to brightway project\n",
     "ndb.write_db_to_brightway()"
    ]
   },
@@ -558,7 +565,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Export"
+    "# Export options"
    ]
   },
   {
@@ -584,6 +591,87 @@
     "ndb.write_db_to_brightway()"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### As a SimaPro CSV file"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "ndb.write_db_to_simapro(filepath=r\"C:/Users/sacchi_r/Downloads/exported_simapro_file\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### As a CSV file for OpenLCA"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "ndb.write_db_to_olca(filepath=r\"C:/Users/sacchi_r/Downloads/exported_olca_file\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### As a Superstructure database\n",
+    "A superstructure database is a database that can accomodate several scenarios, as described [here](https://github.com/dgdekoning/brightway-superstructure), to be then used in [Activity-Browser](https://github.com/LCA-ActivityBrowser/activity-browser).\n",
+    "This function will export the superstructure database as well as produce a \"scenario difference file\". Hence, even though you create multiple scenarios, **you only need to write to disk one database**."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "ndb.write_superstructure_db_to_brightway(name=\"my_db\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Doing so will automatically produce the LCA of your system for each scenario contained in the \"scenario difference\" file."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "![Example superstructure](example_superDB.png)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### As a data package\n",
+    "Export a data package, which can be shared. Data packages can be read by [unfold](https://github.com/polca/unfold), and databases can be reproduced on other computers provided a local copy of ecoinvent is present. This way of sharing premise databases across users respects ecoinvent's EULA."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "ndb.write_datapackage()"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -622,7 +710,28 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Here is an example on how to claculate GWP scores using the set of sparse matrices\n",
+    "The exported matrices have the following columns:\n",
+    "\n",
+    "* \"index of activity\"\n",
+    "* \"index of product\"\n",
+    "* \"value\"\n",
+    "* \"uncertainty type\"\n",
+    "* \"loc\"\n",
+    "* \"scale\"\n",
+    "* \"shape\"\n",
+    "* \"minimum\"\n",
+    "* \"maximum\"\n",
+    "* \"negative\"\n",
+    "* \"flip\"\n",
+    "\n",
+    "Where each row is in an exchange (a technosphere exchange if looking at \"A_matrix,\" else, a biosphere exchange). These matrices comply with the data structure expected by [bw_processing](https://pypi.org/project/bw-processing/) and can therefore be read directly by [bw2calc](\"https://pypi.org/project/bw2calc/\") `2.0.x`."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Otherwise, you can also do things manually. Here is an example of how to calculate GWP scores using the set of sparse matrices\n",
     "export by `premise`."
    ]
   },
@@ -706,7 +815,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Print the results together with the name of the activity"
+    "Print the results together with the name of the activity."
    ]
   },
   {
@@ -722,23 +831,9 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### As a SimaPro CSV file"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "ndb.write_db_to_simapro(filepath=r\"C:/Users/sacchi_r/Downloads/exported_simapro_file\")"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "### As a SimaPro CSV file for OpenLCA"
+    "# Incremental Database\n",
+    "\n",
+    "You can use the class `IncrementalDatabase` to create a `brightway` database that lets you analyze the respective contribution of sectors in the environmental score of your LCA."
    ]
   },
   {
@@ -747,16 +842,23 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "ndb.write_db_to_olca(filepath=r\"C:/Users/sacchi_r/Downloads/exported_simapro_file\")"
+    "ndb = IncrementalDatabase(\n",
+    "    scenarios=[\n",
+    "        {\"model\":\"image\", \"pathway\":\"SSP2-RCP26\", \"year\":2040},\n",
+    "        {\"model\":\"image\", \"pathway\":\"SSP2-RCP26\", \"year\":2050},\n",
+    "    ],\n",
+    "    source_db=\"ecoinvent-3.10-cutoff\", # <-- name of the database in the BW2 project. Must be a string.\n",
+    "    source_version=\"3.10\", # <-- version of ecoinvent. Can be \"3.5\", \"3.6\", \"3.7\" or \"3.8\". Must be a string.\n",
+    "    key=\"xxxxxxxxxxxxxxxxxxxxxxxxx\",\n",
+    "    biosphere_name=\"ecoinvent-3.10-biosphere\",\n",
+    ")"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### As a Superstructure database\n",
-    "A superstructure database is a database that can accomodate several scenarios, as described [here](https://github.com/dgdekoning/brightway-superstructure), to be then used in [Activity-Browser](https://github.com/LCA-ActivityBrowser/activity-browser).\n",
-    "This function will export the superstructure database as well as produce a \"scenario difference file\". Hence, even though you create multiple scenarios, **you only need to write to disk one database**."
+    "Then, you must choose the sectors to apply and the sequence of their implementation (and groupings if so desired)."
    ]
   },
   {
@@ -765,7 +867,22 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "ndb.write_superstructure_db_to_brightway()"
+    "# in this case, we wish to apply transformations relating to \n",
+    "# the electricity sector, the steel sector, as well as the \n",
+    "# cement, cars and fuel sectors. However, in this example, \n",
+    "# these last three will be considered altogether.\n",
+    "\n",
+    "sectors = {\n",
+    "    \"electricity\": \"electricity\",\n",
+    "    \"steel\": \"steel\",\n",
+    "    \"others\": [\n",
+    "        \"cement\",\n",
+    "        \"cars\",\n",
+    "        \"fuels\"\n",
+    "    ]\n",
+    "}\n",
+    "\n",
+    "ndb.update(sectors=sectors)"
    ]
   },
   {
@@ -774,24 +891,27 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "ndb.write_superstructure_db_to_brightway(name=\"my_db\")"
+    "# we export the database to brightway and open it in Activity Browser\n",
+    "# Just like a superstructure database, we load the scenario difference\n",
+    "# file premise has co-produced in the calculation setup window\n",
+    "# and we run an anlaysis. For more info, see how to conduct an analysis\n",
+    "# with a superstructure database.\n",
+    "\n",
+    "ndb.write_increment_db_to_brightway(name=\"test increment\", file_format=\"csv\")"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### As a data package\n",
-    "Export a data package, which can be shared. Data packages cna be read by [unfold](https://github.com/polca/unfold) and databases can be reproduced on other computers."
+    "This lets use see the influence of each sector on the score of our LCA."
    ]
   },
   {
-   "cell_type": "code",
-   "execution_count": null,
+   "cell_type": "markdown",
    "metadata": {},
-   "outputs": [],
    "source": [
-    "ndb.write_datapackage()"
+    "![\"incremental_example\"](incremental_example.png)"
    ]
   },
   {
@@ -870,7 +990,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.10.13"
+   "version": "3.11.8"
   }
  },
  "nbformat": 4,
diff --git a/examples/incremental_example.png b/examples/incremental_example.png
new file mode 100644
index 00000000..56c21ff0
Binary files /dev/null and b/examples/incremental_example.png differ