Nasty.AST.Event (Nasty v0.3.0)

Represents an event extracted from text.

Events capture actions, occurrences, or states with their participants, temporal information, and location.

Examples

%Event{
  trigger: %Token{text: "acquired", lemma: "acquire"},
  type: :business_acquisition,
  participants: %{
    agent: %Entity{text: "Google", type: :org},
    patient: %Entity{text: "YouTube", type: :org},
    value: "1.65 billion"
  },
  time: "October 2006",
  confidence: 0.85,
  language: :en
}

Summary

Types

event_type()

participant_role()

t()

Functions

add_participant(event, role, participant)

Adds a participant to an event.

filter_by_confidence(events, min_confidence)

Filters events by minimum confidence threshold.

filter_by_participant(events, role)

Filters events that have a specific participant role.

filter_by_type(events, type)

Filters events by type.

get_participant(event, role)

Gets a participant by role.

new(type, trigger, language, opts \\ [])

Creates a new event.

sort_by_confidence(events)

Sorts events by confidence (descending).

to_string(event)

Converts an event to a human-readable string.

trigger_text(event)

Gets the text representation of the trigger.

Types

event_type()

@type event_type() ::
  :business_acquisition
  | :business_merger
  | :product_launch
  | :employment_start
  | :employment_end
  | :company_founding
  | :meeting
  | :announcement
  | :election
  | :birth
  | :death
  | :movement
  | :transaction
  | :communication
  | atom()

participant_role()

@type participant_role() ::
  :agent | :patient | :theme | :recipient | :beneficiary | :instrument | atom()

t()

@type t() :: %Nasty.AST.Event{
  confidence: float(),
  language: Nasty.AST.Node.language(),
  location: Nasty.AST.Semantic.Entity.t() | String.t() | nil,
  metadata: map(),
  participants: %{
    required(participant_role()) => Nasty.AST.Semantic.Entity.t() | String.t()
  },
  span: Nasty.AST.Node.span() | nil,
  time: String.t() | nil,
  trigger: Nasty.AST.Token.t() | String.t(),
  type: event_type()
}

Functions

add_participant(event, role, participant)

@spec add_participant(
  t(),
  participant_role(),
  Nasty.AST.Semantic.Entity.t() | String.t()
) :: t()

Adds a participant to an event.

Examples

iex> event = Event.new(:business_acquisition, trigger, :en)
iex> Event.add_participant(event, :agent, buyer_entity)
%Event{participants: %{agent: buyer_entity}}

filter_by_confidence(events, min_confidence)

@spec filter_by_confidence([t()], float()) :: [t()]

Filters events by minimum confidence threshold.

Examples

iex> Event.filter_by_confidence(events, 0.7)
[%Event{confidence: 0.9}, %Event{confidence: 0.8}]

filter_by_participant(events, role)

@spec filter_by_participant([t()], participant_role()) :: [t()]

Filters events that have a specific participant role.

Examples

iex> Event.filter_by_participant(events, :agent)
[%Event{participants: %{agent: ...}}, ...]

filter_by_type(events, type)

@spec filter_by_type([t()], event_type()) :: [t()]

Filters events by type.

Examples

iex> Event.filter_by_type(events, :business_acquisition)
[%Event{type: :business_acquisition}, ...]

get_participant(event, role)

@spec get_participant(t(), participant_role()) ::
  Nasty.AST.Semantic.Entity.t() | String.t() | nil

Gets a participant by role.

Examples

iex> Event.get_participant(event, :agent)
%Entity{text: "Google", type: :org}

iex> Event.get_participant(event, :missing_role)
nil

new(type, trigger, language, opts \\ [])

@spec new(
  event_type(),
  Nasty.AST.Token.t() | String.t(),
  Nasty.AST.Node.language(),
  keyword()
) :: t()

Creates a new event.

Examples

iex> Event.new(:business_acquisition, trigger, :en)
%Event{type: :business_acquisition, trigger: trigger, language: :en}

iex> Event.new(:business_acquisition, trigger, :en,
...>   participants: %{agent: buyer, patient: target},
...>   confidence: 0.8
...> )
%Event{type: :business_acquisition, participants: %{agent: ..., patient: ...}, ...}

sort_by_confidence(events)

@spec sort_by_confidence([t()]) :: [t()]

Sorts events by confidence (descending).

Examples

iex> events = [%Event{confidence: 0.5}, %Event{confidence: 0.9}]
iex> Event.sort_by_confidence(events)
[%Event{confidence: 0.9}, %Event{confidence: 0.5}]

to_string(event)

@spec to_string(t()) :: String.t()

Converts an event to a human-readable string.

Examples

iex> Event.to_string(event)
"business_acquisition: Google acquired YouTube (confidence: 0.85)"

trigger_text(event)

@spec trigger_text(t()) :: String.t()

Gets the text representation of the trigger.