ecoscope.io.earthranger#

Module Contents#

ecoscope.io.earthranger.EventSortOptions#

ecoscope.io.earthranger.StatusOptions#

ecoscope.io.earthranger.ApiVersionSelection#

ecoscope.io.earthranger.AppendCategorySelection#

ecoscope.io.earthranger.SAFE_QUERY_PARAM_LIST_SIZE = 50#

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.

Parameters:

sub_page_size (int)
tcp_limit (int)

token#

sub_page_size = 4000#

tcp_limit = 5#

_token_request(payload)[source]#

_use_v2_api()[source]#: Context manager to safely handle switching the internal client service root to the v2 api base where required, and then switch back to v1

get_sources(manufacturer_id=None, provider_key=None, provider=None, id=None, sub_page_size=None, **addl_kwargs)[source]#

Parameters:

manufacturer_id (str | None)
provider_key (str | None)
provider (str | None)
id (str | None)
sub_page_size (int | None) – Optionally set a specific sub_page_size for this request, instead of using the client default

Returns:

sources – DataFrame of queried sources

Return type:

pd.DataFrame

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)[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_id (Indicate a subject group id for which Subjects should be listed.) – This is translated to the subject_group parameter in the ER backend
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 (str | None)
subject_group_name (A subject group name for which Subjects should be listed.) – This is translated to the group_name parameter in the ER backend
sub_page_size (int | None) – Optionally set a specific sub_page_size for this request, instead of using the client default
max_ids_per_request (int)

Returns:

subjects

Return type:

pd.DataFrame

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

Parameters:

subjects (A comma-delimited list of Subject IDs.)
sources (A comma-delimited list of Source IDs.)
sub_page_size (int | None) – Optionally set a specific sub_page_size for this request, instead of using the client default

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, sub_page_size=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)
sub_page_size (int | None) – Optionally set a specific sub_page_size for this request, instead of using the client default
source_ids (str | list[str] | None)
subject_ids (str | list[str] | None)
subjectsource_ids (str | list[str] | None)
since (str | None)
until (str | None)
filter (int | None)

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 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

Return type:

ecoscope.Relocations

Parameters:

source_ids (str | list[str])
include_source_details (bool)
relocations (bool)

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

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

Return type:

ecoscope.Relocations

Parameters:

subject_ids (str | list[str] | pandas.DataFrame)
include_source_details (bool)
include_subject_details (bool)
include_subjectsource_details (bool)
relocations (bool)
sub_page_size (int | None)

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.Relocations

Parameters:

subjectsource_ids (str | list[str])
include_source_details (bool)
relocations (bool)

get_subjectgroup_observations(subject_group_id=None, subject_group_name=None, include_inactive=True, sub_page_size=None, **kwargs)[source]#

Parameters:

subject_group_id (str) – UUID of subject group to filter by
subject_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
sub_page_size (int | None) – Optionally set a specific sub_page_size for this request, instead of using the client default
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.Relocations

get_event_types(include_inactive=False, api_version='both', **addl_kwargs)[source]#

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”

Return type:

pd.DataFrame

Parameters:

include_inactive (bool)
api_version (ApiVersionSelection)

get_choices_from_v2_event_type(event_type, choice_field)[source]#

Retrieve choice options for a specific field from a v2 event type schema.

Parameters:

event_type (str) – The event type identifier.
choice_field (str) – The name of the choice field to extract options from.

Returns:

A dictionary mapping choice values (const) to their display titles.

Return type:

dict[str, str]

get_fields_from_event_type_schema(event_type)[source]#

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.

Parameters:: event_type (str) – The event type identifier.
Returns:: A dictionary mapping field names to their display titles.
Return type:: dict[str, str]

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

Parameters:

is_collection (bool | None) – true/false whether to filter on is_collection
updated_since (str | None) – date-string to limit on updated_at
event_ids (array[string]) – Event IDs, comma-separated
bbox (ecoscope.base.utils.BoundingBox | None) – bounding box including four coordinate values, comma-separated. Ex. bbox=-122.4,48.4,-122.95,49.0 (west, south, east, north).
sort_by (EventSortOptions | None) – Sort by (use ‘event_time’, ‘updated_at’, ‘created_at’, ‘serial_number’) with optional minus (‘-’) prefix to reverse order.
patrol_segment (str | None) – ID of patrol segment to filter on
state (list[StatusOptions] | None) – Comma-separated list of ‘scheduled’/’active’/’overdue’/’done’/’cancelled’
event_type (list[str] | None) – Comma-separated list of event type uuids
include_updates (bool) – Boolean value
include_details (bool) – Boolean value
include_notes (bool) – Boolean value
include_related_events (bool) – Boolean value
include_files (bool) – Boolean value
max_results (int | None)
oldest_update_date (str | None)
exclude_contained (bool | None)
event_category (str | None)
since (str | None)
until (str | None)
force_point_geometry (bool, default True) – If true, non point geometry (ie polys) will be converted to a single point via Shape.centroid
drop_null_geometry (bool, default True) – If true, events with no geometry will be removed from output
sub_page_size (int | None) – Optionally set a specific sub_page_size for this request, instead of using the client default
updated_size (str | None)

