Gave some tlc to structured comments in module configuration.
authorYeGoblynQueenne@splinter <ep50@uni.brighton.ac.uk>
Fri, 25 Nov 2016 12:28:11 +0000 (12:28 +0000)
committerYeGoblynQueenne@splinter <ep50@uni.brighton.ac.uk>
Fri, 25 Nov 2016 12:28:11 +0000 (12:28 +0000)
grammar_learning/configuration.pl

index e19bfb0..291439a 100644 (file)
 %
 %      Setting Sample to 0 means no bootstrapping will take place.
 %
+
 %bootstrapping(4,0.3).
 bootstrapping(0,0.3).
 
 
-%!     split_divisor(?M) is det.
+%!     cnf_split_divisor(?M) is det.
 %
 %      Length of splits for Chomsky Normal Form grammar.
+%
 %      A grammar in CNF is created by recursively splitting each
 %      sentence to sub-sequences of N/M tokens each, where N the length
 %      of the sentence (or to N/M - 1 if there are not enough tokens
 %      for the longer split).
 %
+%      NOTE: CNF grammars are not yet fully implemented.
+%
 cnf_split_divisor(2).
 
 
@@ -74,10 +78,11 @@ cnf_split_divisor(2).
 %      Currently only used in stochastic grammar evaluation.
 %
 %      NOTE: It doesn't make any sense to set this to 1 (or less) so
-%      instead of having to add special logic to deal with that in
-%      cross-validation predicates they throw an exception and it's as
-%      cryptic as can be, because how can I respect you if you don't
-%      respect yourself, user?
+%      instead of having to add special logic to cross-validation
+%      predicates so that they can deal with that sort of thing
+%      gracefully, they throw an exception and it's as cryptic as can
+%      be, because how can I respect you if you don't respect yourself,
+%      user?
 %
 cross_validation_k(10).
 
@@ -85,9 +90,9 @@ cross_validation_k(10).
 %!     edit_output_grammar(?Bool) is det.
 %
 %      Whether to immediately open a newly constructed grammar file in
-%      the Swi-Prolog IDE. Set to fals while cross-validating or
+%      the Swi-Prolog IDE. Set to false while cross-validating or
 %      otherwise running multiple experiments back-to-back to avoid
-%      having to click on a "Reload" prompt k-times (or how many).
+%      having to click on a "Reload" prompt k-times (or however many).
 %
 edit_output_grammar(false).
 
@@ -95,8 +100,8 @@ edit_output_grammar(false).
 %!     edit_sentence_frequencies(?Bool) is det.
 %
 %      Whether to immediately open a newly created sentence frequencies
-%      file. Unlike edit_output_grammar/1 this too may interfere with
-%      cross-validation.
+%      file in the Swi Prolog IDE. Like edit_output_grammar/1 this too
+%      may interfere with cross-validation.
 %
 edit_sentence_frequencies(false).
 
@@ -105,18 +110,21 @@ edit_sentence_frequencies(false).
 %
 %      What metric to use to evaluate different grammar types.
 %
-%      Grammar_type should be one of: [stochastic,deterministic].
-%      Metric should be one of: [kld,precision_recall,f_measure].
+%      Grammar_type must be one of:
+%       * stochastic
+%       * deterministic
 %
-%      Metric 'kld' is only meaningful with stochastic grammars and
+%       Metric must be one of:
+%        * kld
+%        * precision_recall
+%       * f_score
+%
+%      Option 'kld' is only meaningful with stochastic grammars and
 %      will anyway raise errors otherwise (because of the arity of
-%      stochatsic grammars' start terms). precision_recall and
+%      stochastic grammars' start terms). precision_recall and
 %      f_measure can be used with stochastic grammars but they are more
 %      relevant to deterministic ones.
 %
-%      NOTE: f_measure is not implemented yet and precision_recall
-%      will need some tlc.
-%
 evaluation_metric(stochastic, kld).
 evaluation_metric(deterministic, f_score).
 
@@ -124,6 +132,8 @@ evaluation_metric(deterministic, f_score).
 %!     examples_file_name(?Name) is det.
 %
 %      Basename of the examples file to use in induction.
+%
+
 %examples_file_name(mtg_handsim_atomised).
 %examples_file_name(mtg_handsim_clumped).
 %examples_file_name(mtg_trivial).
@@ -162,6 +172,7 @@ examples_file_name(mtg_hand_simulation).
 %examples_file_name(wsj_sgml_inflated).
 %examples_file_name(wsj_sgml_deflated).
 
+
 %!     examples_predicate_name(?Name) is det.
 %
 %      Name of the predicate holding example data. Clauses of this
@@ -170,10 +181,12 @@ examples_file_name(mtg_hand_simulation).
 %      module scope).
 %
 %      In other words, the examples file should have lines of:
-%      Name(Es).
+%      ==
+%      Name(Examples_list).
+%      ==
 %
-%      Where Name the name specified here and Es a list of example
-%      attributes.
+%      Where Name the name specified here and Examples_list a list of
+%      example attributes.
 %
 examples_predicate_name(example_string).
 
@@ -189,7 +202,7 @@ graph_arity(1).
 %
 %      A term Functor/Arity describing the Prolog term used to store
 %      skeleton graph edges in the currently configured skeleton graph
-%      output file (see option output_file_name/1).
+%      output file (see option output_file_name/2).
 %
 %      Note well: this configuration option is _not_ used by any
 %      predicate and is only provided for reference. The reason is
@@ -210,11 +223,14 @@ graph_edges(edge/2).
 %
 %      Name of the root node of the skeleton graph.
 %      One of:
-%      * digraph_root; connect the head of each sub-graph to a node
-%      called "digraph_root" (which is hopefully rare enough that it
-%      won't clash with any existing word).
-%      * none; leave the head of each sub-graph as a top-level node.
-%      This will output a bipartite graph.
+%      * digraph_root
+%      Connect the head of each sub-graph to a node called
+%      "digraph_root" (which is hopefully rare enough that it won't
+%      clash with any existing word).
+%
+%      * none
+%      leave the head of each sub-graph as a top-level node. This will
+%      output a bipartite graph.
 %
 graph_root(digraph_root).
 
@@ -223,10 +239,14 @@ graph_root(digraph_root).
 %
 %      Name of the final node of each sub-graph of the skeleton graph.
 %      One of:
-%      * epsilon; connect the last token of each subgraph to a node
-%      called "epsilon".
-%      * none; leave the end of each sub-graph as found in the data.
-%      This will lead to a graph with varied exit nodes.
+%      * epsilon
+%      Connect the last token of each subgraph to a node called
+%      "epsilon".
+%
+%      * none
+%      Leave the end of each sub-graph as found in the data. This will
+%      lead to a graph with varied exit nodes.
+%
 graph_tail(epsilon).
 
 
@@ -245,28 +265,36 @@ language_file_name(ability_text).
 %
 %      How to add lexical parameters to derived productions.
 %      One of:
-%      * none; don't add lexical parameters.
-%      * first_nonterminal; always add the first nonterminal
-%        constituent of a nonterminal as a lexical parameter to the
-%        head of the latter nonterminal.
+%       * none
+%        Don't add lexical parameters.
+%
+%       * first_nonterminal
+%       Always add the first nonterminal constituent of a nonterminal
+%       as a lexical parameter to the head of the latter nonterminal.
 %
-%      NOTE: The single actually lexicalising option applies to
+%       @tbd: The single actually lexicalising option applies to
 %      deterministic right-regular grammars only. GNF grammars and
 %      stochastic grammars cannot yet be lexicalised.
 %
-%      NOTE: Also, anything besides "none" will do- "first_nonterinal"
+%      @tbd: Also, anything besides "none" will do- "first_nonterinal"
 %      is just something descriptive. Obviously, this needs fixing.
 %
 lexicalisation_strategy(none).
 
 
-%!     output_stream(?Type,?Name) is det.
+%!     output_file_name(?Type,?Name) is det.
 %
 %      Name of the output file for a derived grammar or a compressed
 %      corpus. Type selects clauses according to the type of file to
-%      print.
+%      print and must be one of:
 %
-%      @tbd this should move to project_utilities, it's grown a bit.
+%       * grammar
+%       * grammar_evaluation
+%       * skeleton_graph
+%       * bootstrapped_grammar
+%
+%      @tbd this should move to project_utilities, it's grown a bit
+%      too long for a configuration predicate.
 %
 output_file_name(grammar, Path):-
        transformation_format(F)
@@ -374,28 +402,44 @@ output_file_name(compressed_corpus, corpus(Filename)):-
 %      What kind of file to print out at the end of an induction run.
 %
 %      One of:
-%      * dcg; print out a full grammar with every production connected
-%      to the start symbol, or to a production connected to the start
-%      symbol. The output file is a valid Prolog file with grammar
-%      rules in DCG format.
-%      * tags; print a set of productions that may be used to carve
-%      up a sentence into parts-of-speech, or indeed comrpess it.
-%      * tree; as "dcg" but with a parameterised start-symbol that
-%      captures the parse tree of a parsed (or generated) phrase. NOT
-%      YET IMPLEMENTED.
-%      * compression; print a compression grammar, used to replace
-%      examples' tokens with the names of productions that cover them;
-%      implies "tags" (and indeed includes the tags grammar). Not
-%      complete.
-%      * bnf; as "dcg" but the output is in Backus-Naur Form.
-%      * ebnf; prints grammar in extended bnf.
-%      * dot; print a dot-language file that can be used to generate a
+%      * dcg
+%      Print out a full grammar with every production connected to the
+%      start symbol, or to a production connected to the start symbol.
+%      The output file is a valid Prolog file with grammar rules in DCG
+%      format.
+%
+%      * tags
+%      Print a set of productions that may be used to carve up a
+%      sentence into parts-of-speech, or indeed comrpess it.
+%
+%      * tree
+%      As "dcg" but with a parameterised start-symbol that captures the
+%      parse tree of a parsed (or generated) phrase. This option is not
+%      yet implemented.
+%
+%      * compression
+%      Print a compression grammar, used to replace examples' tokens
+%      with the names of productions that cover them; implies "tags"
+%      (and indeed includes the tags grammar). Not complete.
+%
+%      * bnf
+%       As "dcg" but the output is in Backus-Naur Form.
+%
+%      * ebnf
+%      Prints grammar in extended bnf.
+%
+%      * dot
+%      Print a dot-language file that can be used to generate a
 %      visualisation of the grammar using a program such as graphviz.
-%      * lean_dot; as dot, but only prints nonterminal and
-%      preterminal nodes (dot explicitly prints terminals also,
-%      kind of like in a parse tree).
 %
-%      @tbd Implement tree; complete compression.
+%      * lean_dot
+%      As dot, but only prints nonterminal and preterminal nodes (dot
+%      explicitly prints terminals also, kind of like in a parse tree).
+%
+%      @tbd Implement option "tree"; complete option "compression".
+%
+%      @tbd Does option "tags" work, actually? I'll be rather surprised
+%      if it does! I think it's left over from a much earlier version.
 %
 output_type(dcg).
 
@@ -422,24 +466,36 @@ output_format(skeleton_graph, '.pl').
 %      Number of constituents of any type in the left- or right-hand
 %      side of productions.
 %
-%      Side is one of: [lhs, rhs], as in left-hand side, right-hand
-%      side.
+%      Side must be one of:
+%        * lhs
+%        * rhs
+%
+%       As in left-hand side, right-hand side.
 %
-%      Constituent is one of: [t, nt], for terminal and nonterminal
-%      respectively.
+%      Constituent must be one of:
+%        * t
+%        * nt
 %
-%      N is a number, the number of constituents of the given type on
-%      the given side.
+%       For terminal and nonterminal, respectively.
+%
+%      N must be a number, the number of constituents of the given type
+%      on the given side.
 %
 %      NOTE: Currently, this only makes a difference with productions
 %      in Greibach Normal Form, created with:
+%      ==
 %      transformation_format(gnf)
+%      ==
 %
-%      When producing GNF grammars take care not to set options
-%      graph_arity(K), production_arity(rhs, nt, N) so that N > K.
+%      When producing GNF grammars take care to *not* set options
+%      ==
+%      graph_arity(K)
+%       production_arity(rhs, nt, N)
+%       ==
+%       so that N > K.
 %
 %      @tbd and that of course should be dealt with in the code, not
-%      left up to the user.
+%      left up to the user. Make it so.
 %
 production_arity(rhs, nt, 2).
 %production_arity(rhs, t, 1).
@@ -450,22 +506,32 @@ production_arity(rhs, nt, 2).
 %      Whether to rename nonterminals that will compile to built-ins at
 %      the DCG compiler.
 %
-%      Bool_or_prefix is either the atom "false", in which case
+%      Bool_or_prefix should be either the atom "false", in which case
 %      built-ins are not renamed or an atom to be used as the prefix of
 %      renamed productions.
 %
 %      Note: if you want the prefix to end in an underscore you have to
-%      specify it here, for example:
+%      specify it here.
+%
+%       For example:
+%       ==
 %      rename_built_ins(n_)
+%      ==
 %
 %      Will result in productions like:
+%      ==
 %      n_is --> [is]...
+%      ==
 %
-%      Wheras:
+%      Whereas:
+%      ==
 %      rename_built_ins(n)
+%      ==
 %
-%      Will only give you:
+%      Will give you:
+%      ==
 %      nis --> [is] ...
+%      ==
 %
 rename_built_ins(n_).
 
@@ -480,7 +546,7 @@ rename_built_ins(n_).
 %      port) and not the depth of recursion, hhmmm..
 %
 %      @bug it's possible to specify a minimum value of N, at which
-%      point this multiplier will must be set to something probably
+%      point this multiplier will be set to something probably
 %      unreasonably large. I think. Figure out and fix.
 %
 sentence_completion_inference_limit_multiplier(4000).
@@ -514,51 +580,44 @@ start_symbol_arity(N):-
 
 %!     evaluation_parsing_time_limit(?Limit) is semidet.
 %
-%      Maximum number of seconds to search for a parse when parsing
-%      with a stochastic GNF grammar.
+%      Maximum number of seconds to search for a derivation when
+%      parsing with a learned grammar.
 %
-%      This is used in stochastic grammar evaluation to avoid having to
-%      spend too long in parsing a single string.
+%      This is used in grammar evaluation to avoid having to spend too
+%      long in parsing a single string, particularly when parsing with
+%      CFGs (including GNF).
 %
 evaluation_parsing_time_limit(0.5).
 
 
 %!     training_set_size(?Size) is det.
 %
-%      Size of the examples set split out for training. The size of the
-%      held-out test set will be the complement of this number to 1,
-%      duh.
+%      Size of the examples set split out for training.
+%
+%      Size must be a floating point number between 0 and 1. The
+%      portion of the held-out test set will be the complement of this
+%      number to 1, duh.
 %
 training_set_size(1.0).
 
 
 %!     transformation_format(?Format) is det.
 %
-%      New config option to subsume production_composition/1,
-%      production_augmentation/1 and hopefully also output_format/2 and
-%      output_type/1.
-%
-%      The point of this one is to determine what the skeleton graph
-%      will be transformed to. Note that this is not just grammars any
-%      more- with the skeleton graph output as a literal predicate, we
-%      can output DCGs and Prolog but also a set of features for
-%      classifiers etc. The sky's the limit. Well, at least I hope so.
+%      The type of the grammar (or other structure) to be learned.
 %
 %      One of:
 %      * right_regular; edges of the skeleton graph will be transformed
-%      into a right-regular grammar of the form:%
+%      into a right-regular grammar of the form:
 %      ==
 %      S --> A
-%      A --> a
-%      A --> aB
+%      A --> a*B
+%      A --> epsilon
 %      ==
-%      Implies output_type(dcg) (ie, a grammar in Definite Clause
-%      Grammar format).
 %
 %      * stochastic_right_regular; as right_regular but productions are
 %      also weighted with probabilities added as an argument to their
-%      head rule calculated by a predicate call in their body for
-%      example:
+%      head. The probabiliyt of a string is calculated by a predicate
+%      call embedded in production bodies, for example:
 %      ==
 %      a(P) --> [a], b(P1), { P is 0.3 * P1}
 %      ==
@@ -574,6 +633,14 @@ training_set_size(1.0).
 %      -recursions (as the right-regular formalism also does). Also:
 %      cool name, obviously.
 %
+%      * stochastic_gnf; as gnf, but productions are also weighted with
+%      probabilities, added as arguments to their head. A predicate
+%      call is embedded in the body of productions to calculate the
+%      probability of a string.
+%
+%      @tbd Options stochastic_right_regular and stochastic_gnf will
+%      probably only work with output_type(dcg). But maybe not.
+%
 %transformation_format(stochastic_gnf).
 %transformation_format(gnf).
 transformation_format(right_regular).