Run Object¶
Run Details¶
A RunDetails object in VOR Stream contains the following data:
| Data | Description | Data Type |
|---|---|---|
| Name | Name of the run | String |
| Study | Study selected for the run | Structure |
| StartDate | Time when the run was started | DateTime |
| Comment | Any comments entered for the run | String |
| Options | Runtime options provided by the user who started the run | Map |
| Objects | Runtime objects by options key to list of object IDs | Map |
| Playpen | Playpen from which the run was started | String |
| Playpen ID | ID of the playpen | Integer |
| UserID | ID of the user who started the run | String |
| UserName | Name of the user who started the run | String |
| UserEmail | Email of the user who started the run | String |
To retrieve data about a run, pass the run's unique numeric identifier
to the GetRunDetails function in Golang or the get_run_details in
Python.
Example: Go¶
runID := frgutil.GetRunID(u.hh)
runDetails, err := sdkClient.GetRunDetails(runID)
if err != nil {
log.Fatal(err)
}
// Getter functions to retrieve specific data in a run object
runName := runDetails.GetName()
runStartDate := runDetails.GetStartDate()
runUserName := runDetails.GetUserName()
Example: Python¶
from sdk import run
runID = handle.options["RunID"]
run_details = run.get_run_details(runID)
# Who started the run?
>>> run_details.UserID
susan
# What is the name of the run?
>>> run_details.Name
test
#When was the start date for the run?
>>> run_details.StartDate.seconds
1652121071
>>> run_details.StartDate.nanos
324463000
Study Details¶
The study that is associated with a run is embedded in the run details object.
Retrieve the study object by calling the GetStudy function in Golang or by
accessing the Study attribute in Python.
Example: Go¶
runID := frgutil.GetRunID(u.hh)
runDetails, err := sdkClient.GetRunDetails(runID)
if err != nil {
log.Fatal(err)
}
// Getter functions to retrieve specific data in a run object
study := runDetails.GetStudy()
Example: Python¶
This Python example shows that the study object in a run details object is the
same as the study object retrieved by the get_study function.
from sdk import run
from sdk import study
run_details = run.get_run_details(run_id)
>>> run_details.Study.name
First Study
>>> run_details.Study.id
1
>>> study.get_study(run_details.Study.id).name
First Study
Runtime Options¶
Runtime options are user-customizable options that can be set or adjusted
when building or running a study. A map of typed options can be retrieved by
calling the GetRunOptions function in Golang or the get_run_options
function in Python.
Tip
Runtime options can be configured through playpen configuration. See Playpen Configuration page for documentation on how to configure them.
Configurable options are user-customizable options that can be set or adjusted when building or running a study. Configurable options come in the following forms:
| Option Type | Protobuf Well-Known Type |
|---|---|
| datepicker | String |
| dropdown | String |
| slider | Double |
| switch | Bool |
| text-box | String |
To retrieve a combination of run options and study options directly without
accessing other run details, pass the run's unique identifier to the GetRunOptions
function in Golang or the get_run_options in Python. If the same option exists
in both study and run options, the value from run options takes precedence.
Example: Go¶
runID := frgutil.GetRunID(u.hh)
runOptions, err := sdkClient.GetRunOptions(runID)
if err != nil {
log.Fatal(err)
}
log.Printf("RUN OPTIONS:")
for k, v := range runOptions {
log.Printf("\t\t%s (%T): %v", k, v, v)
}
log.Printf("%+v", runOptions)
Example: Python¶
from sdk import run
for k, v in run.get_run_options(15).items():
print(f"{k} ({type(v)}): {v}")
Runtime Objects¶
Configuration Groups¶
Users can configure multiple configuration groups to be selected at runtime.
The configuration groups are stored in the run object and can be retrieved
by calling the get_run_config_groups function in Python. The result is a
map of option keys to a list of configuration group objects.
Example: Go¶
Go support for retrieving configuration groups is not available at this time.
Example: Python¶
To pull all configuration groups attached to a run:
run_id = handle.options["RunID"]
for k, v in run.get_run_config_groups(run_id).items():
logging.info(f"{k} CONFIG_GROUPS:\n")
logging.info("====================================")
for c in v:
logging.info(f"{c.meta.ConfigGroupName} (id={c.meta.ConfigGroupID}) tables:")
for table_name, table_df in c.tables.items():
logging.info(f"{table_name}:\n{table_df}")
logging.info("====================================")
Example output for a run with only one runtime configuration group option and only one configuration group selected for the option:
INFO [2024-08-05 08:41:32] sample_config_groups CONFIG_GROUPS:
INFO [2024-08-05 08:41:32]
INFO [2024-08-05 08:00:00] ====================================
INFO [2024-08-05 08:00:00] Sample Config Group (id=100) tables:
INFO [2024-08-05 08:00:00] Sheet1:
INFO [2024-08-05 08:00:00] string_column number_column int_column datetime_column
INFO [2024-08-05 08:00:00] 0 abcdef 1234.5678 1234 2024-08-02 17:50:32.920
INFO [2024-08-05 08:00:00] Sheet2:
INFO [2024-08-05 08:00:00] string_column number_column int_column datetime_column
INFO [2024-08-05 08:00:00] 0 ghijklm 9876.5432 9876 2024-08-02 17:51:16.970
INFO [2024-08-05 08:00:00] ====================================
If a specific option key is desired, use the get_run_config_groups_by_option_key
method as shown below. This eliminates the need to iterate over all
configuration groups and filter by option key. It also is more efficient if
there are a large number of configuration groups attached to the run.
run_id = handle.options["RunID"]
for c in run.get_run_config_groups_by_option_key(run_id, "sample_config_groups"):
logging.info(f"{c.meta.ConfigGroupName} (id={c.meta.ConfigGroupID}) tables:")
for table_name, table_df in c.tables.items():
logging.info(f"{table_name}:\n{table_df}")
logging.info("====================================")
Continuing on the previous example, the above code will print the following:
INFO [2024-08-05 08:00:00] ====================================
INFO [2024-08-05 08:00:00] Sample Config Group (id=100) tables:
INFO [2024-08-05 08:00:00] Sheet1:
INFO [2024-08-05 08:00:00] string_column number_column int_column datetime_column
INFO [2024-08-05 08:00:00] 0 abcdef 1234.5678 1234 2024-08-02 17:50:32.920
INFO [2024-08-05 08:00:00] Sheet2:
INFO [2024-08-05 08:00:00] string_column number_column int_column datetime_column
INFO [2024-08-05 08:00:00] 0 ghijklm 9876.5432 9876 2024-08-02 17:51:16.970
INFO [2024-08-05 08:00:00] ====================================
Filters¶
Users can configure multiple filters to be selected at runtime. The filters
are stored in the run object and can be retrieved by calling the GetRunFilters
function in Golang or the get_run_filters function in Python. The result is a
map of option keys to a list of filter objects.
Example: Go¶
To pull all filters attached to a run:
runID := frgutil.GetRunID(u.hh)
runFilters, err := sdkClient.GetRunFilters(runID)
if err != nil {
log.Fatal(err)
}
for k, v := range runFilters {
log.Printf("%s FILTERS:", k)
for _, f := range v {
log.Printf("\t\t%s (type=%s) (id=%d): %s", f.GetName(), f.GetType(), f.GetId(), f.GetValue())
}
}
Example output for a run with a single set of filters:
INFO [2024-08-01 07:07:31] portfolio_filters FILTERS:
INFO [2024-08-01 07:07:31] Filter 1 (type=PORTFOLIO) (id=1): portfolio=="MORTGAGE"
If a specific option key is desired, use the GetRunFiltersByOptionKey
method as shown below. This eliminates the need to iterate over all filters
and filter by option key. It also is more efficient if there are a large number
of filters attached to the run.
runID := frgutil.GetRunID(u.hh)
portfolioFilters, err := sdkClient.GetRunFiltersByOptionKey(runID, "portfolio_filters")
if err != nil {
log.Fatal(err)
}
for _, f := range portfolioFilters {
log.Printf("%s (type=%s) (id=%d): %s", f.GetName(), f.GetType(), f.GetId(), f.GetValue())
}
Continuing on the previous example, the above code will print the following:
INFO [2024-08-01 07:07:31] Filter 1 (type=PORTFOLIO) (id=1): portfolio=="MORTGAGE"
If a specific filter type is desired, use the GetRunFiltersFilters method as
shown below. This allows for filtering by filter type and/or option key, but it
always returns a map of option keys to a list of filter objects as
GetRunFilters does.
runID := frgutil.GetRunID(u.hh)
runFilters, err := sdkClient.GetRunFiltersFilters(runID, "", "PORTFOLIO")
if err != nil {
log.Fatal(err)
}
for k, v := range runFilters {
log.Printf("%s FILTERS:", k)
for _, u := range v {
log.Printf("\t\t%s (type=%s) (id=%d): %s", f.GetName(), f.GetType(), f.GetId(), f.GetValue())
}
}
Continuing on the previous example, the above code will print the following:
INFO [2024-08-01 07:07:31] portfolio_filters FILTERS:
INFO [2024-08-01 07:07:31] Filter 1 (type=PORTFOLIO) (id=1): portfolio=="MORTGAGE"
Example: Python¶
To pull all filters attached to a run:
run_id = handle.options["RunID"]
for k, v in run.get_run_filters(run_id).items():
logging.info(f"{k} FILTERS:")
for f in v:
logging.info(f"\t{f.name} (type={f.type}) (id={f.id}): {f.value}")
Example output for a run with a single set of filters:
INFO [2024-08-01 07:07:31] portfolio_filters FILTERS:
INFO [2024-08-01 07:07:31] Filter 1 (type=PORTFOLIO) (id=1): portfolio=="MORTGAGE"
If a specific option key is desired, use the get_run_filters_by_option_key
method as shown below. This eliminates the need to iterate over all filters
and filter by option key. It also is more efficient if there are a large number
of filters attached to the run.
run_id = handle.options["RunID"]
for f in run.get_run_filters_by_option_key(run_id, "portfolio_filters"):
logging.info(f"{f.name} (type={f.type}) (id={f.id}): {f.value}")
Continuing on the previous example, the above code will print the following:
INFO [2024-08-01 08:41:32] Filter 1 (type=PORTFOLIO) (id=1): portfolio=="MORTGAGE"
If a specific filter type is desired, use the get_run_filters, specifying
optional parameters. This allows for filtering by filter type and/or option
key, but it always returns a map of option keys to a list of filter objects.
run_id = handle.options["RunID"]
for k, v in run.get_run_filters(run_id, type_filter="PORTFOLIO").items():
logging.info(f"{k} FILTERS:")
for f in v:
logging.info(f"\t{f.name} (type={f.type}) (id={f.id}): {f.value}")
Continuing on the previous example, the above code will print the following:
INFO [2024-08-01 07:07:31] portfolio_filters FILTERS:
INFO [2024-08-01 07:07:31] Filter 1 (type=PORTFOLIO) (id=1): portfolio=="MORTGAGE"
Uploads¶
Users can configure multiple uploads to be selected at runtime. The uploads
are stored in the run object and can be retrieved by calling the GetRunUploads
function in Golang or the get_run_uploads function in Python. The result is a
map of option keys to a list of upload objects, which contains the contents
of the upload and metadata about the upload.
Example: Go¶
To pull all uploads attached to a run:
runID := frgutil.GetRunID(u.hh)
runUploads, err := sdkClient.GetRunUploads(runID)
if err != nil {
log.Fatal(err)
}
for k, v := range runUploads {
log.Printf("%s UPLOADS:", k)
for _, u := range v {
log.Printf("\t\t%s (type=%s) (id=%d)", u.GetName(), u.GetType(), u.GetId())
}
}
For a run with two sets of uploads, history_uploads and scenario_uploads,
the above code will print something like the following:
INFO [2024-08-01 07:07:31] history_uploads UPLOADS:
INFO [2024-08-01 07:07:31] Domestic_history.xlsx (type=ME_HISTORY) (id=2)
INFO [2024-08-01 07:07:31] scenario_uploads UPLOADS:
INFO [2024-08-01 07:07:31] Euro Zone Severe Impact Scenario.xlsx (type=ME_SCEN) (id=1)
If a specific option key is desired, use the GetRunUploadsByOptionKey
method as shown below. This eliminates the need to iterate over all uploads
and filter by option key. It also is more efficient if there are a large number
of uploads attached to the run.
runID := frgutil.GetRunID(u.hh)
historyUploads, err := sdkClient.GetRunUploadsByOptionKey(runID, "history_uploads")
if err != nil {
log.Fatal(err)
}
for _, v := range historyUploads {
log.Printf("%s (type=%s) (id=%d)", v.GetName(), v.GetType(), v.GetId())
}
Continuing on the previous example, the above code will print the following:
INFO [2024-08-01 07:07:31] Domestic_history.xlsx (type=ME_HISTORY) (id=2)
If a specific upload type is desired, use the GetRunUploadsFiltered method as
shown below. This allows for filtering by upload type and/or option key, but it
always returns a map of option keys to a list of upload objects as
GetRunUploads does.
runID := frgutil.GetRunID(u.hh)
runUploads, err := sdkClient.GetRunUploadsFiltered(runID, "", "ME_HISTORY")
if err != nil {
log.Fatal(err)
}
for k, v := range runUploads {
log.Printf("%s UPLOADS:", k)
for _, u := range v {
log.Printf("\t\t%s (type=%s) (id=%d)", u.GetName(), u.GetType(), u.GetId())
}
}
Continuing on the previous example, the above code will print the following:
INFO [2024-08-01 07:07:31] history_uploads UPLOADS:
INFO [2024-08-01 07:07:31] Domestic_history.xlsx (type=ME_HISTORY) (id=2)
Example: Python¶
To pull all uploads attached to a run:
run_id = handle.options["RunID"]
for k, v in run.get_run_uploads(run_id).items():
logging.info(f"{k} UPLOADS:")
for u in v:
logging.info(f"\t{u.name} (type={u.type}) (id={u.id})")
For a run with two sets of uploads, history_uploads and scenario_uploads,
the above code will print something like the following:
INFO [2024-08-01 08:36:13] scenario_uploads UPLOADS:
INFO [2024-08-01 08:36:13] Euro Zone Severe Impact Scenario.xlsx (type=ME_SCEN) (id=1)
INFO [2024-08-01 08:36:13] history_uploads UPLOADS:
INFO [2024-08-01 08:36:13] Domestic_history.xlsx (type=ME_HISTORY) (id=2)
If a specific option key is desired, use the get_run_uploads_by_option_key
method as shown below. This eliminates the need to iterate over all uploads
and filter by option key. It also is more efficient if there are a large number
of uploads attached to the run.
run_id = handle.options["RunID"]
for u in run.get_run_uploads_by_option_key(run_id, "history_uploads"):
logging.info(f"{u.name} (type={u.type}) (id={u.id})")
Continuing on the previous example, the above code will print the following:
INFO [2024-08-01 08:41:32] Domestic_history.xlsx (type=ME_HISTORY) (id=2)
If a specific upload type is desired, use the get_run_uploads, specifying
optional parameters. This allows for filtering by upload type and/or option
key, but it always returns a map of option keys to a list of upload objects.
run_id = handle.options["RunID"]
for k, v in run.get_run_uploads(run_id, type_filter="ME_HISTORY").items():
logging.info(f"{k} UPLOADS:")
for u in v:
logging.info(f"\t{u.name} (type={u.type}) (id={u.id})")
Continuing on the previous example, the above code will print the following:
INFO [2024-08-01 08:36:13] history_uploads UPLOADS:
INFO [2024-08-01 08:36:13] Domestic_history.xlsx (type=ME_HISTORY) (id=2)