Returns:

events – GeoDataFrame of queried events

Return type:

gpd.GeoDataFrame

get_event_type_display_names_from_events(events_gdf, append_category_names='never')[source]#

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

Parameters:

ER (Event types that are present on events but missing from the)
to (event-type registry (e.g. deleted/orphan types still attached)
the (historical events) fall back to their raw event_type value as)
display
KeyError. (rather than raising)
events_gdf (geopandas.GeoDataFrame)
append_category_names ("always","duplicates", or "never", default "never")

Return type:

gpd.GeoDataFrame

get_patrol_types()[source]#

Return type:: pandas.DataFrame

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

Parameters:

since (str | None) – Lower time range
until (str | None) – Upper time range
patrol_type (str | list[str] | None) – A patrol type UUID or a list of UUIDs
patrol_type_value (str | list[str] | None) – A patrol type value or a list of patrol type values
status (list[StatusOptions] | None) – ‘scheduled’/’active’/’overdue’/’done’/’cancelled’ Accept a status string or a list of statuses
sub_page_size (int | None) – Optionally set a specific sub_page_size for this request, instead of using the client default
patrols_overlap_daterange (bool, default True) – If false, restricts patrols to only those that start within the bounds of the provided time range

Returns:

patrols – DataFrame of queried patrols

Return type:

pd.DataFrame

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

Parameters:

since (str | None) – Lower time range
until (str | None) – Upper time range
patrol_type (str | list[str] | None) – A patrol type UUID or a list of UUIDs
patrol_type_value (str | list[str] | None) – A patrol type value or a list of patrol type values
status (list[StatusOptions] | None) – ‘scheduled’/’active’/’overdue’/’done’/’cancelled’ Accept a status string or a list of statuses
force_point_geometry (bool, default True) – If true, non point geometry (ie polys) will be converted to a single point via Shape.centroid
drop_null_geometry (bool, default True) – If true, events with no geometry will be removed from output
sub_page_size (int | None) – Optionally set a specific sub_page_size for this request, instead of using the client default
patrols_overlap_daterange (bool, default True) – If false, restricts patrols to only those that start within the bounds of the provided time range
event_type (list[str] | None)

Returns:

events – 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 (str) – Patrol UUID.
kwargs – Additional parameters to pass to _get.

Returns:

dataframe

Return type:

Dataframe of patrols.

get_patrol_segments()[source]#

Return type:: pandas.DataFrame

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

Download observations for patrols with provided filters.

Parameters:

since (str | None) – Lower time range
until (str | None) – Upper time range
patrol_type (str | list[str] | None) – A patrol type UUID or a list of UUIDs
patrol_type_value (str | list[str] | None) – A patrol type value or a list of patrol type values
status (list[StatusOptions] | None) – ‘scheduled’/’active’/’overdue’/’done’/’cancelled’ Accept a status string or a list of statuses
include_patrol_details (bool, optional) – Whether to merge patrol details into dataframe
sub_page_size (int | None) – Optionally set a specific sub_page_size for this request, instead of using the client default
patrols_overlap_daterange (bool, default True) – If false, restricts patrols to only those that start within the bounds of the provided time range
kwargs – Additional parameters to pass to get_subject_observations.

Returns:

relocations

Return type:

ecoscope.Relocations

get_patrol_observations(patrols_df, include_patrol_details=False, sub_page_size=None, **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
sub_page_size (int | None) – Optionally set a specific sub_page_size for this request, instead of using the client default
kwargs – Additional parameters to pass to get_subject_observations.

Returns:

relocations

Return type:

ecoscope.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]#

Parameters:

patrol_segment_id (str | None)
include_details (bool)
include_files (bool)
include_related_events (bool)
include_notes (bool)

Return type:

pandas.DataFrame

get_spatial_features_group(spatial_features_group_name=None, spatial_features_group_id=None, with_group_data=False, **addl_kwargs)[source]#

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

Parameters:

spatial_features_group_id (str | None) – Spatial Features Group UUID.
with_group_data (bool) – Whether or not to return group data
kwargs – Additional parameters to pass to _get.
spatial_features_group_name (str | None)

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

Return type:

geopandas.GeoDataFrame | dict[str, str | geopandas.GeoDataFrame]

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

Download spatial feature for a given spatial feature id.

Parameters:

spatial_feature_id (str | None) – 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=None, **kwargs)[source]#

Parameters:

source_type (str)
manufacturer_id (str)
model_name (str)
provider (str)
additional (Dict | None)

Return type:

pd.DataFrame

post_sourceproviders(provider_key, display_name, additional=None, **kwargs)[source]#

Parameters:

provider_key (str)
display_name (str)
additional (Dict | None)

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 | None)

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 | None)
tracked_subject_id (str | None)
scheduled_start (str | None)
scheduled_end (str | None)
start_time (str | None)
end_time (str | None)
start_location (Tuple[float, float] | None)
end_location (Tuple[float, float] | None)

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)
-------

ecoscope.io.earthranger#

Module Contents#

This Page