.de Sp .if n .sp .if t .sp 0.4 .. .TH CLEVER 1 "May 1994" .SH NAME clever, nclever \- "Command-Line Entrez VERsion" .SH SYNOPSIS .B clever [-b] .br .B nclever [-b] .br .SH DESCRIPTION Clever is a tty-based version of NCBI's Entrez program. It is an interactive tool that allows easy browsing of the Entrez database. For more information about Entrez, see the Entrez manual, or write to entrez@ncbi.nih.nlm.gov. The original Entrez Browser program written by NCBI is a tool that uses windows, menus, and a pointing device; since not everyone yet has computers or terminals with graphics capabilities, clever was written to do the same work using only text input/output. Clever can do almost everything the browser version can do, and some more. See the section called CLEVER AND THE ENTREZ BROWSER for a more complete comparison between these two Entrez database access tools. .LP In addition, the clever program permits BATCH access to the Entrez databases. Thus by use of script files, clever can be made to perform queries in batch mode. In this way clever can be used as a "search engine" for any application which has as its input a set of database queries in clever format and can use as output any of the data in the Entrez databases (in any of the various formats supported by Entrez). .LP Clever's user interface is command-line based (thus its name). The user is presented with a prompt at which he/she types a command. Some commands perform searches in the Entrez databases, while others set options, display records, or save information in files. .LP Clever can be compiled to access the CD-ROM version of the Entrez database as well as the Network version of this database. The behavior of the two versions is identical to the user; use of the STATUS command indicates which version is currently in use. .LP .SH "THE -b SWITCH" The "-b" (for "batch") command-line switch globally affects the way warning messages (and other outputs of some commands) appear; when supplied it turns OFF an internal parameter called VerboseMode. It can alse be toggled on and off with the Option command. See the description for this command and the section USING CLEVER IN BATCH MODE. Two very noticable effects of turning off VerboseMode is to disable the printing of the information seen when starting, and the complete absence of the interactive prompt! .LP .SH "THE MAIN LISTS" The program manages two main lists. The first one is a list of terms, supplied by the user. It is the equivalent of the "Query Refinement" subwindow in the Entrez Browser. Each term is a search string used to query one of Entrez's indexes. They can be grouped together to make conjunctive or disjunctive queries. Clever computes the other list, called the current documents list, from the list of terms, every time the list of term is changed. When doing neighboring or lookups, the current list of documents can become quite different from what is specified in the list of terms. The two lists have their own "current database" associated with them. The term list database is changed with the database command, while the curent documents database is usually the same as the term list database except when doing neighborings, when it may change. .LP .SH COMMANDS Commands are described here; they are entered after clever's prompt, which is "CLEVER> ". Arguments to commands are separated by white spaces (that is, blanks or tabs) and sometimes can also be separated by commas. All commands can be abbreviated to the minimum number of characters necessary to resolve ambiguity with other commands. They are not case- sensitive. .LP INFORMATION COMMANDS .TP 5 About Displays the version and authorship of the program; an abbridged version of this message is also displayed once at the begining of each invocation of clever if VerboseMode is true. .LP .nf Help [command] Man [command] ? [command] .fi .in +5 Without arguments, displays a list of all commands with a short description of each. If the name of a command is supplied as argument, displays more information about that command. .LP .TP 5 Status Reports miscellanous Entrez database information. .LP CONFIGURATION COMMANDS .TP 5 Option [[no|!]optname] [no|!]optname...] This commands set/resets options that change the behavior of other commands and of the program generally. With no arguments, it displays the current values of all options. There are two kind options: boolean and integer. Boolean options are set to TRUE simply by supplying their names as argument to the command, and set to FALSE by prefixing them with the letters "no" or by a "!". For example, .Sp CLEVER> Option TruncationMode .Sp sets the option TruncationMode to TRUE while .Sp CLEVER> Option noTruncationMode .Sp sets it to false. There is currently only one integer option, and it is called CharsPerLine. It is set to a value by supplying a number ofter the option name, like in: .Sp CLEVER> Option CharsPerLine 80 .Sp Many options can be set/reset on the same command-line; they are not case-sensitive and they can all be abbreviated to the minimum number of characters necessary to distinguish between them. All options have default values, which can be saved to the user's clever configuration file (see the section THE CLEVER CONFIGURATION FILE). .Sp Here is a description of all possible options: .nf .Sp [no]MEDAbstract .br [no]MEDGenes .br [no]MEDMesh .br [no]MEDSubstances .Sp .fi These four options selectively enable/disable displaying parts of the MEDLINE records when the REPORT format is chosen (see the ARTICLE command). .Sp CharsPerLine .Sp This option tells clever to use a display width of characters. It affects the displaying of records in Report format, and the output of the ABOUT command. .Sp [no]ParentsPersist .Sp This option tells clever to always include a copy of the records that were selected for neighboring when returning a list of their neighbors. When listing the current documents list, a "*" is shown beside the parents documents. .Sp [no]ShowSequences .Sp This option turns on or off the displaying of sequences when showing records of the Protein or Nucleotide database in Report format. When set to "FALSE", the words "(not shown)" are displayed in the sequence field rather the the sequence itself. .Sp [no]MultipleMode .Sp This option affect all search commands. When set to TRUE, the search commands will parse their arguments, separating them at white spaces, and making a query for each of them. When set to FALSE, everything after the search command is considered part of the query, INCLUDING the white spaces. Therefore, in the first case, a query of the form .Sp CLEVER> Author Struhl K .Sp will try to search for "Struhl" and then for "K", which might not be what the user wanted; rather, setting NOMultipleMode will look for "Struhl K". .Sp [no]TruncationMode .Sp This option affects all search command. When set to TRUE, all queries will be made in Truncation Mode, that is, the search string will be interpreted as a prefix of what is looked for. In that case, reported entries are shown with a "..." appended to the search string. When set to FALSE, an exact match between the search string and the indexed terms of entrez is expected. .Sp [no]FetchSpecial .Sp This option affects search commands that uses both the TOTAL and SPECIAL indexed terms. When set to TRUE and doing a search on the total field, the number of entries indexed with the special field will also be displayed. When set to FALSE, the user has to make an explicit query for the number of entries in the special field if he/she wants to get them, using the -s option of the search command. See the introduction to the search commands for more information. .Sp [no]AllowNull .Sp This option affects all search command. When set to TRUE, all queries that return an empty list of document will still create an entry in the current list of terms. This behavior is useful when using CLEVER in batch mode; when using it interactively this option is better set to FALSE. The default is FALSE. .Sp [no]VerboseMode .Sp This option affects many commands. It basically toggles the displaying/nondisplaying of warning messages. Usually it is set to TRUE for interactive query of the database, and set to FALSE on invocation (using to -b command-line option) when clever is used in BATCH mode, doing automatic retrieval from the Entrez database under script control. In that case, clever only to produces useful information when the script is run, so the displaying of the prompt and the initial welcome message are also disabled. See the section USING CLEVER IN BATCH MODE for more information. .Sp Save .Sp This is not really an option. This tells clever to write out the current setting of all the options to clever's configuration file. See the section THE CLEVER CONFIGURATION FILE for more information. .Sp OPTIONS DEFAULTS: .Sp Medline Report display options: .br \- MedAbstracts = TRUE .br \- MedMesh = TRUE .br \- MedGenes = TRUE .br \- MedSubstances = TRUE .Sp Miscellanous options: .br \- CharsPerLine = 60 .br \- ParentsPersist = TRUE .br \- ShowSequences = FALSE .br \- MultipleMode = TRUE .br \- TruncationMode = TRUE .br \- FetchSpecial = TRUE .br \- VerboseMode = TRUE .TP 5 Database [database name] This command sets the current terms lookup database to either "medline", "protein" or "nucleotide". Note that changing database implies doing a RESET of the current search environment: all searched terms are cleared and the current document list and it's neighboring history too. The default database is Medline. Without arguments, shows the current list of terms database. .TP 5 Article [article format] This command sets the format in which medline articles are displayed. If no arguments are supplied, it shows what format is currently chosen. Possible formats can be shown by supplying a question mark to the command (or anything else that is not a legal article format). .TP 5 Report [sequence report format] This command sets the format in which sequence records are displayed. If no arguments are supplied, it shows what format is currently chosen. Possible formats can be shown by supplying a question mark to the command (or anything else that is not a legal sequence format). .TP 5 Class [sequence level] This command tells clever what level of complexity of the sequence to display. Possible levels are NucProt, SegSet and BioSeq, according to NCBI's internal data structures for representing set of sequences. If no arguments are supplied, it shows what level is currently chosen. Possible levels can be shown by supplying a question mark to the command (or anything else that is not one of the three keywords just mentionned). .LP SEARCH COMMANDS .LP .nf [term2] [term3]... (MultipleMode=TRUE) (MultipleMode=FALSE) .fi .in +5 All search commands do the same thing: search for one or more terms in the indexes of the Entrez databases, and if the operation is successful, add each term in the current list of terms at which point they can be grouped together, excluded, etc. There are twelve search commands that are used to search through ten fields (the difference between the numbers come from the fact that some search commands are variants of others). Some fields are indexed in two subfields: a Special subfield and a Total subfield. Search commands always use the Total subfield (except for the Title command, see below), unless they are followed by the characters "-s" to force a search on the special field; if the option FetchSpecial is TRUE and the "-s" is absent, then the Special subfield will be reported as well as the total subfield. .Sp Beside FetchSpecial, two other options affects searching. MultipleMode forces all search commands to make a query for each space-separated argument given to them; when MultipleMode is FALSE, spaces become significant in queries. TruncationMode allows queries to be made on prefixes of indexed terms, for example, a query on the characters "cox" will effectively match "cox1", "cox2", etc. .Sp Some search commands apply to only some of the three Entrez databases. They are: .nf .Sp Accession - Select SEQUENCE documents by accession number. Author - Select documents by author. Date - Select documents by date. Ecnumber - Select MEDLINE or PROTEIN documents by E.C. Number. Gene - Select documents by gene name. Journal - Select documents by journal title. Keyword - Select SEQUENCE documents by keyword. Mesh - Select MEDLINE documents by MESH terms. Organism - Select SEQUENCE documents by organism name. Pname - Select PROTEIN documents by protein name. Substance - Select MEDLINE documents by substance name. Text - Select documents by text term. Title - Select MEDLINE documents by titles. .Sp .fi The index of the date command contains years like "1968" and combination of years and month like "1995/01". .fi Note that "Title" is a perfect synonym of "Text -s" and that the "Keyword" and "Substance" search commands are synonymous (the Entrez Browser used the word "Substance" when accessing the Medline database, but it really is using the "Keyword" index). .Sp When a term has been added the list of terms, the current document list is updated, and its associated database is set to the list of term's database. .LP NEIGHBORING COMMANDS: .TP 5 [num2] [num3] The commands "Neighbors", "Medline", "Protein" and "Nucleic" are used to do neighboring and lookup (see below) searches. When supplied as arguments with a list of numbers corresponding to documents in the current documents list, they retrieve the set of "similar" documents (precomputed in the entrez database; see the Entrez documention for how these indexes are built). This set then becomes the new current list of documents. "Neighbors" are similar records in the same database as the current list. The other commands ("Medline", "Protein" and "Nucleic") specify another database (or the same) in a more explicit manner (see LOOKUPS below). If the ParentsPersist option is TRUE, the documents used for neighboring will be included at the top of the new list, and marked with an "*" when listing it. Special recognised arguments are ALL for "all documents" and PARENTS for "parents documents" (they can be abbreviated to "A" and "P"). .Sp LOOKUPS .Sp Unlike the Entrez Browser, Clever does not have a lookup command. Instead, lookups are performed by specifiying the database to be accessed and the documents from the current list to be looked up in that database. Thus lookups are performed as described above for "NEIGHBORING" but apply only when the "Medline", "Protein" and "Nucleic" commands are used and when the most recent document list applies to a database different from the one specified in the command. For instance, if the Medline database had just been searched and the nucleic acid entry for the first entry was desired, the command .Sp CLEVER> nucleic 1 .Sp would retrieve that entry. On the other hand, if the neighbours to this document were desired, the commands: .Sp CLEVER> medline 1 .Sp or .Sp CLEVER> neighbor 1 .Sp would have both retrieved the neighbors to the first document on the list. .LP HISTORY COMMANDS: .LP .nf History Previous Next .fi .in +5 When doing neighboring, the current list changes as the user browses lists of documents. Clever keeps a history of the changes, and the user is able to go back to previously fetched document lists with the "previous" command. The "next" command goes forward in the history list. The "history" command shows a summary of that list. Note that Modifying the term list doesn't automatically update the history list, until an explicit access to the history list is done with one of the history command. .LP TAXONOMY COMMANDS: .LP .nf Taxonomy List Taxonomy Down Taxonomy Up [num] Taxonomy Add [num] .fi .in +5 These commands allows the user to browse the two taxonomic trees available with the the two sequence databases. The "List" command shows information related to the current node in the tree: its lineage and the name of all its children along with the number of documents found in the current sequence database. Taxonomy starts by default at the "root" of the tree, which is by convention at the 'top' and is its 'highest point'. The "Down" command allows the user to go to child number (as reported by the "List" command) of the current node. The "Up" command does the inverse; if a is supplied, the user climbs back the tree up to the lineage level with that number. The "Add" command puts the list of documents specified by children into the current list of term, exactly like the search commands. If the current node in the tree is already a leaf and has therefore no children, then doesn't need to be specified. .LP MISCELLANOUS COMMANDS: .TP 5 List [num] Shows a summary of the current list of documents. Since this list can be very long, the default shows only the first 20 documents. When given a number N as argument, a summary of the first N documents are shown. Special arguments are "A" and "P"; see the NEIGHBORING COMMANDS subsection. .TP 5 [num1] [num2] [num3]... These commands are used to manipulated the terms in the list of terms. They take a list of numbers as arguments, each number corresponding to one of the terms shown by the list command. Since version 3.02, the "all" keyword can also be used to specify "all terms in the current term list". .Sp The "Pick" commands selects and unselects individual terms; an unselected term is shown with nothing in front of it when the list of term is displayed with the "List" command, while a selected one is shown with a "<" sign (unless grouped with the "Union" command). A negative number -n means to UNpick the term number n. Unselected term are completely ignored for the purpose of building the list of documents. .Sp The "Union" commands groups all the terms whose numbers are supplied in argument. Groups of one term are shown with a "<" sign in front of them, like a one-line bracket, while larger groups are shown with the characters "/", "|" and "\\" which visually appear as larger brackets. Picking or unpicking single terms can be used to break-up a group. .Sp The "Not" command can only be used on groups of one term. It is used to do boolean NOTS of terms. Such terms are shown with a "-" sign in front of the single "<". A negative number -n means to remove the boolean NOT associated with the terms numN. .Sp The "Pick" command interprets "Pick 0" as "unpick all". Note that grouping terms together with "Union" can move the terms around in the list (this doesn't apply to the "Pick" or "Not" commands). .Sp Examples: .Sp CLEVER> pick 2 -5 3 CLEVER> union 2 4 6 CLEVER> not 1 3 -5 .Sp Evaluation of the boolean expression built by PICKing, UNIONing and NOTing terms is done in the following manner: first all groups made with the "Union" command are evaluated as ORs of the lists of documents specified by the terms. The groups are then ANDed together and finally, the single NOTed groups are substracted from that result. Therefore, a list of 8 terms like this: .Sp \-< 1 Term1 < 2 Term2 / 3 Term3 | 4 Term4 \\ 5 Term5 \-< 6 Term6 / 7 Term7 \\ 8 Term8 .Sp can be interpreted as the boolean expression .Sp ((2) AND (3 OR 4 OR 5) AND (7 OR 8)) AND (NOT 1) AND (NOT 6) .Sp When no argument is supplied, these commands show the current list of terms. .Sp When a change has been made to the list of terms, the current document list is updated, and its associated database is set to the list of term's database. .TP 5 [Type] [num2] [num3]... This command displays one or more documents from the current list of documents. It takes numbers as arguments to specify which documents to show. Special arguments are "A" and "P"; see the NEIGHBORING COMMANDS subsection. The format of the displayed documents depend on the settings of the "Article" or "Report" commands. The "type" itself is optional, since clever will recognize a command that starts with a digit as an abbreviation for "type". .TP 5 UID [uid2] [uid3]... This command doesn't affect any of the internal lists. It simply displays one or more documents from the current term database, specified by their UIDs. It therefore assumes that the user knows the correct uids. As for the "type" command, the format of the displayed documents depend on the settings of the "Article" and "Report" commands. .TP 5 File [ [modifiers]] This command tells clever to send the useful output of other commands (like "list", "type", etc) to a file. With no argument it returns the output to the user's stream. When a file is supplied as argument, the output of the following commands are sent to the file name specified, and nothing will be displayed on the screen. Some one-letter modifiers can be specified after the filename. An "A" means Append to the file. A "1" means redirect the output for the next command ONLY, not all the following commands. It is possible to do a one-command-only redirection (with modifier "1") while the general output has already been redirected somewhere else. This features is used by the "save" and "print" commands. .TP 5 Save [num2] [num3]... This commands does the same thing as the "type" command, but send its ouput to "filename". It is the same as doing "File 1" followed by "Type [num2] [num3]...". .TP 5 Print [num2] [num3]... This command does the same thing as "save", but sends its output to the printer. The output is saved in a temporary file and that file is printed using the PRINT COMMAND configuration in the user's clever configuration file. See the section called THE CLEVER CONFIGURATION FILE. This command is implemented only for UNIX systems. .TP 5 Reset This command discards the current list of documents, its history list, and the current list of terms. It leaves all configuration setting unchanged (current term database, record formats, etc). .TP 5 Saveuids This command saves the list of all the uids of the current documents list to the file filename. .TP 5 Loaduids This command reloads a list saved by the "saveuids" command. It adds the list to the term list, as if it was a legal searched-for term. The loaded list must be a list of uids from the same database as the list of term's database (see the "database" command). .LP .nf Exit Quit .fi .in +5 This exits from clever. .SH "USING CLEVER IN BATCH MODE" Since clever receives its command using the standard output and displays records to its standard output, it can be used as a tool to query the Entrez database automatically. One has simply to feed it the commands on its standard input and gather the results on its standard output. The "-b" (for BATCH) command-line switch can be used to turn off the internal option VerboseMode; this is advantageous in that it tells clever not to print a prompt for each command, which would clutter the output and render it difficult to parse by other programs. The -b switch also disables the display of the introductory message. Therefore, building a scriptfile like this one: .LP .nf Database Medline Article ASN Author Struhl Type 1 .fi .LP and feeding it to clever with "clever -b