spec.yaml

id: subject_tracking
requirements:
  - name: ecoscope-workflows-core
    version: 0.1.5
    channel: https://repo.prefix.dev/ecoscope-workflows/
  - name: ecoscope-workflows-ext-ecoscope
    version: 0.1.5
    channel: https://repo.prefix.dev/ecoscope-workflows/
rjsf-overrides:
  properties:
    subject_obs.properties.subject_group_name.ecoscope:subject_group_name: properties.er_client_name.properties.data_source.properties.name
  $defs:
    ValueGrouper.oneOf:
      - const: subject_name
        title: Subject Name
      - const: subject_subtype
        title: Subject Subtype
      - const: subject_sex
        title: Subject Sex
workflow:
  - name: Workflow Details
    id: workflow_details
    task: set_workflow_details
  - name: Data Source
    id: er_client_name
    task: set_er_connection
  - name: Time Range
    id: time_range
    task: set_time_range
    partial:
      time_format: '%d %b %Y %H:%M:%S %Z'
  - name: Get Subject Group Observations from EarthRanger
    id: subject_obs
    task: get_subjectgroup_observations
    partial:
      client: ${{ workflow.er_client_name.return }}
      time_range: ${{ workflow.time_range.return }}
      raise_on_empty: true
      include_details: false
  - name: Group Data
    id: groupers
    task: set_groupers
  - name: Transform Observations to Relocations
    id: subject_reloc
    task: process_relocations
    partial:
      observations: ${{ workflow.subject_obs.return }}
      relocs_columns:
        - groupby_col
        - fixtime
        - junk_status
        - geometry
        - extra__subject__name
        - extra__subject__subject_subtype
        - extra__subject__sex
      filter_point_coords:
        - x: 180.000000
          y: 90.000000
        - x: 0.000000
          y: 0.000000
        - x: 1.000000
          y: 1.000000
  - name: Apply Day/Night Labels to Relocations
    id: day_night_labels
    task: classify_is_night
    partial:
      relocations: ${{ workflow.subject_reloc.return }}
  - name: Transform Relocations to Trajectories
    id: subject_traj
    task: relocations_to_trajectory
    partial:
      relocations: ${{ workflow.day_night_labels.return }}
  - name: Add temporal index to Subject Trajectories
    id: traj_add_temporal_index
    task: add_temporal_index
    partial:
      df: ${{ workflow.subject_traj.return }}
      time_col: segment_start
      groupers: ${{ workflow.groupers.return }}
      cast_to_datetime: true
      format: mixed
  - name: Rename value grouper columns
    id: rename_grouper_columns
    task: map_columns
    partial:
      df: ${{ workflow.traj_add_temporal_index.return }}
      drop_columns: []
      retain_columns: []
      rename_columns:
        extra__name: subject_name
        extra__subject_subtype: subject_subtype
        extra__sex: subject_sex
  - name: Map Subject Sex Values
    id: map_subject_sex
    task: map_values
    partial:
      df: ${{ workflow.rename_grouper_columns.return }}
      column_name: subject_sex
      value_map:
        male: male
        female: female
      missing_values: replace
      replacement: unknown
  - name: Classify Trajectories By Speed
    id: classify_traj_speed
    task: apply_classification
    partial:
      df: ${{ workflow.map_subject_sex.return }}
      input_column_name: speed_kmhr
      output_column_name: speed_bins
      classification_options:
        scheme: equal_interval
        k: 6
      label_options:
        label_ranges: false
        label_decimals: 1
  - name: Split Subject Trajectories by Group
    id: split_subject_traj_groups
    task: split_groups
    partial:
      df: ${{ workflow.classify_traj_speed.return }}
      groupers: ${{ workflow.groupers.return }}
  - name: Base Maps
    id: base_map_defs
    task: set_base_maps
  - name: Sort Trajetories By Classification
    id: sort_traj_speed
    task: sort_values
    partial:
      column_name: speed_bins
      ascending: true
      na_position: last
    mapvalues:
      argnames: df
      argvalues: ${{ workflow.split_subject_traj_groups.return }}
  - name: Apply Color to Trajectories By Speed
    id: colormap_traj_speed
    task: apply_color_map
    partial:
      input_column_name: speed_bins
      output_column_name: speed_bins_colormap
      colormap:
        - '#1a9850'
        - '#91cf60'
        - '#d9ef8b'
        - '#fee08b'
        - '#fc8d59'
        - '#d73027'
    mapvalues:
      argnames: df
      argvalues: ${{ workflow.sort_traj_speed.return }}
  - name: Format Speedmap bins for legend
    id: speed_bin_legend_with_unit
    task: map_values_with_unit
    partial:
      input_column_name: speed_bins
      output_column_name: speed_bins_formatted
      original_unit: km/h
      new_unit: km/h
      decimal_places: 1
    mapvalues:
      argnames: df
      argvalues: ${{ workflow.colormap_traj_speed.return }}
  - name: Format speed values for display
    id: speed_val_with_unit
    task: map_values_with_unit
    partial:
      input_column_name: speed_kmhr
      output_column_name: speed_kmhr
      original_unit: km/h
      new_unit: km/h
      decimal_places: 1
    mapvalues:
      argnames: df
      argvalues: ${{ workflow.speed_bin_legend_with_unit.return }}
  - name: Rename columns for map tooltip display
    id: rename_speed_display_columns
    task: map_columns
    partial:
      drop_columns: []
      retain_columns: []
      rename_columns:
        segment_start: Start
        timespan_seconds: Duration (s)
        speed_kmhr: Speed (kph)
        extra__is_night: Nighttime
        subject_name: Subject Name
        subject_sex: Subject Sex
    mapvalues:
      argnames: df
      argvalues: ${{ workflow.speed_val_with_unit.return }}
  - name: Create map layer for each trajectory group
    id: traj_map_layers
    task: create_polyline_layer
    partial:
      layer_style:
        color_column: speed_bins_colormap
      legend:
        label_column: speed_bins_formatted
        color_column: speed_bins_colormap
      tooltip_columns:
        - Start
        - Duration (s)
        - Speed (kph)
        - Nighttime
        - Subject Name
        - Subject Sex
    mapvalues:
      argnames: geodataframe
      argvalues: ${{ workflow.rename_speed_display_columns.return }}
  - name: Draw Ecomaps for each trajectory group
    id: traj_ecomap
    task: draw_ecomap
    partial:
      tile_layers: ${{ workflow.base_map_defs.return }}
      north_arrow_style:
        placement: top-left
      legend_style:
        placement: bottom-right
      static: false
      title: null
      max_zoom: 20
    mapvalues:
      argnames: geo_layers
      argvalues: ${{ workflow.traj_map_layers.return }}
  - name: Persist ecomap as Text
    id: ecomap_html_urls
    task: persist_text
    partial:
      root_path: ${{ env.ECOSCOPE_WORKFLOWS_RESULTS }}
    mapvalues:
      argnames: text
      argvalues: ${{ workflow.traj_ecomap.return }}
  - name: Create Map Widgets for Trajectories
    id: traj_map_widgets_single_views
    task: create_map_widget_single_view
    partial:
      title: Subject Group Trajectory Map
    map:
      argnames:
        - view
        - data
      argvalues: ${{ workflow.ecomap_html_urls.return }}
  - name: Merge EcoMap Widget Views
    id: traj_grouped_map_widget
    task: merge_widget_views
    partial:
      widgets: ${{ workflow.traj_map_widgets_single_views.return }}
  - name: Sort Trajetories By Night/Day Classification
    id: sort_traj_night_day
    task: sort_values
    partial:
      column_name: extra__is_night
      ascending: false
      na_position: last
    mapvalues:
      argnames: df
      argvalues: ${{ workflow.split_subject_traj_groups.return }}
  - name: Apply Color to Trajectories By Day/Night
    id: colormap_traj_night
    task: apply_color_map
    partial:
      colormap:
        - '#292965'
        - '#e7a553'
      input_column_name: extra__is_night
      output_column_name: is_night_colors
    mapvalues:
      argnames: df
      argvalues: ${{ workflow.sort_traj_night_day.return }}
  - name: Rename columns for map tooltip display
    id: rename_nightday_display_columns
    task: map_columns
    partial:
      drop_columns: []
      retain_columns: []
      rename_columns:
        subject_name: Subject Name
        subject_subtype: Subject Sex
        extra__is_night: Nighttime
    mapvalues:
      argnames: df
      argvalues: ${{ workflow.colormap_traj_night.return }}
  - name: Create map layer for each trajectory group
    id: traj_map_night_layers
    task: create_polyline_layer
    partial:
      layer_style:
        color_column: is_night_colors
      legend:
        labels:
          - Night
          - Day
        colors:
          - '#292965'
          - '#e7a553'
      tooltip_columns:
        - Subject Name
        - Subject Sex
        - Nighttime
    mapvalues:
      argnames: geodataframe
      argvalues: ${{ workflow.rename_nightday_display_columns.return }}
  - name: Draw Ecomaps for each trajectory group
    id: traj_nightday_ecomap
    task: draw_ecomap
    partial:
      tile_layers: ${{ workflow.base_map_defs.return }}
      north_arrow_style:
        placement: top-left
      legend_style:
        placement: bottom-right
      static: false
      title: null
      max_zoom: 20
    mapvalues:
      argnames: geo_layers
      argvalues: ${{ workflow.traj_map_night_layers.return }}
  - name: Persist ecomap as Text
    id: ecomap_nightday_html_urls
    task: persist_text
    partial:
      root_path: ${{ env.ECOSCOPE_WORKFLOWS_RESULTS }}
    mapvalues:
      argnames: text
      argvalues: ${{ workflow.traj_nightday_ecomap.return }}
  - name: Create Map Widgets for Trajectories
    id: traj_map_nightday_widgets_sv
    task: create_map_widget_single_view
    partial:
      title: Subject Group Night/Day Map
    map:
      argnames:
        - view
        - data
      argvalues: ${{ workflow.ecomap_nightday_html_urls.return }}
  - name: Merge EcoMap Widget Views
    id: traj_nightday_grouped_map_widget
    task: merge_widget_views
    partial:
      widgets: ${{ workflow.traj_map_nightday_widgets_sv.return }}
  - name: Calculate Mean Speed Per Group
    id: mean_speed
    task: dataframe_column_mean
    partial:
      column_name: speed_kmhr
    mapvalues:
      argnames: df
      argvalues: ${{ workflow.split_subject_traj_groups.return }}
  - name: Convert Average Speed units
    id: average_speed_converted
    task: with_unit
    partial:
      original_unit: km/h
      new_unit: km/h
    mapvalues:
      argnames: value
      argvalues: ${{ workflow.mean_speed.return }}
  - name: Create Single Value Widgets for Mean Speed Per Group
    id: mean_speed_sv_widgets
    task: create_single_value_widget_single_view
    partial:
      title: Mean Speed
      decimal_places: 1
    map:
      argnames:
        - view
        - data
      argvalues: ${{ workflow.average_speed_converted.return }}
  - name: Merge per group Mean Speed SV widgets
    id: mean_speed_grouped_sv_widget
    task: merge_widget_views
    partial:
      widgets: ${{ workflow.mean_speed_sv_widgets.return }}
  - name: Calculate Max Speed Per Group
    id: max_speed
    task: dataframe_column_max
    partial:
      column_name: speed_kmhr
    mapvalues:
      argnames: df
      argvalues: ${{ workflow.split_subject_traj_groups.return }}
  - name: Convert Max Speed units
    id: max_speed_converted
    task: with_unit
    partial:
      original_unit: km/h
      new_unit: km/h
    mapvalues:
      argnames: value
      argvalues: ${{ workflow.max_speed.return }}
  - name: Create Single Value Widgets for Max Speed Per Group
    id: max_speed_sv_widgets
    task: create_single_value_widget_single_view
    partial:
      title: Max Speed
      decimal_places: 1
    map:
      argnames:
        - view
        - data
      argvalues: ${{ workflow.max_speed_converted.return }}
  - name: Merge per group Max Speed SV widgets
    id: max_speed_grouped_sv_widget
    task: merge_widget_views
    partial:
      widgets: ${{ workflow.max_speed_sv_widgets.return }}
  - name: Calculate Number of Locations Per Group
    id: num_location
    task: dataframe_count
    mapvalues:
      argnames: df
      argvalues: ${{ workflow.split_subject_traj_groups.return }}
  - name: Create Single Value Widgets for Number of Location Per Group
    id: num_location_sv_widgets
    task: create_single_value_widget_single_view
    partial:
      title: Number of Locations
      decimal_places: 1
    map:
      argnames:
        - view
        - data
      argvalues: ${{ workflow.num_location.return }}
  - name: Merge per group Number of Locations SV widgets
    id: num_location_grouped_sv_widget
    task: merge_widget_views
    partial:
      widgets: ${{ workflow.num_location_sv_widgets.return }}
  - name: Calculate Day/Night Ratio Per Group
    id: nightday_ratio
    task: get_night_day_ratio
    mapvalues:
      argnames: df
      argvalues: ${{ workflow.split_subject_traj_groups.return }}
  - name: Create Single Value Widgets for Day/Night Ratio Per Group
    id: nightday_ratio_sv_widgets
    task: create_single_value_widget_single_view
    partial:
      title: Night/Day Ratio
      decimal_places: 1
    map:
      argnames:
        - view
        - data
      argvalues: ${{ workflow.nightday_ratio.return }}
  - name: Merge per group Day/Night Ratio SV widgets
    id: nightday_ratio_grouped_sv_widget
    task: merge_widget_views
    partial:
      widgets: ${{ workflow.nightday_ratio_sv_widgets.return }}
  - name: Calculate Total Distance Per Group
    id: total_distance
    task: dataframe_column_sum
    partial:
      column_name: dist_meters
    mapvalues:
      argnames: df
      argvalues: ${{ workflow.split_subject_traj_groups.return }}
  - name: Convert total distance units
    id: total_dist_converted
    task: with_unit
    partial:
      original_unit: m
      new_unit: km
    mapvalues:
      argnames: value
      argvalues: ${{ workflow.total_distance.return }}
  - name: Create Single Value Widgets for Total Distance Per Group
    id: total_distance_sv_widgets
    task: create_single_value_widget_single_view
    partial:
      title: Total Distance
      decimal_places: 1
    map:
      argnames:
        - view
        - data
      argvalues: ${{ workflow.total_dist_converted.return }}
  - name: Merge per group Total Distance SV widgets
    id: total_dist_grouped_sv_widget
    task: merge_widget_views
    partial:
      widgets: ${{ workflow.total_distance_sv_widgets.return }}
  - name: Calculate Total Time Per Group
    id: total_time
    task: dataframe_column_sum
    partial:
      column_name: timespan_seconds
    mapvalues:
      argnames: df
      argvalues: ${{ workflow.split_subject_traj_groups.return }}
  - name: Convert total time units
    id: total_time_converted
    task: with_unit
    partial:
      original_unit: s
      new_unit: h
    mapvalues:
      argnames: value
      argvalues: ${{ workflow.total_time.return }}
  - name: Create Single Value Widgets for Total Distance Per Group
    id: total_time_sv_widgets
    task: create_single_value_widget_single_view
    partial:
      title: Total Time
      decimal_places: 1
    map:
      argnames:
        - view
        - data
      argvalues: ${{ workflow.total_time_converted.return }}
  - name: Merge per group Total Distance SV widgets
    id: total_time_grouped_sv_widget
    task: merge_widget_views
    partial:
      widgets: ${{ workflow.total_time_sv_widgets.return }}
  - name: Calculate Time Density from Trajectory
    id: td
    task: calculate_time_density
    partial:
      crs: ESRI:53042
      percentiles:
        - 50.000000
        - 60.000000
        - 70.000000
        - 80.000000
        - 90.000000
        - 95.000000
        - 99.999000
      nodata_value: nan
      band_count: 1
    mapvalues:
      argnames: trajectory_gdf
      argvalues: ${{ workflow.split_subject_traj_groups.return }}
  - name: Time Density Colormap
    id: td_colormap
    task: apply_color_map
    partial:
      input_column_name: percentile
      colormap: RdYlGn
      output_column_name: percentile_colormap
    mapvalues:
      argnames: df
      argvalues: ${{ workflow.td.return }}
  - name: Create map layer from Time Density
    id: td_map_layer
    task: create_polygon_layer
    partial:
      layer_style:
        fill_color_column: percentile_colormap
        opacity: 0.700000
        get_line_width: 0
      legend:
        label_column: percentile
        color_column: percentile_colormap
      tooltip_columns:
        - percentile
    mapvalues:
      argnames: geodataframe
      argvalues: ${{ workflow.td_colormap.return }}
  - name: Draw Ecomap from Time Density
    id: td_ecomap
    task: draw_ecomap
    partial:
      tile_layers: ${{ workflow.base_map_defs.return }}
      north_arrow_style:
        placement: top-left
      legend_style:
        placement: bottom-right
      static: false
      title: null
      max_zoom: 20
    mapvalues:
      argnames: geo_layers
      argvalues: ${{ workflow.td_map_layer.return }}
  - name: Persist Ecomap as Text
    id: td_ecomap_html_url
    task: persist_text
    partial:
      root_path: ${{ env.ECOSCOPE_WORKFLOWS_RESULTS }}
    mapvalues:
      argnames: text
      argvalues: ${{ workflow.td_ecomap.return }}
  - name: Create Time Density Map Widget
    id: td_map_widget
    task: create_map_widget_single_view
    partial:
      title: Home Range Map
    map:
      argnames:
        - view
        - data
      argvalues: ${{ workflow.td_ecomap_html_url.return }}
  - name: Merge Time Density Map Widget Views
    id: td_grouped_map_widget
    task: merge_widget_views
    partial:
      widgets: ${{ workflow.td_map_widget.return }}
  - name: Draw NSD Scatter Chart
    id: nsd_chart
    task: draw_ecoplot
    partial:
      group_by: subject_name
      ecoplot_configs:
        - x_col: segment_start
          y_col: nsd
          plot_style:
            xperiodalignment: null
          color_column: null
      tickformat: '%b-%Y'
    mapvalues:
      argnames: dataframe
      argvalues: ${{ workflow.split_subject_traj_groups.return }}
  - name: Persist NSD Scatter Chart as Text
    id: nsd_chart_html_url
    task: persist_text
    partial:
      root_path: ${{ env.ECOSCOPE_WORKFLOWS_RESULTS }}
    mapvalues:
      argnames: text
      argvalues: ${{ workflow.nsd_chart.return }}
  - name: Create NSD Plot Widget
    id: nsd_chart_widget
    task: create_plot_widget_single_view
    partial:
      title: Net Square Displacement
    map:
      argnames:
        - view
        - data
      argvalues: ${{ workflow.nsd_chart_html_url.return }}
  - name: Merge NSD Widget Views
    id: grouped_nsd_chart_widget_merge
    task: merge_widget_views
    partial:
      widgets: ${{ workflow.nsd_chart_widget.return }}
  - name: Create Dashboard with Subject Tracking Widgets
    id: subject_tracking_dashboard
    task: gather_dashboard
    partial:
      details: ${{ workflow.workflow_details.return}}
      widgets:
        - ${{ workflow.traj_grouped_map_widget.return }}
        - ${{ workflow.mean_speed_grouped_sv_widget.return }}
        - ${{ workflow.max_speed_grouped_sv_widget.return }}
        - ${{ workflow.num_location_grouped_sv_widget.return }}
        - ${{ workflow.nightday_ratio_grouped_sv_widget.return }}
        - ${{ workflow.total_dist_grouped_sv_widget.return }}
        - ${{ workflow.total_time_grouped_sv_widget.return }}
        - ${{ workflow.td_grouped_map_widget.return }}
        - ${{ workflow.traj_nightday_grouped_map_widget.return }}
        - ${{ workflow.grouped_nsd_chart_widget_merge.return }}
      groupers: ${{ workflow.groupers.return }}
      time_range: ${{ workflow.time_range.return}}