Update docs (#273)

* Cleaner README.md

* Cosmetics on documentation index.

* Cleanup, example notebooks.

README.md

@@ -2,110 +2,61 @@
 
 
 # fmu-sumo
-This package is intended for interaction with Sumo within the FMU (Fast Model Update(TM)) ecosystem.
+`fmu.sumo` is a Python package intended for interaction with FMU results stored in Sumo.<br />
+`fmu.sumo.explorer` is a Python API for consuming FMU results from Sumo.
 
-Want to contribute? Read our [contributing](./CONTRIBUTING.md) guidelines
+_Note! Access to Sumo is required. For Equinor users, apply through `AccessIT``._
 
-## Explorer
-
-> :warning: OpenVDS does not publish builds for MacOS. You can still use the Explorer without OpenVDS, but some Cube methods will not work.
+## Installation
+```
+$ pip install fmu-sumo
+```
+... or for the latest development version:
+```
+$ git clone [email protected]:equinor/fmu-sumo.git
+$ cd fmu-sumo
+$ pip install .
+```
+:warning: OpenVDS does not publish builds for MacOS. You can still use the Explorer without OpenVDS, but some Cube methods will not work.
 
-Explore and retrieve data from Sumo.
+#### For development
 
-```python
-from fmu.sumo.explorer import Explorer
+```
+$ git clone <your fork>
+$ cd fmu-sumo
+$ pip install .[dev]
+```
 
-sumo = Explorer()
+#### Run tests
 ```
+$ pytest tests/
+```
+
+## Documentation and guidelines
+:link: [fmu-sumo documentation](https://fmu-sumo.readthedocs.io/en/latest/)
 
-#### Example: Find cases
+## Example usage
 ```python
-# List of all available cases
-cases = sumo.cases
+from fmu.sumo.explorer import Explorer
 
-# Get filter values
-cases.statuses
-cases.users
-cases.fields
+# Connect
+sumo = Explorer()
 
 # Apply filters
 cases = cases.filter(status=["keep", "offical"], user="peesv", field="DROGON")
 
 for case in cases:
-    print(case.uuid)
-    print(case.name)
+    print(f"{case.name} ({case.uuid})")
 
-# select case
+# Select case
 case = cases[0]
-```
-
-#### Example: Retrieve case objects
-Get objects within a case through `case.[CONTEXT].[OBJECT_TYPE]`.
-
-##### Realized data
-```python
-# All realized surface objects in case
-surfs = case.surfaces
-
-# Get filter values
-surfs.names
-surfs.tagnames
-surfs.iterations
 
-# Apply filters
-surfs = surfs.filter(name="surface_name", tagname="surface_tagname", iteration="iter-0")
-
-# Get surface
-surf = surfs[0]
-
-# Metadata
-surf.uuid
-surf.name
-surf.tagname
-surf.iteration
-surf.realization
-
-# Binary
-surf.blob
-
-# Get xtgeo.RegularSurface
-%matplotlib inline
-reg = surf.to_regular_surface()
-reg.quickplot()
+# Alternatively, get specific case via case.uuid
+case = sumo.get_case_by_uuid(<uuid>)
 ```
 
-##### Aggregated data
-```python
-# All aggregated surfaces in case
-surfs = case.surfaces.filter(aggregation=True)
-
-# Get filter values
-surfs.names
-surfs.tagnames
-surfs.iterations
-surfs.aggregations
-
-# Apply filters
-surfs = surfs.filter(name="surface_name", tagname="surface_tagname", iteration="iter-0", aggregation="mean")
-
-# Get surface
-surf = surfs[0]
-
-```
-
-##### Observed data
-```python
-# All observed surfaces in case
-surfs = case.surfaces.filter(is_observation=True)
-
-# Get filter values
-surfs.names
-surfs.tagnames
-
-# Apply filters
-surfs = surfs.filter(name="surface_name", tagname="surface_tagname")
-
-# Get surfaces
-surf = surfs[0]
-```
+## Contribute
+[Contribution guidelines](./CONTRIBUTING.md)
 
+## License
+Apache 2.0

docs/index.rst

@@ -1,16 +1,11 @@
 fmu-sumo
 ########
 
-Sumo is developed for handling storage of data produced in and by FMU workflows
-with the intention of usage outside the realization context. Scope for Sumo in this context
-are the data that are currently left behind on /scratch after the ERT run is finished.
+Sumo is a solution for indexing, storing and supplying results produced by FMU workflows
+and associated processes (post-processing). See the `Sumo front-end for FMU <https://fmu-sumo.app.radix.equinor.com>`_
+for additional information and documentation on Sumo.
 
-Sumo provides indexing, storage, API and data management capabilities for FMU results. Further,
-Sumo provides a data-backend for services for e.g post-processing.
-
-For documentation of Sumo in the FMU context, see the `Sumo front-end for FMU <https://fmu-sumo.app.radix.equinor.com>`_
-
-``fmu-sumo`` is a Python library for interaction with Sumo in the FMU context. It contains
+``fmu-sumo`` is a Python library for interaction with FMU results stored in Sumo. It contains
 multiple modules:
 
 * **Explorer** (This module) for *reading* data from Sumo in the FMU context.

examples/explorer.ipynb

@@ -25,7 +25,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "sumo = Explorer(\"dev\")"
+    "sumo = Explorer()"
    ]
   },
   {
@@ -43,7 +43,8 @@
    "outputs": [],
    "source": [
     "# Get Drogon cases\n",
-    "cases = sumo.cases.filter(asset=\"Drogon\")\n",
+    "myassetname = \"Drogon\" # Must be a valid asset on Sumo\n",
+    "cases = sumo.cases.filter(asset=myassetname)\n",
     "\n",
     "# Get available status filters\n",
     "print(\"Statuses:\",cases.statuses)\n",
@@ -66,10 +67,12 @@
     "    print(\"\\n\")\n",
     "\n",
     "# Get case by name (name is not guaranteed to be unique)\n",
-    "case = sumo.cases.filter(name=\"drogon_design_small-2023-01-18\")[0]\n",
+    "mycasename = cases[0].name # for sake of example\n",
+    "case = sumo.cases.filter(name=mycasename)[0]\n",
     "\n",
     "# Get case by id\n",
-    "case = sumo.cases.filter(uuid=\"2c2f47cf-c7ab-4112-87f9-b4797ec51cb6\")[0]\n",
+    "mycaseuuid = cases[0].uuid # for sake of example\n",
+    "case = sumo.cases.filter(uuid=mycaseuuid)[0]\n",
     "\n",
     "# Select case\n",
     "case = cases[0]\n",
@@ -141,7 +144,7 @@
     "print(\"stratigraphic\", surf.stratigraphic)\n",
     "print(\"vertical domain\", surf.vertical_domain)\n",
     "\n",
-    "# xtge.RegularSurface\n",
+    "# xtgeo.RegularSurface\n",
     "reg_surf = surf.to_regular_surface()\n",
     "reg_surf.quickplot()"
    ]
@@ -219,16 +222,9 @@
    "outputs": [],
    "source": [
     "# Perform aggregation on SurfaceCollection\n",
-    "# surfs.min()\n",
-    "# surfs.max()\n",
-    "# surfs.mean()\n",
-    "# surfs.std()\n",
-    "# surfs.p10()\n",
-    "# surfs.p50()\n",
-    "# surfs.p90()\n",
-    "\n",
-    "min = surfs.min()\n",
-    "min.quickplot()"
+    "\n",
+    "regsurf = surfs.min() # .max(), .mean(), .std(), .p10(), .p90(), .p50()\n",
+    "regsurf.quickplot()"
    ]
   },
   {
@@ -318,7 +314,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.10.12"
+   "version": "3.8.18"
   },
   "orig_nbformat": 4,
   "vscode": {