ecoscope.io.earthranger#
Module Contents#
- 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.
- sub_page_size = 4000#
- tcp_limit = 5#
- 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_id=None, name=None, updated_since=None, tracks=None, id=None, updated_until=None, subject_group_name=None, max_ids_per_request=50, **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
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
- 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:
- 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, 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 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:
- 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:
- get_subjectgroup_observations(subject_group_id=None, subject_group_name=None, include_inactive=True, **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
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:
- 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_patrols(since=None, until=None, patrol_type=None, patrol_type_value=None, status=None, **addl_kwargs)[source]#
- Parameters:
since – Lower time range
until – Upper time range
patrol_type – A patrol type UUID or a list of UUIDs
patrol_type_value – A patrol type value or a list of patrol type values
status – ‘scheduled’/’active’/’overdue’/’done’/’cancelled’ Accept a status string or a list of statuses
- 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, **addl_kwargs)[source]#
- Parameters:
since – Lower time range
until – Upper time range
patrol_type – A patrol type UUID or a list of UUIDs
patrol_type_value – A patrol type value or a list of patrol type values
status – ‘scheduled’/’active’/’overdue’/’done’/’cancelled’ Accept a status string or a list of statuses
- 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 – Patrol UUID.
kwargs – Additional parameters to pass to _get.
- Returns:
dataframe
- Return type:
Dataframe of patrols.
- get_patrol_observations_with_patrol_filter(since=None, until=None, patrol_type=None, patrol_type_value=None, status=None, include_patrol_details=False, **kwargs)[source]#
Download observations for patrols with provided filters.
- Parameters:
since – Lower time range
until – Upper time range
patrol_type – A patrol type UUID or a list of UUIDs
patrol_type_value – A patrol type value or a list of patrol type values
status – ‘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
kwargs – Additional parameters to pass to get_subject_observations.
- Returns:
relocations
- Return type:
- 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:
- 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_sourceproviders(provider_key, display_name, additional={}, **kwargs)[source]#
- Parameters:
provider_key (str)
display_name (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_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