fmu.sumo.explorer.explorer module

Module containing class for exploring results from sumo

class fmu.sumo.explorer.explorer.Explorer(env='prod', token=None, interactive=True, keep_alive=None, http_client=None, async_http_client=None)[source]

Bases: SearchContext

Class for consuming FMU results from Sumo. The Sumo Explorer is a Python package for consuming FMU results stored in Sumo. It is FMU aware, and creates an abstraction on top of the Sumo API. The purpose of the package is to create an FMU-oriented Python interface towards FMU data in Sumo, and make it easy for FMU users in various contexts to use data stored in Sumo.

Examples of use cases:

Applications (example: Webviz)
Scripts (example: Local post-processing functions)
Manual data browsing and visualization (example: A Jupyter Notebook)

Initialize the Explorer class

Parameters:

env (str) – Sumo environment
token (str) – authenticate with existing token
interactive (bool) – authenticate using interactive flow (browser)
keep_alive (str) – point in time lifespan (deprecated and ignored)

property cases: Cases from current selection.

get_permissions(asset=None)[source]

Get permissions

Parameters:: asset (str) – asset in Sumo
Returns:: Dictionary of user permissions
Return type:: dict

async get_permissions_async(asset=None)[source]

Get permissions

Parameters:: asset (str) – asset in Sumo
Returns:: Dictionary of user permissions
Return type:: dict

property aggregations: List[str]: List of unique object aggregation operations.

property aggregations_async: List[str]: List of unique object aggregation operations.

property asset_names: List[str]: List of asset names.

property asset_names_async: List[str]: List of asset names.

batch_aggregate(columns=None, operation=None, no_wait=False)

Aggregate one or more columns for the current context.

Parameters:

columns – list of column names or regular expressions for column names.
operation – must be “collection”
no_wait – set to True if the client handles polling itself.

Returns:

list of column names that occur in the current context and match the names/patterns.

async batch_aggregate_async(columns=None, operation=None, no_wait=False)

Aggregate one or more columns for the current context.

Parameters:

columns – list of column names or regular expressions for column names.
operation – must be “collection”
no_wait – set to True if the client handles polling itself.

Returns:

list of column names that occur in the current context and match the names/patterns.

property cases_async: Cases from current selection.

property classes: List[str]: List of class names.

property classes_async: List[str]: List of class names.

property columns: List[str]: List of unique column names.

property columns_async: List[str]: List of unique column names.

property contents: List[str]: List of unique contents.

property contents_async: List[str]: List of unique contents.

property dataformats: List[str]: List of unique data.format values.

property dataformats_async: List[str]: List of unique data.format values.

property ensembles: Ensembles from current selection.

property ensembles_async: Ensembles from current selection.

property entities: List[str]: List of entity uuids.

property entities_async: List[str]: List of entity uuids.

property fieldidentifiers: List[str]: List of unique field names.

property fieldidentifiers_async: List[str]: List of unique field names.

filter(**kwargs)

Filter SearchContext.

Apply additional filters to SearchContext and return a new filtered instance.

The filters (specified as keyword args) are of these formats:

Id: Match against document id(s) (in uuid format). Boolean: Match boolean value. Name: Match against “data.name”, or “case.name” for case objects. General: Match property against either single value or list of values. If the value given is a boolean, tests for existence or not of the property.

Time: Match against a TimeFilter instance. Complex: Match against user-supplied query, which is a structured Elasticsearch query in dictionary form.

Parameters:

aggregation (General) – “fmu.aggregation.operation.keyword”
asset (General) – “access.asset.name.keyword”
cls (General) – “class.keyword”
column (General) – “data.spec.columns.keyword”
content (General) – “data.content.keyword”
dataformat (General) – “data.format.keyword”
ensemble (General) – “fmu.ensemble.name.keyword”
entity (General) – “fmu.entity.uuid.keyword”
field (General) – “masterdata.smda.field.identifier.keyword”
id (Id)
is_observation (Boolean) – “data.is_observation”
is_prediction (Boolean) – “data.is_prediction”
name (Name)
realization (General) – “fmu.realization.id”
relative_path (General) – “file.relative_path.keyword”
standard_result (General) – “data.standard_result.name.keyword”
status (General) – “_sumo.status.keyword”
stratigraphic (Boolean) – “data.stratigraphic”
tagname (General) – “data.tagname.keyword”
time (Time)
user (General) – “fmu.case.user.id.keyword”
uuid (General) – “fmu.case.uuid.keyword”
vertical_domain (General) – “data.vertical_domain.keyword”
has (Complex)
complex (Complex)

Returns:

A filtered SearchContext.

Return type:

SearchContext

Examples

Match one value:

surfs = case.surfaces.filter(
            ensemble="iter-0",
            name="my_surface_name"
        )

Match multiple values:

surfs = case.surfaces.filter(
            name=["one_name", "another_name"]
        )

Get aggregated surfaces with specific operation:

surfs = case.surfaces.filter(
            aggregation="max"
        )

Get all aggregated surfaces:

surfs = case.surfaces.filter(
            aggregation=True
        )

Get all non-aggregated surfaces:

surfs = case.surfaces.filter(
            aggregation=False
        )

get_case_by_uuid(uuid)

Get case object by uuid

Parameters:: uuid (str) – case uuid
Returns:: case object
Return type:: Case

async get_case_by_uuid_async(uuid)

Get case object by uuid

Parameters:: uuid (str) – case uuid
Returns:: case object
Return type:: Case

get_ensemble_by_uuid(uuid)

Get ensemble object by uuid

Parameters:: uuid (str) – ensemble uuid
Return type:: Ensemble

Returns: ensemble object

async get_ensemble_by_uuid_async(uuid)

Get ensemble object by uuid

Parameters:: uuid (str) – ensemble uuid
Return type:: Ensemble

Returns: ensemble object

get_field_values(field)

Get List of unique values for a given field

Parameters:: field (-) – a metadata field
Return type:: List
Returns:: A List of unique values for the given field

get_field_values_and_counts(field)

Get List of unique values with occurrence counts for a given field

Parameters:: field (-) – a metadata field
Return type:: Dict[str, int]
Returns:: A mapping from unique values to count.

async get_field_values_and_counts_async(field)

Get List of unique values with occurrence counts for a given field

Parameters:: field (-) – a metadata field
Return type:: Dict[str, int]
Returns:: A mapping from unique values to count.

async get_field_values_async(field)

Get List of unique values for a given field

Parameters:: field (-) – a metadata field
Return type:: List
Returns:: A List of unique values for the given field

get_object(uuid)

Get metadata object by uuid

Parameters:

uuid (str) – uuid of metadata object
select (List[str]) – list of metadata fields to return

Returns:

a metadata object

Return type:

Dict

async get_object_async(uuid)

Get metadata object by uuid

Parameters:

uuid (str) – uuid of metadata object
select (List[str]) – list of metadata fields to return

Returns:

a metadata object

Return type:

Dict

get_polygons_by_uuid(uuid)

Get polygons object by uuid

Parameters:: uuid (str) – polygons uuid
Returns:: polygons object
Return type:: Polygons

async get_polygons_by_uuid_async(uuid)

Get polygons object by uuid

Parameters:: uuid (str) – polygons uuid
Returns:: polygons object
Return type:: Polygons

get_realization_by_uuid(uuid)

Get realization object by uuid

Parameters:: uuid (str) – realization uuid
Return type:: Realization

Returns: realization object

async get_realization_by_uuid_async(uuid)

Get realization object by uuid

Parameters:: uuid (str) – realization uuid
Return type:: Realization

Returns: realization object

get_surface_by_uuid(uuid)

Get surface object by uuid

Parameters:: uuid (str) – surface uuid
Returns:: surface object
Return type:: Surface

async get_surface_by_uuid_async(uuid)

Get surface object by uuid

