ecoscope.io.earthranger#

Module Contents#

ecoscope.io.earthranger.fatal_status_code(e)[source]#
class ecoscope.io.earthranger.EarthRangerIO(sub_page_size=4000, tcp_limit=5, **kwargs)[source]#

Bases: 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.

_token_request(payload)[source]#
static _clean_kwargs(addl_kwargs={}, **kwargs)[source]#
static _normalize_column(df, col)[source]#
static _dataframe_to_dict(events)[source]#
static _to_gdf(df)[source]#
get_sources(manufacturer_id=None, provider_key=None, provider=None, id=None, **addl_kwargs)[source]#
Parameters:

  • manufacturer_id –

  • provider_key –

  • provider –

  • id –

Returns:

sources – DataFrame of queried sources

Return type:

pd.DataFrame

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)[source]#
Parameters:

  • include_inactive (Include inactive subjects in list.) –

  • bbox (Include subjects having track data within this bounding box defined by a 4-tuple of coordinates marking) – west, south, east, north.

  • subject_group (Indicate a subject group for which Subjects should be listed.) –

  • name (Find subjects with the given name) –

  • updated_since (Return Subject that have been updated since the given timestamp.) –

  • tracks (Indicate whether to render each subject's recent tracks.) –

  • id (A comma-delimited list of Subject IDs.) –

  • updated_until –

  • group_name –

Returns:

subjects

Return type:

pd.DataFrame

get_subjectsources(subjects=None, sources=None, **addl_kwargs)[source]#
Parameters:

  • subjects (A comma-delimited list of Subject IDs.) –

  • sources (A comma-delimited list of Source IDs.) –

Returns:

subjectsources

Return type:

pd.DataFrame

_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)[source]#

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)

Parameters:

  • include_details (one of [true,false], default is false. This brings back the observation additional field) –

  • created_after (get observations created (saved in EarthRanger) after this ISO8061 date, include timezone) –

Returns:

observations

Return type:

gpd.GeoDataFrame

get_source_observations(source_ids, include_source_details=False, relocations=True, **kwargs)[source]#

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

Return type:

ecoscope.base.Relocations

get_subject_observations(subject_ids, include_source_details=False, include_subject_details=False, include_subjectsource_details=False, relocations=True, **kwargs)[source]#

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

Return type:

ecoscope.base.Relocations

get_subjectsource_observations(subjectsource_ids, include_source_details=False, relocations=True, **kwargs)[source]#

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

Return type:

ecoscope.base.Relocations

get_subjectgroup_observations(subject_group=None, group_name=None, include_inactive=True, **kwargs)[source]#
Parameters:

  • subject_group (str) – UUID of subject group to filter by

  • group_name (str) – Common name of subject group to filter by

  • include_inactive (bool, optional) – Whether to get observations for Subjects marked inactive by EarthRanger

  • 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

Return type:

ecoscope.base.Relocations

get_event_types(include_inactive=False, **addl_kwargs)[source]#
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)[source]#
Parameters:

  • is_collection – true/false whether to filter on is_collection

  • updated_since – date-string to limit on updated_at

  • event_ids (array[string]) – Event IDs, comma-separated

  • bbox – bounding box including four coordinate values, comma-separated. Ex. bbox=-122.4,48.4,-122.95,49.0 (west, south, east, north).

  • sort_by – Sort by (use ‘event_time’, ‘updated_at’, ‘created_at’, ‘serial_number’) with optional minus (‘-’) prefix to reverse order.

  • patrol_segment – ID of patrol segment to filter on

  • state – Comma-separated list of ‘scheduled’/’active’/’overdue’/’done’/’cancelled’

  • event_type – Comma-separated list of event type uuids

  • include_updates – Boolean value

  • include_details – Boolean value

  • include_notes – Boolean value

  • include_related_events – Boolean value

  • include_files – Boolean value

  • max_results –

  • oldest_update_date –

  • exclude_contained –

  • event_category –

  • since –

  • until –

Returns:

events – GeoDataFrame of queried events

Return type:

gpd.GeoDataFrame

get_patrol_types()[source]#
get_patrols(since=None, until=None, patrol_type=None, status=None, **addl_kwargs)[source]#
Parameters:

  • since – lower date range

  • until – upper date range

  • patrol_type – Comma-separated list of type of patrol UUID

  • status – Comma-separated list of ‘scheduled’/’active’/’overdue’/’done’/’cancelled’

