Module: NexosisApi::Client::Sessions

Included in:
NexosisApi::Client
Defined in:
lib/nexosis_api/client/sessions.rb

Overview

Session-based API operations

See Also:

Instance Method Summary collapse

Instance Method Details

#create_forecast_session(dataset_name, start_date, end_date, target_column = nil, result_interval = NexosisApi::TimeInterval::DAY, column_metadata = nil) ⇒ NexosisApi::SessionResponse

Note:

The time interval selected must be greater than or equal to the finest granularity of the data provided. For instance if your data includes many recoreds per hour, then you could request hour, day, or any other result interval. However, if your data includes only a few records per day or fewer, then a request for an hourly result interval will produce poor results.

Initiate a new forecast session based on a named dataset.

Parameters:

  • dataset_name (String) —

    The name of the saved data set that has the data to forecast on.

  • start_date (DateTime) —

    The starting date of the forecast period. Can be ISO 8601 string.

  • end_date (DateTime) —

    The ending date of the forecast period. Can be ISO 8601 string.

  • target_column (String) (defaults to: nil) —

    The name of the column for which you want predictions. Nil if defined in dataset.

  • result_interval (NexosisApi::TimeInterval) (defaults to: NexosisApi::TimeInterval::DAY) —

    (optional) - The date/time interval (e.g. Day, Hour) at which predictions should be generated. So, if Hour is specified for this parameter you will get a Result record for each hour between startDate and endDate. If unspecified, we’ll generate predictions at a Day interval.

  • column_metadata (Array of NexosisApi::DatasetColumn) (defaults to: nil) —

    (optional) - specification for how to handle columns if different from existing metadata on dataset

Returns:


89
90
91
 
# File 'lib/nexosis_api/client/sessions.rb', line 89

def create_forecast_session(dataset_name, start_date, end_date, target_column = nil, result_interval = NexosisApi::TimeInterval::DAY, column_metadata = nil)
	create_session(dataset_name, start_date, end_date, target_column, false, nil, "forecast", result_interval, column_metadata)
end

#create_impact_session(dataset_name, start_date, end_date, event_name, target_column = nil, result_interval = NexosisApi::TimeInterval::DAY, column_metadata = nil) ⇒ NexosisApi::SessionResponse

Analyze impact for an event with data already saved to the API.

Parameters:

  • dataset_name (String) —

    The name of the saved data set that has the data to forecast on.

  • start_date (DateTime) —

    The starting date of the impactful event. Can be ISO 8601 string.

  • end_date (DateTime) —

    The ending date of the impactful event. Can be ISO 8601 string.

  • event_name (String) —

    The name of the event.

  • target_column (String) (defaults to: nil) —

    The name of the column for which you want predictions. Nil if defined in datatset.

  • result_interval (NexosisApi::TimeInterval) (defaults to: NexosisApi::TimeInterval::DAY) —

    (optional) - The date/time interval (e.g. Day, Hour) at which predictions should be generated. So, if Hour is specified for this parameter you will get a Result record for each hour between startDate and endDate. If unspecified, we’ll generate predictions at a Day interval.

  • column_metadata (Array of NexosisApi::DatasetColumn) (defaults to: nil) —

    (optional) - specification for how to handle columns if different from existing metadata on dataset

Returns:


115
116
117
 
# File 'lib/nexosis_api/client/sessions.rb', line 115

def create_impact_session(dataset_name, start_date, end_date, event_name, target_column = nil, result_interval = NexosisApi::TimeInterval::DAY, column_metadata = nil)
    create_session(dataset_name, start_date, end_date, target_column, false, event_name, "impact", result_interval, column_metadata)
end

#estimate_forecast_session(dataset_name, start_date, end_date, target_column = nil, result_interval = NexosisApi::TimeInterval::DAY) ⇒ NexosisApi::SessionResponse

Estimate the cost of a forecast from data already saved to the API.

Parameters:

  • dataset_name (String) —

    The name of the saved data set that has the data to forecast on.

  • start_date (DateTime) —

    The starting date of the forecast period. Can be ISO 8601 string.

  • end_date (DateTime) —

    The ending date of the forecast period. Can be ISO 8601 string.

  • target_column (String) (defaults to: nil) —

    The name of the column for which you want predictions. Nil if defined in dataset.

  • result_interval (NexosisApi::TimeInterval) (defaults to: NexosisApi::TimeInterval::DAY) —

    (optional) - The date/time interval (e.g. Day, Hour) at which predictions should be generated. So, if Hour is specified for this parameter you will get a Result record for each hour between startDate and endDate. If unspecified, we’ll generate predictions at a Day interval.

Returns:


101
102
103
 
# File 'lib/nexosis_api/client/sessions.rb', line 101

def estimate_forecast_session(dataset_name, start_date, end_date, target_column = nil, result_interval = NexosisApi::TimeInterval::DAY)
    create_session(dataset_name, start_date, end_date, target_column, true, nil, "forecast", result_interval)
end

#estimate_impact_session(dataset_name, start_date, end_date, event_name, target_column = nil, result_interval = NexosisApi::TimeInterval::DAY) ⇒ NexosisApi::SessionResponse

Estimate the cost of impact analysis for an event with data already saved to the API.

Parameters:

  • dataset_name (String) —

    The name of the saved data set that has the data to forecast on.

  • start_date (DateTime) —

    The starting date of the impactful event. Can be ISO 8601 string.

  • end_date (DateTime) —

    The ending date of the impactful event. Can be ISO 8601 string.

  • event_name (String) —

    The name of the event.

  • target_column (String) (defaults to: nil) —

    The name of the column for which you want predictions. Nil if defined in dataset.

  • result_interval (NexosisApi::TimeInterval) (defaults to: NexosisApi::TimeInterval::DAY) —

    (optional) - The date/time interval (e.g. Day, Hour) at which predictions should be generated. So, if Hour is specified for this parameter you will get a Result record for each hour between startDate and endDate. If unspecified, we’ll generate predictions at a Day interval.

Returns:


128
129
130
 
# File 'lib/nexosis_api/client/sessions.rb', line 128

def estimate_impact_session(dataset_name, start_date, end_date, event_name, target_column = nil, result_interval = NexosisApi::TimeInterval::DAY)
    create_session(dataset_name, start_date, end_date, target_column, true, event_name, "impact", result_interval)
end

#get_session(session_id) ⇒ NexosisApi::Session

Get a specific session by id.

Parameters:

  • session_id (String) —

    the Guid string returned in a previous session request

Returns:


161
162
163
164
165
166
167
168
169
 
# File 'lib/nexosis_api/client/sessions.rb', line 161

def get_session(session_id)
    session_url = "/sessions/#{session_id}"
    response = self.class.get(session_url, @options)
    if(response.success?)
        NexosisApi::Session.new(response.parsed_response)
    else
        raise HttpException.new("There was a problem getting the session: #{response.code}.", "getting session #{session_id}" ,response)
			    end
end

#get_session_results(session_id, as_csv = false) ⇒ NexosisApi::SessionResult

Get the results of the session.

Parameters:

  • session_id (String) —

    the Guid string returned in a previous session request

  • as_csv (Boolean) (defaults to: false) —

    indicate whether results should be returned in csv format

Returns:


137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
 
# File 'lib/nexosis_api/client/sessions.rb', line 137

def get_session_results(session_id, as_csv = false)
  		session_result_url = "/sessions/#{session_id}/results"
		
	if as_csv
 	@headers["Accept"] = "text/csv"
				end
 response = self.class.get(session_result_url, @options)
 @headers.delete("Accept")

 if(response.success?)
  if(as_csv)
   response.body
  else
   NexosisApi::SessionResult.new(response.parsed_response)
  end
          else
              raise HttpException.new("There was a problem getting the session: #{response.code}.", "get results for session #{session_id}" ,response)
 end
end

#list_sessions(query_options = {}, page = 0, pageSize = 50) ⇒ Array of NexosisApi::SessionResponse

Note:

query parameters hash members are dataset_name, event_name, requested_before_date, and requested_after_date. After and before dates refer to the session requested date.

List sessions previously submitted

Examples:

query for just one dataset

sessions = NexosisApi.client.list_sessions :dataset_name => 'MyDataset'

Parameters:

  • query_options (Hash) (defaults to: {}) —

    optionally provide query parameters to limit the search of sessions.

  • page (Integer) (defaults to: 0) —

    optionally provide a page number for paging. Defaults to 0 (first page).

  • pageSize (Integer) (defaults to: 50) —

    optionally provide a page size to limit the total number of results. Defaults to 50, max 1000

Returns:


21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
 
# File 'lib/nexosis_api/client/sessions.rb', line 21

def list_sessions(query_options = {}, page = 0, pageSize = 50)
	sessions_url = '/sessions'
	query = { 
		"dataSetName" => query_options[:dataset_name],
		"eventName" => query_options[:event_name],
		"requestedAfterDate" => query_options[:requested_after_date],
		"requestedBeforeDate" => query_options[:requested_before_date],
		"type" => query_options[:type],
		"page" => page,
		"pageSize" => pageSize
	}
	response = self.class.get(sessions_url, :headers => @headers, :query => query)
	if(response.success?)
		all_responses = []
		response.parsed_response["items"].each do |session_hash|
			response_hash = {"session" => session_hash}.merge(response.headers)
			all_responses << NexosisApi::SessionResponse.new(response_hash)
		end
		all_responses
	else
		raise HttpException.new("Could not retrieve sessions","Get all sessions with query #{query_options.to_s}",response)
	end
end

#remove_session(session_id) ⇒ Object

Remove a session

Parameters:

  • session_id (String) —

    required session identifier


47
48
49
50
51
52
53
54
55
56
57
58
 
# File 'lib/nexosis_api/client/sessions.rb', line 47

def remove_session(session_id)
	if(session_id.to_s.empty?)
		raise ArgumentError 'session_id cannot be empty or nil'
	end
	session_url = '/session/#{session_id.to_s}'
	response = self.class.delete(session_url)	
	if(response.success?)
		return
	else
		raise HttpException.new("Could not delete session with given id","remove session with id #{session_id.to_s}",response)
	end
end

#remove_sessions(query_options = {}) ⇒ Object

Note:

query parameters hash members are type, dataset_name, event_name, start_date, and end_date. Start and end dates refer to the session requested date. Results are not removed but then can only be accessed by dataset name

Remove sessions that have been run. All query options are optional and will be used to limit the sessions removed.

Examples:

Remove all sessions based on a dataset by name

NexosisApi.client.remove_sessions :dataset_name => 'existing_dataset'

Parameters:

  • query_options (Hash) (defaults to: {}) —

    optionally provide query parametes to limit the set of sessions removed.


67
68
69
70
71
72
73
74
75
 
# File 'lib/nexosis_api/client/sessions.rb', line 67

def remove_sessions(query_options = {})
	sessions_url = '/sessions'
	response = self.class.delete(sessions_url, :headers => @headers, :query => get_query_from_options(query_options))
	if(response.success?)
		return
	else
		raise HttpException.new("Could not remove sessions","Remove sessions with query #{query_options.to_s}",response)
	end
end