diff --git a/docs/examples/index.rst b/docs/examples/index.rst
deleted file mode 100644
index c810be7..0000000
--- a/docs/examples/index.rst
+++ /dev/null
@@ -1,10 +0,0 @@
-Examples
-========
-
-.. toctree::
- :maxdepth: 3
-
- create.rst
- create-aggregates.rst
- read.rst
- query.rst
\ No newline at end of file
diff --git a/docs/examples/create-aggregates.rst b/docs/how-to/create-aggregates.rst
similarity index 97%
rename from docs/examples/create-aggregates.rst
rename to docs/how-to/create-aggregates.rst
index 60aa673..9b52267 100644
--- a/docs/examples/create-aggregates.rst
+++ b/docs/how-to/create-aggregates.rst
@@ -1,5 +1,5 @@
-Example - create aggregate data
-===============================
+How to create aggregate data
+============================
We want to run a survey about how many people like hats.
@@ -10,7 +10,7 @@ First we'll import the library and make a new store.
.. code-block:: python
from ocdsmetricsanalysis.library import Store
- store = Store("example-create-aggregates.sqlite")
+ store = Store("how-to-create-aggregates.sqlite")
We'll add our own metric.
diff --git a/docs/examples/create.rst b/docs/how-to/create-export.rst
similarity index 85%
rename from docs/examples/create.rst
rename to docs/how-to/create-export.rst
index a38e813..f0020e8 100644
--- a/docs/examples/create.rst
+++ b/docs/how-to/create-export.rst
@@ -1,5 +1,5 @@
-Example - create data
-=====================
+How to create and export data
+=============================
Open a python shell in interactive mode (run `python3`) and run the following commands in sequence.
@@ -9,7 +9,7 @@ First we'll import the library and make a new store.
.. code-block:: python
from ocdsmetricsanalysis.library import Store
- store = Store("example-create.sqlite")
+ store = Store("how-to-create-export.sqlite")
Currently the store is empty, as you can see by getting a list of current metrics.
@@ -33,6 +33,10 @@ Now we have our metric, but we need to add some observations to it.
metric.add_observation("obs2", measure=15, dimensions={'answer':'neither like or dislike'})
metric.add_observation("obs3", measure=12, dimensions={'answer':'dislike'})
+The first parameter is the id of the observation. This must be unique in the metric.
+
+You can also :doc:`pass other information such as financial data or unit information - see the reference for details <../python-api/metric>`.
+
Now our store contains some data - we can export this as JSON.
.. code-block:: python
diff --git a/docs/examples/read.rst b/docs/how-to/import.rst
similarity index 95%
rename from docs/examples/read.rst
rename to docs/how-to/import.rst
index 6bd4bd1..5473864 100644
--- a/docs/examples/read.rst
+++ b/docs/how-to/import.rst
@@ -1,5 +1,5 @@
-Example - read data
-===================
+How to import data
+==================
Start by getting a data file:
@@ -16,7 +16,7 @@ First we'll import the library and make a new store.
.. code-block:: python
from ocdsmetricsanalysis.library import Store
- store = Store("example-read.sqlite")
+ store = Store("how-to-import.sqlite")
Currently the store is empty, as you can see by getting a list of current metrics.
diff --git a/docs/how-to/index.rst b/docs/how-to/index.rst
new file mode 100644
index 0000000..e243c6d
--- /dev/null
+++ b/docs/how-to/index.rst
@@ -0,0 +1,10 @@
+How To
+======
+
+.. toctree::
+ :maxdepth: 3
+
+ create-export.rst
+ query.rst
+ import.rst
+ create-aggregates.rst
\ No newline at end of file
diff --git a/docs/examples/query.rst b/docs/how-to/query.rst
similarity index 95%
rename from docs/examples/query.rst
rename to docs/how-to/query.rst
index 404c7b2..cfa0cc7 100644
--- a/docs/examples/query.rst
+++ b/docs/how-to/query.rst
@@ -1,5 +1,5 @@
-Example - query data
-====================
+How to query data
+=================
Setup
-----
@@ -11,7 +11,7 @@ First we'll import the library, make a new store and add some sample data to que
.. code-block:: python
from ocdsmetricsanalysis.library import Store
- store = Store("example-query.sqlite")
+ store = Store("how-to-query.sqlite")
store.add_metric("HATS", "How many people like hats?", "We ran a survey to find out.")
metric = store.get_metric("HATS")
metric.add_observation("obs1", measure=34, dimensions={'answer':'like'})
@@ -171,7 +171,7 @@ Now get all data and print it, as before.
12
{'answer': 'dislike'}
-This is however a touch inconvenient; you have to know what all the other dimensions are and specifically exclude them. Fortunately there is an easier way to do this - let's get a new Observation List object and try again.
+This is however inconvenient; you have to know what all the other dimensions are and specifically exclude them. Fortunately there is an easier way to do this - let's get a new Observation List object and try again.
.. code-block:: python
diff --git a/docs/index.rst b/docs/index.rst
index 07cfa0d..f4879d5 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -12,9 +12,6 @@ It can be used in a `Jupyter `_ or `Google Colab list:
class ObservationList:
+ """A class to get list of observations from a metric.
+ It has methods to set query filters, and then methods to get the data.
+
+ Do not construct directly; instead call `get_observation_list` on a Metric to get an observation list.
+ """
+
def __init__(self, metric: Metric):
self._metric: Metric = metric
self._store: Store = metric._store
@@ -314,8 +335,10 @@ def filter_by_dimension_not_set(self, dimension_key: str):
"""Filter by dimension - this key must not exist on the observation."""
self._filter_by_dimensions_not_set.append(dimension_key)
- def get_data(self):
- """Returns a list of Observations matching the filters set on this object."""
+ def get_data(self) -> list:
+ """Returns a list of Observations.
+
+ Observations will match the filters set on this observation list. (Just don't set any filters to get all observations.)"""
cur = self._store._database_connection.cursor()
params: dict = {"metric_id": self._metric._metric_id}
@@ -366,13 +389,18 @@ def get_data(self):
cur.execute(sql, params)
- out = []
+ out: list = []
for result in cur.fetchall():
out.append(Observation(self._metric, result))
return out
- def get_data_by_dimension(self, dimension_key: str):
- out = defaultdict(list)
+ def get_data_by_dimension(self, dimension_key: str) -> dict:
+ """Returns Observations grouped by the value of a dimension key.
+
+ Observations will match the filters set on this observation list. (Just don't set any filters to get all observations.)
+
+ Returns a dict. The key is the value of the dimension, and the value is a list of all observations with that dimension value."""
+ out: dict = defaultdict(list)
for observation in self.get_data():
dimensions: dict = observation.get_dimensions()
if dimensions.get(dimension_key):
@@ -381,6 +409,12 @@ def get_data_by_dimension(self, dimension_key: str):
class Observation:
+ """A class representing one observation from a store.
+ It has methods to get information.
+
+ Do not construct directly; instead use an ObservationList to get Observations.
+ """
+
def __init__(self, metric: Metric, observation_row_data):
self._metric: Metric = metric
self._store: Store = metric._store