| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This section lists all KOJAK commands that can be called in KOJAK run
scripts in alphabetical order. Additionally, all PowerLoom commands
documented in the PowerLoom manual (see http://www.isi.edu/isd/LOOM/PowerLoom/)
can also be called. KOJAK commands all reside in the KOJAK module and
can usually be called without the KOJAK/ module prefix as long as
the KOJAK module is visible from the current module (set at the
beginning of a script with in-module). The KOJAK module is
case-insensitive, so commands can be written with any mixture of upper
and lowercase characters.
All commands need to be written in a Lisp-ish input syntax which is the
standard input syntax used by the underlying PowerLoom system.
Knowledge of PowerLoom should not be required, but see
http://www.isi.edu/isd/LOOM/PowerLoom/ for more information if
necessary. Commands take zero or more required arguments and a set of
options specified as keyword/value pairs. Default values for
unspecified options are often taken from the configuration file. Some
commands such as get-parameter return values that can be given as
input to other commands. Here is an example command invocation:
(db-save-groups (get-all-groups)
:dataset (get-parameter "DatasetName")
:source "AV" :category "F")
|
In the descriptions below, parameter types are given in all-caps
following a parameter name. If a function returns a value, the return
type is given after the : following the parameter list.
options is always a list of optional arguments that need to be
supplied as keyword/value pairs. The documentation of a command
describes which options are legal.
edb) according to options. Looks up dbInstance in the module
specified by the :module option (defaults to current module) and retracts any
preexisting connection information. New assertions are also made in that module.
Understands the following options: :connection-string, :dsn, :db, :host, :port,
:user, :password and :module. At least one of :connection-string and :dsn
must be specified. If a connection string is given, all other connection options
are ignored. The values of :user and :password default to the values of DBUser
and DBPassword specified in the configuration file.
DATASET).
If :MI-groups? is TRUE use db-load-MI-groups to load groups which understands
some additional options and knows how to fixup results. This is a kludge to deal
with preservation of some of the group annotations that Jafar's MI code doesn't
carry over to extended groups.
DatasetName
property given in the configuration file. Groups will be encoded relative to
the module sepcified by the optional :module option (defaults to DATASET).
:mode can be either :individual or :collective which controls whether the extension graph is grown for each group indiviually or fow all groups collectively. Collective extension requires more memory but will make MI computation somewhat more accurate in certain cases where individuals are members of multiple groups. Boosting is not yet supported in :collective mode.
:link-types specifies a single or list of link types that should be
considered to expand the graph and compute connection strength. These
link types must match the ones in the link data. Using different link
types particularly benefits the MI computation, since it can
differentiate links of different types. A special anyLink type is
also supported for EDB data, which treats all links as the same.
Link types can be supplied as symbols or strings. If none are given
the values of ExpansionLinkTypes are used.
:methods is the list of connection strength computations that should
be used. Currently supported are :mi, :group-mi, :mi-or-group-mi,
:link-count and :connectivity (which is computed implicitly as part of
link counting). Defaults to the value of ExpansionMethods (or
(:connectivity :link-count :group-mi) if not specified). :methods
can be specified as symbols, keywords or strings.
:measures is a list of measures computed by the specified :methods
that will be used to determine the final connection strength. If
there are more than one measure, they will be averaged (bagging).
Each strength computation method produces a number of associated
measures such as maximum and average values, etc. See the
documentation of ExpansionMeasures for a full list.
:boost?, :boost-min-seeds, :boost-factor, :boost-min-step and :boost-max-cycles control boosting. See the documentation of the corresponding configuration parameters for more information.
:depth specifies to which depth the graph around seed members should
be expanded. Defaults to the value of ExpansionDepth (or 1 if not
specified). IMPORTANT: due to graph fanout this value has a big
impact on run time. Use values larger than 1 only for cases with very
small seed groups (e.g., 1-5 members) and increase it only one step at
a time if needed.
:top-N specifies how many of the members of an extended group should be kept after the strength computation is complete. If it is not supplied, all members will be kept.
:module can be specified to be the module in which group extension
will be performed. It defaults to DATASET. All new extended
members of each group will be interned into the global objects table.
retrieve-groups and retrieve-events). The set of events can
be restricted by supplying them in the :events option. Runs in the the module
specified by the :module option (defaults to DATASET). A :mode option can be
supplied as :aggressive, :conservative (the default) or :very-conservative to control
the manner in which unknown groups are hypothesized. :conservative will use events
whose responsible group is not known but some or all of the event participants might
have known group associations. :aggressive will collect event participants of all
events into groups (even if the responsible group is known). :very-conservative
is like :conservative but additionally requires that none of the participants have
any known group associations.
.csv
extension. The :DATA-SOURCE option can be used to specify either directly the
source file or a data key from the configuration file (the default is Data).
If a data key is specified, all its values will be loaded. If :CLEAR-EDB?
is supplied as TRUE, the current content of the EDB will be cleared before new
content will be loaded. Without that, data will be added incrementally.
load-kojak-ontology (which see). The EDB schema will be loaded if :LOAD-EDB-SCHEMA?
is TRUE (the default). Otherwise, the schema can be loaded explicitly with
load-EDB-schema (which see). If :CLEAR-OLD-HYPOTHESES? is TRUE (defaults to the
value of the configuration parameter ClearOldHypotheses), old hypotheses will be
cleared from the hypothesis tables of the KOJAK DB.
print-object-list.
LoadEDBSchemaScript or KJ:scripts;load-edb-schema.plm if not specified
in the configuration. Before the script is loaded, the edb instance will be pointed
to the datbase identified by the :db option which should be a connection string.
If :db is not specified, one of the RDBMS input data sources specified in the configuration
file will be used (for example, one of the values of PrimaryData). The instance
will be set in the module specified by the :module option which defaults to EDB.
This module should match or be visible from the module used by the EDB schema script.
If no RDBMS data source is specified, edb will remain unconnected which is ok as
long as the EDB schema script does not make reference to it.
DATASET). If :assert-envelopes?
is supplied as TRUE, assertion wrappers such as containsInformation or
reportContent will be asserted also. Defines undefined concepts and relations
on the fly to handle incompletely defined LD ontologies.
DATASET). Defines undefined concepts and relations
on the fly to handle incompletely defined LD ontologies.
DATASET (specific hard-coded PL and LD modules are used
for certain IET EDBs). Loading data might mean actually loading the data into the
PowerLoom KR&R system or only loading certain parts + mapping rules that connect
PowerLoom to the evidence database. For large datasets, it is recommended that
the data is stored in the database and only accessed selectively through PowerLoom's
RDBMS interface. What data gets loaded and how can be controlled by a variety of
configuration parameters and scripts (see configuration.dat for more info).
configuration.dat). A list of
command line arguments can be supplied via the :cmd-line-args which override
any information with the same key provided in the configuration file. The
syntax is a list of strings, for example, '("-c" "myconfig.dat").
LoadOntologyScript (or KJ:scripts;load-ontology.plm
if not specified in the configuration).
ReportFile parameter). If a :directory option is given (defaults to
ReportDirectory or the empty string), it will be prepended to form the full report
file name. :if-exists can be used to specify what to do if the report file already
exists. Supported values are :append, :supersede (the default) or :error.
:format (defaults to ReportFormat) controls the output format. Supported
formats are CSV-Table, IET-Report, IET-Y3-Report and IET-Y3-Report. If no
format is specified it will be inferred from the report file extension (.csv is
interpreted as CSV-Table, everything else is interpreted as IET-Report).
The :threshold-function option can be used to point to a specialized STELLA
thresholding function. Without that, thresholding will be performed relative to the
various thresholding parameters specified in the configuration file. :report-factor
can be used to specify a fraction of group members to be reported, e.g., to force
a certain percentage of over or underreporting. For example, 1.2 would specify
20% overreporting on top of what thresholding would normally produce (the default
is 1.0). If :report-member-weights? is TRUE, hypothesized group members will be
annotated with a weight indicating how strongly they are deemed to be a group
member (defaults to the value of ReportMemberWeights). If weights are reported,
the :weight-decimals option determines how many decimals behind the decimal point
are used to print the weight in fixed-point format (defaults to the value of
WeightDecimals or 6). The computed number of to-be-reported members will usually
wind up somewhere within a run of members with equal membership weights. The value
of :last-run-cutoff determines how this last run should be cut. The default is
:inclusive which will keep all members of this last run (see the documentation of
the LastRunCutoff parameter for more information). If :report-names? is TRUE
groups and members will be reported with their namestrings if appropriately defined by
GROUPS/nameString assertions or rules (defaults to the value of ReportNames).
:module specifies the module relative to which output will be peformed (defaults to
DATASET). Arbitrary other options can also be specified which are passed on to
:threshold-function.
load-kojak-configuration
or initialize-kojak can be used subsequently to change the configuration
if necessary.
CAUTION: This will destroy all loaded data and ontologies and might break
other loaded STELLA systems if they do reference KOJAK symbols in their code.
DATASET) and return
them as a list of event objects. Also interns events in the global object table
as a side effect.
DATASET) and return
them as a list of group objects. Also interns the retrieved groups in the global
object table as a side effect.
DATASET.
RunKojakScript configuration property.
compute-nof-members-to-report-from-configuration). If :report-factor is given
determine how many members should be reported and then multiply that by the given
factor (default = 1.0) which allows over or underreporting. The computed number of
to-be-reported members will usually wind up somewhere within a run of members with
equal membership weights. The value of :last-run-cutoff determines how this last
run should be cut. The default is :inclusive which will keep all members of this
last run (see the documentation of the LastRunCutoff parameter for more information).
Performs thresholding in the module specified by :module which defaults to DATASET.
Any other options will be passed on to the threshold computation function.
9.1 Important PowerLoom Commands 9.2 Important RDBMS Commands 9.3 XTIE-Specific Commands for IET Datasets
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The following commands are an important subset of PowerLoom commands that are used to define and load ontologies, make assertions, queries, etc. The full set of PowerLoom commands can be found in the PowerLoom manual (see http://www.isi.edu/isd/LOOM/PowerLoom/).
ask
will spend most of its effort to determine whether the proposition
is true and only a little effort via shallow inference strategies to
determine whether it is false. To find out whether a proposition is
false with full inference effort ask its negation.
KIF example: (ask (happy Fred)) will return TRUE if Fred was indeed
found to be happy. Note, that for this query to run, the logic
constant Fred and the relation happy must already be defined (see
assert). Use (set/unset-feature goal-trace) to en/disable goal
tracing of the inference engine.
The ask command supports the following options: :TIMEOUT is an
integer or floating point time limit, specified in seconds. For
example, the command (ask (nervous Fred) :timeout 2.0) will cease
inference after two seconds if a proof has not been found by then.
If the :DONT-OPTIMIZE? is given as TRUE, it tells PowerLoom to
not optimize the order of clauses in the query before evaluating it.
This is useful for cases where a specific evaluation order of the
clauses is required (or the optimizer doesn't do the right thing).
If :THREE-VALUED is given as TRUE, PowerLoom will try to prove
the negation of the query with full effort in case the given query
returned UNKNOWN. By default, PowerLoom uses full effort to prove
the query as stated and only a little opportunistic effort to see
whether it is actually false.
happy must already
be defined. If the constant Fred has not yet been created, it is
automatically created as a side-effect of calling assert.
(assert-from-query <query-command>
[:relation <relation-name>]
[:pattern <description-term>]
[:module <module-name>])
|
<query-command> has to be a strict or partial retrieval command. If a :relation option is supplied, <relation-name> is used as the relation of the resulting propositions. In this case the bindings of each solution will become arguments to the specified relation in the order of querys output variables (the arities have to match). The :pattern option is a generalization of this mechanism that specifies an arbitrary proposition pattern to be instantiated by the query's solution. In this case <description-term> has to be a SETOFALL or KAPPA expression whose IO-variables will be bound in sequence to the bindings of a query solution to generate the resulting proposition. Finally, if a :module option is specified, the assertions will be generated in that module. Note that for this to work the relations referenced in the query proposition or pattern have to be visible in the module. Also, instances will not be copied to the target module, therefore, the resulting propositions might reference external out-of-module objects in case they are not visible there. Here are some examples:
(assert-from-query (retrieve all (foo ?x ?y)))
(assert-from-query (retrieve all (?y ?x)
(exists ?z
(and (foo ?x ?z)
(foo ?z ?y))))
:relation bar :module other)
(assert-from-query
(retrieve all (and (relation ?x) (symmetric ?x)))
:pattern (kappa (?pred)
(forall (?x ?y)
(=> (holds ?pred ?x ?y)
(holds ?pred ?y ?x))))))
|
cc is a no-op if the
context reference cannot be successfully evaluated.
(defconcept <conceptconst> [(<var> <parent>*)]
[:documentation <string>]
[:<= <sentence>] | [:=> <sentence>] |
[:<<= <sentence>] | [:=>> <sentence>] |
[:<=> <sentence>] | [:<=>> <sentence>] | [:<<=> <sentence>] |
[:<<=>> <sentence>] |
[:axioms {<sentence> | (<sentence>+)}] |
<keyword-option>*)
|
Declaration of a concept variable <var> is optional, unless any
implication (arrow) options are supplied that need to reference it. A
possibly empty list of concept names following <var> is taken as the list
of parents of <conceptconst>. Alternatively, parents can be specified
via the :=> option. If no parents are specified, the parent of
<conceptconst> is taken to be THING. <keyword-option> represents a
keyword followed by a value that states an assertion about <conceptconst>.
See defrelation for a description of <keyword-option>s.
(deffunction <funconst> (<vardecl>+) [:-> <vardecl>]
[:documentation <string>]
[:<= <sentence>] | [:=> <sentence>] |
[:<<= <sentence>] | [:=>> <sentence>] |
[:<=> <sentence>] | [:<=>> <sentence>] |
[:<<=> <sentence>] | [:<<=>> <sentence>] |
[:axioms {<sentence> | (<sentence>+)}]
[<keyword-option>*])
|
Function parameters can be typed or untyped. If the :-> option is
supplied, it specifies the output variable of the function. Otherwise,
the last variable in the parameter list is used as the output variable.
See defrelation for a description of <keyword-option>s.
(defobject <constant>
[:documentation <string>]
[<keyword-option>*])
|
<keyword-option> represents a keyword followed by a value
that states an assertion about <constant>. See defrelation for a
description of <keyword-option>s.
defobject provides a sugar-coated way to assert a collection of facts
about a logic constant, but otherwise adds nothing in terms of functionality.
(defrelation <relconst> (<vardecl>+)
[:documentation <string>]
[:<= <sentence>] | [:=> <sentence>] |
[:<<= <sentence>] | [:=>> <sentence>] |
[:<=> <sentence>] | [:<=>> <sentence>] |
[:<<=> <sentence>] | [:<<=>> <sentence>] |
[:axioms {<sentence> | (<sentence>+)}]
[<keyword-option>*])
|
Relation parameters can be typed or untyped.
<keyword-option> represents a keyword followed by a value that states an
assertion about <relconst>. For example, including the option :foo bar
states that the proposition (foo <relconst> bar) is true. :foo (bar fum)
states that both (foo <relconst> bar) and (foo <relconst> fum) are true.
:foo true states that (foo <relconst>) is true, :foo false states that
(not (foo <relconst>)) is true.
(retrieve [<integer> | all]
[[{<vardecl> | (<vardecl>+)}]
<proposition>])
|
The variables and proposition are similar to an exists sentence or
kappa term without the explicit quantifier. If variables are declared,
they must match the free variables referenced by <proposition>. Otherwise,
the free variables referenced in <proposition> will be used as the query
variables. If <proposition> is omitted, the most recently asked query
will be continued.
A solution is a set of bindings for the listed variables for which
<proposition> is true. The optional first argument controls how many
solutions should be generated before control is returned. The keyword
all indicates that all solutions should be generated. By default,
retrieve returns after it has found one new solution or if it cannot
find any more solutions.
retrieve returns an iterator which saves all the necessary state of
a query and stores all generated solutions. When used interactively,
the returned iterator will print out with the set of solutions collected
so far. Calling retrieve without any arguments (or only with the first
argument) will generate one (or more) solutions to the most recently
asked query.
KIF examples:
(retrieve (happy ?x)) |
will try to find one happy entity and store it in the returned query iterator.
(retrieve 10 (happy ?x)) |
will try to find 10 happy entities.
(retrieve 10) |
will try to find the next 10 happy entities..
(retrieve all (happy ?x)) |
will find all happy entities.
(retrieve all (?x Person) (happy ?x)) |
will to find all happy people. Here we used the optional retrieve variable syntax to restrict the acceptable solutions. The above is equivalent to the following query:
(retrieve all (and (Person ?x) (happy ?x))) |
Similarly,
(retrieve all (?x Person)) (retrieve all (Person ?x)) (retrieve all ?x (Person ?x)) |
will find all people. Note that in the first case we only specify a query variable and its type but omit the logic sentence which defaults to TRUE. This somewhat impoverished looking query can be paraphrased as "retrieve all ?x of type Person such that TRUE."
(retrieve ?x (or (happy ?x) (parent-of Fred ?x))) |
will try to find a person that is happy or has Fred as a parent.
(retrieve (?y ?x) (parent-of ?x ?y)) |
will try to find the one pair of parent/child and return it in the order of child/parent.
(retrieve all (?x Person)
(exists (?y Person) (parent-of ?x ?y)))
|
will generate the set of all parents. Note, that for these queries to run,
the class Person, the relations happy and parent-of, and the logic
constant Fred must already be defined (see assert).
Use (set/unset-feature trace-subgoals) to en/disable goal tracing of the
inference engine.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The following commands are an important subset of PowerLoom commands that deal with its relational database interface. These commands are particularly important for advanced configuration with an external relational evidence database.
(defdb <dbconst>
[:protocol <protocol string>]
[:server-type <server type string>]
[:dsn <ODBC data-source name string>]
[:odbc-connection-string <ODBC connection string>]
[:jdbc-connection-string <JDBC connection string>]
[:connection-string <connection string>] ;; deprecated
[:host <server host string>]
[:port <server host port>]
[:user <user name string>]
[:password <password string>]
[:db-name <database name string>]
[<keyword-option>*])
|
Connection information can be asserted explicitly later or be done
programmatically, as long as it is done before the first time a
connection attempt is made (e.g., during a query). This information
is passed to SDBC/connect (which see for more documentation on
ways to specify a connection). For example, for ODBC a :DSN, an
:ODBC-CONNECTION-STRING or an appropriate combination of :HOST,
:PORT, :USER, :PASSWORD AND :DB-NAME can be used. For JDBC a
:JDBC-CONNECTION-STRING or combination of :HOST, :PORT, etc. can
be used. See defobject for additional legal keyword options.
(defquery <relconst> (<vardecl>+)
{:query-pattern (<query-evaluator> <dbconst> <arguments-string>)}*
[<keyword-option>*]).
|
<query-evaluator> has to be a Computed-Procedure that takes the following
three arguments: the <relconst> query proposition, the database object <dbconst>
and the arguments string. It needs to return an iterator that generates CONS
tuples whose elements will be bound in sequence to <relconst>'s arguments.
See defrelation for other legal keyword options.
(deftable <relconst> <dbconst> <tablename> (<columndecl>+)
[<keyword-option>*]).
|
<columndecl>'s specify the names (and optionally types) of the columns of the database table. They have the same form as a PowerLoom <vardecl>, but column names can be specified with or without question marks. If there is a question mark it will be stripped to determine the column name, otherwise a question mark will be added to generate the relation variable. The optional type specifies the domain of that argument and controls any necessary coercion. The name of each column HAS TO MATCH one of the columns of <tablename>, however, the order is irrelevant and arbitrary projections can be defined by only specifying some subset of <tablename>'s columns.
See defrelation for legal keyword options.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The following commands are specific to IET datasets and the XTIE collaboration during the Y2.5 and Y3 evaluations. They are not useful for general applications.
DATASET.
weight
assertion and use them to assign membership weights for each group object.
This allows us to report members in reports in the correct order.
DATASET). Event teams won't be loaded into
the global objects table to avoid interference with real groups.
performedBy assertion. The reason
we do this almost literal copying is that the alert reports have various intricate
structure and order that we don't want to mess up. For this to work it is important
that xtie-merge-case-teams-and-groups was run first.
| [ << ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |