:py:mod:`ecoscope.io.earthranger` ================================= .. py:module:: ecoscope.io.earthranger Module Contents --------------- .. py:function:: fatal_status_code(e) .. 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:method:: _token_request(payload) .. py:method:: _clean_kwargs(addl_kwargs={}, **kwargs) :staticmethod: .. py:method:: _normalize_column(df, col) :staticmethod: .. py:method:: _dataframe_to_dict(events) :staticmethod: .. py:method:: _to_gdf(df) :staticmethod: .. py:method:: get_sources(manufacturer_id=None, provider_key=None, provider=None, id=None, **addl_kwargs) :param manufacturer_id: :param provider_key: :param provider: :param id: :returns: **sources** -- DataFrame of queried sources :rtype: pd.DataFrame .. py:method:: get_subjects(include_inactive=None, bbox=None, subject_group=None, name=None, updated_since=None, tracks=None, id=None, updated_until=None, group_name=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: :type subject_group: Indicate a subject group 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 group_name: :returns: **subjects** :rtype: pd.DataFrame .. py:method:: get_subjectsources(subjects=None, sources=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. :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, **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 :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 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.base.Relocations .. py:method:: get_subject_observations(subject_ids, include_source_details=False, include_subject_details=False, include_subjectsource_details=False, relocations=True, **kwargs) Get observations for each listed subject and create a `Relocations` object. :param subject_ids: List of subject UUIDs :type subject_ids: str or list[str] :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 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.base.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.base.Relocations .. py:method:: get_subjectgroup_observations(subject_group=None, group_name=None, include_inactive=True, **kwargs) :param subject_group: UUID of subject group to filter by :type subject_group: str :param group_name: Common name of subject group to filter by :type group_name: str :param include_inactive: Whether to get observations for Subjects marked inactive by EarthRanger :type include_inactive: bool, optional :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.base.Relocations .. py:method:: get_event_types(include_inactive=False, **addl_kwargs) .. 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, **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: :returns: **events** -- GeoDataFrame of queried events :rtype: gpd.GeoDataFrame .. py:method:: get_patrol_types() .. py:method:: get_patrols(since=None, until=None, patrol_type=None, status=None, **addl_kwargs) :param since: lower date range :param until: upper date range :param patrol_type: Comma-separated list of type of patrol UUID :param status: Comma-separated list of 'scheduled'/'active'/'overdue'/'done'/'cancelled' :returns: **patrols** -- 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(patrols_df, include_patrol_details=False, **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 kwargs: Additional parameters to pass to `get_subject_observations`. :returns: **relocations** :rtype: ecoscope.base.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_id=None, **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 kwargs: Additional parameters to pass to `_get`. :returns: **dataframe** :rtype: GeoDataFrame of spatial features in a spatial features 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 = {}, **kwargs) :param source_type: :param manufacturer_id: :param model_name: :param provider: :param additional: :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 -------: