ecoscope.io

Submodules

• ecoscope.io.earthranger
• ecoscope.io.eetools
• ecoscope.io.raster
• ecoscope.io.utils

Package Contents

class ecoscope.io.EarthRangerIO(**kwargs)

Bases: ConcurrentDasClient

Extends ConcurrentDasClient with Ecoscope-specific configuration.

static _to_gdf(df)

static _normalize_column(df, col)

static _clean_kwargs(addl_kwargs={}, **kwargs)

get_subjectsources(subjects=None, sources=None, **addl_kwargs)

Parameters

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

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

Returns

subjectsources – DataFrame of queried subjectssources

Return type

pd.DataFrame

get_subjects(include_inactive=None, tracks_since=None, tracks_until=None, bbox=None, subject_group=None, name=None, updated_since=None, render_last_location=None, tracks=None, id=None, updated_until=None, group_name=None, **addl_kwargs)

Parameters

• include_inactive – Include inactive subjects in list.

• tracks_since – Include tracks since this timestamp

• tracks_until – Include tracks up through this timestamp

• 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 (UUID) – Find subjects with the given name.

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

• render_last_location – Indicate whether to render each subject’s last location.

• tracks – Indicate whether to render each subject’s recent tracks.

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

• updated_until –

• group_name –

Returns

subjects – DataFrame of queried subjects

Return type

pd.DataFrame

get_patrols(filter=None, status=None, **addl_kwargs)

Parameters

• filter – example: {“date_range”:{“lower”:”2020-09-16T00:00:00.000Z”}} date_range patrols_overlap_daterange text patrol_type tracked_by

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

Returns

patrols – DataFrame of queried patrols

Return type

pd.DataFrame

get_users()

Get all users

Returns

users

Return type

pd.DataFrame

get_sources(manufacturer_id=None, provider_key=None, provider=None, id=None, **addl_kwargs)

Parameters

• manufacturer_id –

• provider_key –

• provider –

• id –

Returns

sources – DataFrame of queried sources

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)

Return observations matching queries. If subject_id, source_id, or subjectsource_id is specified, the index is set to the provided value.

Parameters

• subject_ids – filter to a single subject

• source_ids – filter to a single source

• subjectsource_ids – filter to a subjectsource_id, rather than source_id + time range

• since – get observations after this ISO8061 date, include timezone

• until – get observations up to this ISO8061 date, include timezone

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

• 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 – GeoDataFrame of queried observations

Return type

gpd.GeoDataFrame

get_source_observations(source_ids, include_source_details=False, relocations=True, **kwargs)

Get observations for each listed source and create a Relocations object.

Parameters

• source_ids (str or list[str]) – List of source UUIDs

• include_source_details (bool, optional) – Whether to merge source info into dataframe

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

Get observations for each listed subject and create a Relocations object.

Parameters

• subject_ids (str or list[str]) – List of subject UUIDs

• include_source_details (bool, optional) – Whether to merge source info into dataframe

• include_subject_details (bool, optional) – Whether to merge subject info into dataframe

• include_subjectsource_details (bool, optional) – Whether to merge subjectsource info into dataframe

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

Get observations for each listed subjectsource and create a Relocations object.

Parameters

• subjectsource_ids (str or list[str]) – List of subjectsource UUIDs

• include_source_details (bool, optional) – Whether to merge source info into dataframe

• 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_events(is_collection=None, updated_size=None, event_ids=None, bbox=None, include_updates=None, include_details=None, sort_by=None, patrol_segment=None, state=None, event_type=None, include_notes=None, include_related_events=None, include_files=None, max_results=None, oldest_update_date=None, exclude_contained=None, updated_since=None, event_category=None, filter=None, **addl_kwargs)

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

• include_updates – Boolean value

• include_details – Boolean value

• 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_notes – Boolean value

• include_related_events – Boolean value

• include_files – Boolean value

• max_results –

• oldest_update_date –

• exclude_contained –

• event_category –

• filter (json dict) – Can contain any of ‘event_filter_id’, ‘text’, ‘date_range’, ‘duration’, ‘state’, ‘priority’, ‘event_category’, ‘event_type’, ‘reported_by’, ‘create_date’, ‘update_date’

Returns

events – GeoDataFrame of queried events

Return type

gpd.GeoDataFrame

get_subjectgroup_observations(subject_group=None, group_name=None, include_inactive=True, **kwargs)

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_observations_for_patrols(patrols_df, **kwargs)

Download observations for provided patrols_df.

Parameters

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

• kwargs – Additional parameters to pass to get_subject_observations.

Returns

relocations

Return type

ecoscope.base.Relocations

post_observations(observations, source_id_col='source', recorded_at_col='recorded_at')

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_subjectsource(subject_id, source_id, lower_bound_assignend_range, upper_bound_assigned_range, additional=None)

Parameters

• subject_id (str) –

• source_id (str) –

• lower_bound_assignend_range (datetime.datetime) –

• upper_bound_assigned_range (datetime.datetime) –

• additional (Dict) –

Return type

pd.DataFrame

static _dataframe_to_dict(events)

post_event(events)

Parameters

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

Returns

New events created in EarthRanger.

Return type

pd.DataFrame

patch_event(event_id, events)

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

ecoscope.io.download_file(url, path, overwrite_existing=False, chunk_size=1024, **request_kwargs)