Parameters:: uuid (str) – surface uuid
Returns:: surface object
Return type:: Surface

get_table_by_uuid(uuid)

Get table object by uuid

Parameters:: uuid (str) – table uuid
Returns:: table object
Return type:: Table

async get_table_by_uuid_async(uuid)

Get table object by uuid

Parameters:: uuid (str) – table uuid
Returns:: table object
Return type:: Table

property intervals: List[Tuple]: List of unique intervals in SearchContext

property intervals_async: List[Tuple]: List of unique intervals in SearchContext

limit(n=None)

Set max number of items to search. If set to None, there is no limit. :type n: :param n: Optional[int]

This method returns itself, so it is chainable, but the sort settings will not propagate into a new SearchContextBase (specifically, it will not be passed into the result of .filter()).

Returns: SearchContext (itself)

max(): Deprecated since version Use: the method ‘aggregate’ instead, with parameter ‘operation’.

mean(): Deprecated since version Use: the method ‘aggregate’ instead, with parameter ‘operation’.

property metrics: Metrics for current search context.

min(): Deprecated since version Use: the method ‘aggregate’ instead, with parameter ‘operation’.

property names: List[str]: List of unique object names.

property names_async: List[str]: List of unique object names.

p10(): Deprecated since version Use: the method ‘aggregate’ instead, with parameter ‘operation’.

p50(): Deprecated since version Use: the method ‘aggregate’ instead, with parameter ‘operation’.

p90(): Deprecated since version Use: the method ‘aggregate’ instead, with parameter ‘operation’.

property realizationids: List[int]: List of unique realization ids.

property realizationids_async: List[int]: List of unique realization ids.

property realizations: Realizations from current selection.

property realizations_async: Realizations from current selection.

property reference_realizations: Reference realizations from current selection.

property reference_realizations_async: Reference realizations from current selection.

select(sel)

Specify what should be returned from elasticsearch. Has the side effect of clearing the lru cache. sel is either a single string value, a list of string value, or a dictionary with keys “includes” and/or “excludes” and the values are lists of strings. The string values are nested property names.

This method returns itself, so it is chainable, but the select settings will not propagate into a new SearchContext (specifically, it will not be passed into the result of .filter()).

Parameters:: sel (str | List(str) | Dict(str, List[str]) – select specification
Return type:: SearchContext
Returns:: SearchContext (itself)

property single: Verifies that SearchContext contains exactly one object, and returns it.

property single_async: Verifies that SearchContext contains exactly one object, and returns it.

sort(sortspec)

Set sort order.

Args: sortspec: A single sort specification, or a list of sort

specifications, each of which is a an object with a field as key and a dictionary with key “order” and “asc” or “desc” as value. The default is {“_doc”: {“order”: “asc”}}

This method returns itself, so it is chainable, but the sort settings will not propagate into a new SearchContextBase (specifically, it will not be passed into the result of .filter()).

Returns: SearchContext (itself)

property stages: List[str]: List of unique stages.

property stages_async: List[str]: List of unique stages.

property standard_results: List[str]: List of standard result names.

property standard_results_async: List[str]: List of standard result names.

property statuses: List[str]: List of unique case statuses.

property statuses_async: List[str]: List of unique case statuses.

std(): Deprecated since version Use: the method ‘aggregate’ instead, with parameter ‘operation’.

property stratcolumnidentifiers: List[str]: List of unique stratigraphic column names.

property stratcolumnidentifiers_async: List[str]: List of unique stratigraphic column names.

property tagnames: List[str]: List of unique object tagnames.

property tagnames_async: List[str]: List of unique object tagnames.

property timestamps: List[str]: List of unique timestamps in SearchContext

property timestamps_async: List[str]: List of unique timestamps in SearchContext

property users: List[str]: List of unique user names.

property users_async: List[str]: List of unique user names.

property vertical_domains: List[str]: List of unique object vertical domains.

property vertical_domains_async: List[str]: List of unique object vertical domains.