ecoscope.io.earthranger ======================= .. py:module:: ecoscope.io.earthranger Module Contents --------------- .. py:data:: EventSortOptions .. py:data:: StatusOptions .. py:data:: ApiVersionSelection .. py:data:: AppendCategorySelection .. py:data:: SAFE_QUERY_PARAM_LIST_SIZE :value: 50 .. py:class:: EarthRangerIO(sub_page_size = 4000, tcp_limit = 5, **kwargs) Bases: :py:obj:`erclient.client.ERClient` ERClient provides basic access to the EarthRanger server API. You will need the server hostname as well as credentials in the form of a username/password or access token. The boiler-plate code handles authentication, so you don't have to think about Oauth2 or refresh tokens. .. py:attribute:: token .. py:attribute:: sub_page_size :value: 4000 .. py:attribute:: tcp_limit :value: 5 .. py:method:: _token_request(payload) .. py:method:: _use_v2_api() Context manager to safely handle switching the internal client service root to the v2 api base where required, and then switch back to v1 .. py:method:: get_sources(manufacturer_id = None, provider_key = None, provider = None, id = None, sub_page_size = None, **addl_kwargs) :param manufacturer_id: :param provider_key: :param provider: :param id: :param sub_page_size: Optionally set a specific sub_page_size for this request, instead of using the client default :type sub_page_size: int | None :returns: **sources** -- DataFrame of queried sources :rtype: pd.DataFrame .. py:method:: get_subjects(include_inactive = None, bbox = None, subject_group_id = None, name = None, updated_since = None, tracks = None, id = None, updated_until = None, subject_group_name = None, max_ids_per_request = 50, sub_page_size = None, **addl_kwargs) :param include_inactive: :type include_inactive: Include inactive subjects in list. :param bbox: west, south, east, north. :type bbox: Include subjects having track data within this bounding box defined by a 4-tuple of coordinates marking :param subject_group_id: This is translated to the subject_group parameter in the ER backend :type subject_group_id: Indicate a subject group id for which Subjects should be listed. :param name: :type name: Find subjects with the given name :param updated_since: :type updated_since: Return Subject that have been updated since the given timestamp. :param tracks: :type tracks: Indicate whether to render each subject's recent tracks. :param id: :type id: A comma-delimited list of Subject IDs. :param updated_until: :param subject_group_name: This is translated to the group_name parameter in the ER backend :type subject_group_name: A subject group name for which Subjects should be listed. :param sub_page_size: Optionally set a specific sub_page_size for this request, instead of using the client default :type sub_page_size: int | None :returns: **subjects** :rtype: pd.DataFrame .. py:method:: get_subjectsources(subjects = None, sources = None, sub_page_size = None, **addl_kwargs) :param subjects: :type subjects: A comma-delimited list of Subject IDs. :param sources: :type sources: A comma-delimited list of Source IDs. :param sub_page_size: Optionally set a specific sub_page_size for this request, instead of using the client default :type sub_page_size: int | None :returns: **subjectsources** :rtype: pd.DataFrame .. py:method:: _get_observations(source_ids = None, subject_ids = None, subjectsource_ids = None, tz='UTC', since = None, until = None, filter = None, include_details = None, created_after = None, sub_page_size = None, **addl_kwargs) Return observations matching queries. If `subject_id`, `source_id`, or `subjectsource_id` is specified, the index is set to the provided value. :param subject_ids: :type subject_ids: filter to a single subject :param source_ids: :type source_ids: filter to a single source :param subjectsource_ids: :type subjectsource_ids: filter to a subjectsource_id, rather than source_id + time range :param since: :type since: get observations after this ISO8061 date, include timezone :param until: :type until: get observations up to this ISO8061 date, include timezone :param filter: filter using exclusion_flags for an observation. filter=None returns everything filter=0 filters out everything but rows with exclusion flag 0 (i.e, passes back clean data) filter=1 filters out everything but rows with exclusion flag 1 (i.e, passes back manually filtered data) filter=2, filters out everything but rows with exclusion flag 2 (i.e., passes back automatically filtered data) filter=3, filters out everything but rows with exclusion flag 2 or 1 (i.e., passes back both manual and automatically filtered data) :param include_details: :type include_details: one of [true,false], default is false. This brings back the observation additional field :param created_after: :type created_after: get observations created (saved in EarthRanger) after this ISO8061 date, include timezone :param sub_page_size: Optionally set a specific sub_page_size for this request, instead of using the client default :type sub_page_size: int | None :returns: **observations** :rtype: gpd.GeoDataFrame .. py:method:: get_source_observations(source_ids, include_source_details = False, relocations = True, **kwargs) Get observations for each listed source and create a `Relocations` object. :param source_ids: List of source UUIDs :type source_ids: str or list[str] :param include_source_details: Whether to merge source info into dataframe :type include_source_details: bool, optional :param sub_page_size: Optionally set a specific sub_page_size for this request, instead of using the client default :type sub_page_size: int | None :param kwargs: Additional arguments to pass in the request to EarthRanger. See the docstring of `_get_observations` for info. :returns: **relocations** -- Observations in `Relocations` format :rtype: ecoscope.Relocations .. py:method:: get_subject_observations(subject_ids, include_source_details = False, include_subject_details = False, include_subjectsource_details = False, relocations = True, sub_page_size = None, **kwargs) Get observations for each listed subject and create a `Relocations` object. :param subject_ids: List of subject UUIDs, or a DataFrame of subjects :type subject_ids: str or list[str] or pd.DataFrame :param include_source_details: Whether to merge source info into dataframe :type include_source_details: bool, optional :param include_subject_details: Whether to merge subject info into dataframe :type include_subject_details: bool, optional :param include_subjectsource_details: Whether to merge subjectsource info into dataframe :type include_subjectsource_details: bool, optional :param sub_page_size: Optionally set a specific sub_page_size for this request, instead of using the client default :type sub_page_size: int | None :param kwargs: Additional arguments to pass in the request to EarthRanger. See the docstring of `__get_observations` for info. :returns: **relocations** -- Observations in `Relocations` format :rtype: ecoscope.Relocations .. py:method:: get_subjectsource_observations(subjectsource_ids, include_source_details = False, relocations = True, **kwargs) Get observations for each listed subjectsource and create a `Relocations` object. :param subjectsource_ids: List of subjectsource UUIDs :type subjectsource_ids: str or list[str] :param include_source_details: Whether to merge source info into dataframe :type include_source_details: bool, optional :param kwargs: Additional arguments to pass in the request to EarthRanger. See the docstring of `__get_observations` for info. :returns: **relocations** -- Observations in `Relocations` format :rtype: ecoscope.Relocations .. py:method:: get_subjectgroup_observations(subject_group_id = None, subject_group_name = None, include_inactive = True, sub_page_size = None, **kwargs) :param subject_group_id: UUID of subject group to filter by :type subject_group_id: str :param subject_group_name: Common name of subject group to filter by :type subject_group_name: str :param include_inactive: Whether to get observations for Subjects marked inactive by EarthRanger :type include_inactive: bool, optional :param sub_page_size: Optionally set a specific sub_page_size for this request, instead of using the client default :type sub_page_size: int | None :param kwargs: Additional arguments to pass in the request to `get_subject_observations`. See the docstring of `get_subject_observations` for info. :returns: **relocations** -- Observations in `Relocations` format :rtype: ecoscope.Relocations .. py:method:: get_event_types(include_inactive = False, api_version = 'both', **addl_kwargs) Return dataframe of ER event types :param include_inactive: Whether to include inactive event types :type include_inactive: bool, default False :param api_version: Whether to fetch v1 or v2 event types, or both :type api_version: "v1","v2", or "both", default "both" :rtype: pd.DataFrame .. py:method:: get_choices_from_v2_event_type(event_type, choice_field) Retrieve choice options for a specific field from a v2 event type schema. :param event_type: The event type identifier. :type event_type: str :param choice_field: The name of the choice field to extract options from. :type choice_field: str :returns: A dictionary mapping choice values (const) to their display titles. :rtype: dict[str, str] .. py:method:: get_fields_from_event_type_schema(event_type) Retrieve all fields from an event type schema. Attempts to fetch from the v2 API first, falling back to the v1 API if the event type is not found in v2. :param event_type: The event type identifier. :type event_type: str :returns: A dictionary mapping field names to their display titles. :rtype: dict[str, str] .. py:method:: get_events(is_collection = None, updated_size = None, event_ids = None, bbox = None, sort_by = None, patrol_segment = None, state = None, event_type = None, include_updates = False, include_details = False, include_notes = False, include_related_events = False, include_files = False, max_results = None, oldest_update_date = None, exclude_contained = None, updated_since = None, event_category = None, since = None, until = None, force_point_geometry = True, drop_null_geometry = True, sub_page_size = None, **addl_kwargs) :param is_collection: true/false whether to filter on is_collection :param updated_since: date-string to limit on updated_at :param event_ids: Event IDs, comma-separated :type event_ids: array[string] :param bbox: bounding box including four coordinate values, comma-separated. Ex. bbox=-122.4,48.4,-122.95,49.0 (west, south, east, north). :param sort_by: Sort by (use 'event_time', 'updated_at', 'created_at', 'serial_number') with optional minus ('-') prefix to reverse order. :param patrol_segment: ID of patrol segment to filter on :param state: Comma-separated list of 'scheduled'/'active'/'overdue'/'done'/'cancelled' :param event_type: Comma-separated list of event type uuids :param include_updates: Boolean value :param include_details: Boolean value :param include_notes: Boolean value :param include_related_events: Boolean value :param include_files: Boolean value :param max_results: :param oldest_update_date: :param exclude_contained: :param event_category: :param since: :param until: :param force_point_geometry: If true, non point geometry (ie polys) will be converted to a single point via Shape.centroid :type force_point_geometry: bool, default True :param drop_null_geometry: If true, events with no geometry will be removed from output :type drop_null_geometry: bool, default True :param sub_page_size: Optionally set a specific sub_page_size for this request, instead of using the client default :type sub_page_size: int | None :returns: **events** -- GeoDataFrame of queried events :rtype: gpd.GeoDataFrame .. py:method:: get_event_type_display_names_from_events(events_gdf, append_category_names = 'never') For the provided events_gdf, append an "event_type_display" column containing the display names for each event type, optionally including the corresponding event category name :param events_gdf: The events dataframe to add display names to :type events_gdf: gpd.GeoDataFrame :param append_category_names: Whether to append the event category to the event type display name If appended, the format value will be: "Event Type (Event Category)" If set to always, the event category value will be appended in all cases If set to duplicates, the event category value will be appended only for event types with overlapping display names If set to never, no category names will be appended :type append_category_names: "always","duplicates", or "never", default "never" :param Event types that are present on events but missing from the ER: :param event-type registry (e.g. deleted/orphan types still attached to: :param historical events) fall back to their raw event_type value as the: :param display: :param rather than raising KeyError.: :rtype: gpd.GeoDataFrame .. py:method:: get_patrol_types() .. py:method:: get_patrols(since = None, until = None, patrol_type = None, patrol_type_value = None, status = None, sub_page_size = None, patrols_overlap_daterange = True, **addl_kwargs) :param since: Lower time range :param until: Upper time range :param patrol_type: A patrol type UUID or a list of UUIDs :param patrol_type_value: A patrol type value or a list of patrol type values :param status: 'scheduled'/'active'/'overdue'/'done'/'cancelled' Accept a status string or a list of statuses :param sub_page_size: Optionally set a specific sub_page_size for this request, instead of using the client default :type sub_page_size: int | None :param patrols_overlap_daterange: If false, restricts patrols to only those that start within the bounds of the provided time range :type patrols_overlap_daterange: bool, default True :returns: **patrols** -- DataFrame of queried patrols :rtype: pd.DataFrame .. py:method:: get_patrol_events(since = None, until = None, patrol_type = None, patrol_type_value = None, event_type = None, status = None, force_point_geometry = True, drop_null_geometry = True, sub_page_size = None, patrols_overlap_daterange = True, **addl_kwargs) :param since: Lower time range :param until: Upper time range :param patrol_type: A patrol type UUID or a list of UUIDs :param patrol_type_value: A patrol type value or a list of patrol type values :param status: 'scheduled'/'active'/'overdue'/'done'/'cancelled' Accept a status string or a list of statuses :param force_point_geometry: If true, non point geometry (ie polys) will be converted to a single point via Shape.centroid :type force_point_geometry: bool, default True :param drop_null_geometry: If true, events with no geometry will be removed from output :type drop_null_geometry: bool, default True :param sub_page_size: Optionally set a specific sub_page_size for this request, instead of using the client default :type sub_page_size: int | None :param patrols_overlap_daterange: If false, restricts patrols to only those that start within the bounds of the provided time range :type patrols_overlap_daterange: bool, default True :returns: **events** -- DataFrame of queried patrols :rtype: pd.DataFrame .. py:method:: get_patrol_segments_from_patrol_id(patrol_id, **addl_kwargs) Download patrols for a given `patrol id`. :param patrol_id: Patrol UUID. :param kwargs: Additional parameters to pass to `_get`. :returns: **dataframe** :rtype: Dataframe of patrols. .. py:method:: get_patrol_segments() .. py:method:: get_patrol_observations_with_patrol_filter(since = None, until = None, patrol_type = None, patrol_type_value = None, status = None, include_patrol_details = False, sub_page_size = None, patrols_overlap_daterange = True, **kwargs) Download observations for patrols with provided filters. :param since: Lower time range :param until: Upper time range :param patrol_type: A patrol type UUID or a list of UUIDs :param patrol_type_value: A patrol type value or a list of patrol type values :param status: 'scheduled'/'active'/'overdue'/'done'/'cancelled' Accept a status string or a list of statuses :param include_patrol_details: Whether to merge patrol details into dataframe :type include_patrol_details: bool, optional :param sub_page_size: Optionally set a specific sub_page_size for this request, instead of using the client default :type sub_page_size: int | None :param patrols_overlap_daterange: If false, restricts patrols to only those that start within the bounds of the provided time range :type patrols_overlap_daterange: bool, default True :param kwargs: Additional parameters to pass to `get_subject_observations`. :returns: **relocations** :rtype: ecoscope.Relocations .. py:method:: get_patrol_observations(patrols_df, include_patrol_details = False, sub_page_size = None, **kwargs) Download observations for provided `patrols_df`. :param patrols_df: Data returned from a call to `get_patrols`. :type patrols_df: pd.DataFrame :param include_patrol_details: Whether to merge patrol details into dataframe :type include_patrol_details: bool, optional :param sub_page_size: Optionally set a specific sub_page_size for this request, instead of using the client default :type sub_page_size: int | None :param kwargs: Additional parameters to pass to `get_subject_observations`. :returns: **relocations** :rtype: ecoscope.Relocations .. py:method:: get_patrol_segment_events(patrol_segment_id = None, include_details = False, include_files = False, include_related_events = False, include_notes = False, **addl_kwargs) .. py:method:: get_spatial_features_group(spatial_features_group_name = None, spatial_features_group_id = None, with_group_data = False, **addl_kwargs) Download spatial features in a spatial features group for a given `spatial features group id`. :param spatial_features_group_id: Spatial Features Group UUID. :param with_group_data: Whether or not to return group data :param kwargs: Additional parameters to pass to `_get`. :returns: * *If with_group_data is False this will return a GDF of the features within the requested group* * *If with_group_data is True this will return a dict containing the group data and a "features"* -- field containing a GDF of the features within the requested group .. py:method:: get_spatial_feature(spatial_feature_id = None, **addl_kwargs) Download spatial feature for a given `spatial feature id`. :param spatial_feature_id: Spatial Feature UUID. :param kwargs: Additional parameters to pass to `_get`. :returns: **dataframe** :rtype: GeoDataFrame of spatial feature. .. py:method:: post_source(source_type, manufacturer_id, model_name, provider = 'default', additional = None, **kwargs) :param source_type: :param manufacturer_id: :param model_name: :param provider: :param additional: :rtype: pd.DataFrame .. py:method:: post_sourceproviders(provider_key, display_name, additional = None, **kwargs) :param provider_key: :param display_name: :rtype: pd.DataFrame .. py:method:: post_subject(subject_name, subject_type, subject_subtype, is_active = True, **kwargs) :param subject_name: :param subject_subtype: :param is_active: :rtype: pd.DataFrame .. py:method:: post_subjectsource(subject_id, source_id, lower_bound_assigned_range, upper_bound_assigned_range, additional = None) :param subject_id: :param source_id: :param lower_bound_assigned_range: :param upper_bound_assigned_range: :param additional: :rtype: pd.DataFrame .. py:method:: post_observations(observations, source_id_col = 'source', recorded_at_col = 'recorded_at') :param observations: observation data to be uploaded :type observations: gpd.GeoDataFrame :param source_id_col: The source column in the observation dataframe :type source_id_col: str :param recorded_at_col: The observation recorded time column in the dataframe :type recorded_at_col: str :rtype: None .. py:method:: post_event(events) :param events: :returns: New events created in EarthRanger. :rtype: pd.DataFrame .. py:method:: post_patrol(priority, **kwargs) :param priority: :rtype: pd.DataFrame .. py:method:: post_patrol_segment(patrol_id, patrol_segment_id, patrol_type = None, tracked_subject_id = None, scheduled_start = None, scheduled_end = None, start_time = None, end_time = None, start_location = None, end_location = None, **kwargs) :param patrol_id: :param patrol_segment_id: :param patrol_type: :param tracked_subject_id: :param scheduled_start: :param scheduled_end: :param start_time: :param end_time: :param start_location: :param end_location: :rtype: pd.DataFrame .. py:method:: post_patrol_segment_event(patrol_segment_id, event_type, **addl_kwargs) :param patrol_segment_id: :param event_type: :rtype: pd.DataFrame .. py:method:: patch_event(event_id, events) :param event_id: UUID for the event that will be updated. :param events: :returns: Updated events in EarthRanger. :rtype: pd.DataFrame .. py:method:: delete_observation(observation_id) :param observation_id: :param -------: