Adding basic documentation about contexts
@@ -26,7 +26,7 @@ Typically, you'll want to attach the data that you insert to entities already in
the database. This allows you to recover objects in a hierarchical fashion from
the database later. ``Worm``, for instance has a property, ``neuron_network``,
which points to the ``Network`` which should contain all neural cells and
-synaptic connections. To initialize the hiearchy you would do something like::
+synaptic connections. To initialize the hierarchy you would do something like::
w = Worm('C. briggsae') # The name is optional and currently defaults to 'C. elegans'
nn = Network() # make a neuron network
@@ -97,3 +97,56 @@ the database.
would be possible with one query and thus not requiring parsing and iterating
over neurons twice--it's all done in a single, simple query.
+
+Contexts
+--------
+Above, we didn't qualify our statements in any way, but stated them as simple
+facts. In reality, our statements are made in a context that influences how
+they should be interpreted. In |pow|, that context-sensitivity is modeled by
+using :class:``Context`` objects. To see what this looks like, let's start with
+an example.
+
+Example 1
+^^^^^^^^^
+I have data about widgets from BigDataWarehouse (BDW) that I want to translate
+into RDF using |pow|, but I don't want put them with my other widget data since
+BDW data may conflict with mine. Also, if get more BDW data, I want to be able
+to relate these data to that. A good way to keep data which are made at
+distinct times or which come from different, possibly conflicting, sources is
+using contexts. The code below shows how to do that::
+
+ from rdflib import ConjunctiveGraph
+ from PyOpenWorm.context import Context
+ from mymod import Widget # my model for Widgets
+ from bdw import Load # BigDataWarehouse API
+
+ # Create a Context with an identifier appropriate to this BDW data import
+ ctx = Context(ident='http://example.org/data/imports/BDW_Widgets_2017-2018')
+
+ # Create a context manager using the default behavior of reading the
+ # dictionary of current local variables
+ with ctx(W=Widget) as c:
+ for record in Load(data_set='Widgets2017-2018'):
+ # declares Widgets in this context
+ c.W(part_number=record.pnum,
+ fullness=record.flns,
+ hardiness=record.hrds)
+
+ # Create an RDFLib graph as the target for the data
+ g = ConjunctiveGraph()
+
+ # Save the data
+ c.save_context(g)
+
+ # Serialize the data in the nquads format so we can see that all of our
+ # statements are in the proper context
+ print(g.serialize(format='nquads'))
+
+If you've worked with lots of data before, this kind of pattern should be
+familiar. You can see how, with later imports, you would follow the naming
+scheme to create new contexts (e.g., ``http://example.org/data/imports/BDW_Widgets_2018-2019``).
+
+.. Context metadata
+.. Importing contexts
+.. Evidence, DataSources, DataTranslators, Provenance and contexts
+