Returns:

patrols – DataFrame of queried patrols

Return type:

pd.DataFrame

get_patrol_segments_from_patrol_id(patrol_id, **addl_kwargs)[source]#

Download patrols for a given patrol id.

Parameters:

  • patrol_id – Patrol UUID.

  • kwargs – Additional parameters to pass to _get.

Returns:

dataframe

Return type:

Dataframe of patrols.

get_patrol_segments()[source]#
get_patrol_observations(patrols_df, include_patrol_details=False, **kwargs)[source]#

Download observations for provided patrols_df.

Parameters:

  • patrols_df (pd.DataFrame) – Data returned from a call to get_patrols.

  • include_patrol_details (bool, optional) – Whether to merge patrol details into dataframe

  • kwargs – Additional parameters to pass to get_subject_observations.

Returns:

relocations

Return type:

ecoscope.base.Relocations

get_patrol_segment_events(patrol_segment_id=None, include_details=False, include_files=False, include_related_events=False, include_notes=False, **addl_kwargs)[source]#
get_spatial_features_group(spatial_features_group_id=None, **addl_kwargs)[source]#

Download spatial features in a spatial features group for a given spatial features group id.

Parameters:

  • spatial_features_group_id – Spatial Features Group UUID.

  • kwargs – Additional parameters to pass to _get.

Returns:

dataframe

Return type:

GeoDataFrame of spatial features in a spatial features group.

get_spatial_feature(spatial_feature_id=None, **addl_kwargs)[source]#

Download spatial feature for a given spatial feature id.

Parameters:

  • spatial_feature_id – Spatial Feature UUID.

  • kwargs – Additional parameters to pass to _get.

Returns:

dataframe

Return type:

GeoDataFrame of spatial feature.

post_source(source_type, manufacturer_id, model_name, provider='default', additional={}, **kwargs)[source]#
Parameters:

  • source_type (str) –

  • manufacturer_id (str) –

  • model_name (str) –

  • provider (str) –

  • additional (Dict) –

Return type:

pd.DataFrame

post_subject(subject_name, subject_type, subject_subtype, is_active=True, **kwargs)[source]#
Parameters:

  • subject_name (str) –

  • subject_subtype (str) –

  • is_active (bool) –

  • subject_type (str) –

Return type:

pd.DataFrame

post_subjectsource(subject_id, source_id, lower_bound_assigned_range, upper_bound_assigned_range, additional=None)[source]#
Parameters:

  • subject_id (str) –

  • source_id (str) –

  • lower_bound_assigned_range (datetime.datetime) –

  • upper_bound_assigned_range (datetime.datetime) –

  • additional (Dict) –

Return type:

pd.DataFrame

post_observations(observations, source_id_col='source', recorded_at_col='recorded_at')[source]#
Parameters:

  • observations (gpd.GeoDataFrame) – observation data to be uploaded

  • source_id_col (str) – The source column in the observation dataframe

  • recorded_at_col (str) – The observation recorded time column in the dataframe

Return type:

None

post_event(events)[source]#
Parameters:

events (Union[geopandas.GeoDataFrame, pandas.DataFrame, Dict, List[Dict]]) –

Returns:

New events created in EarthRanger.

Return type:

pd.DataFrame

post_patrol(priority, **kwargs)[source]#
Parameters:

priority (int) –

Return type:

pd.DataFrame

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)[source]#
Parameters:

  • patrol_id (str) –

  • patrol_segment_id (str) –

  • patrol_type (str) –

  • tracked_subject_id (str) –

  • scheduled_start (str) –

  • scheduled_end (str) –

  • start_time (str) –

  • end_time (str) –

  • start_location (Tuple[float, float]) –

  • end_location (Tuple[float, float]) –

Return type:

pd.DataFrame

post_patrol_segment_event(patrol_segment_id, event_type, **addl_kwargs)[source]#
Parameters:

  • patrol_segment_id (str) –

  • event_type (str) –

Return type:

pd.DataFrame

patch_event(event_id, events)[source]#
Parameters:

  • event_id (str) – UUID for the event that will be updated.

  • events (Union[geopandas.GeoDataFrame, pandas.DataFrame, Dict, List[Dict]]) –

Returns:

Updated events in EarthRanger.

Return type:

pd.DataFrame

delete_observation(observation_id)[source]#
Parameters:

  • observation_id (str) –

  • ------- –