BP_BIBLIO(1p)						User Contributed Perl Documentation					     BP_BIBLIO(1p)

NAME

       biblio.PLS - bioperl client for accessing and querying a bibliographic repository.

SYNOPSIS

       Usage:

	 biblio.PLS [vh]
	 biblio.PLS [bcFgOpq]	      [-l <URL>]
	 biblio.PLS [abcdDeFknmOpqrs] [-l <URL>] -i <collection-ID>
	 biblio.PLS [abcdDeFknmOpqrs] [-l <URL>] - -find <keywords> 
		[-attrs <attrs>]...
	 biblio.PLS [Vq]	      [-l <URL>]
	 biblio.PLS [FOq]	      [-f <filename>]

DESCRIPTION

       A client showing how to use Bio::Biblio module, a module for accessing and querying a bibliographic repository.	It also shows how to use
       modules Bio::Biblio::IO::medlinexml Bio::Biblio::IO::medline2ref which converts XML MEDLINE citations into a simple hash table and into
       full Perl objects.

       It has many options in order to cover as many methods as possible.  Because of that, it can be also used as a fully functional command-line
       client for querying repository and retrieving citations from it.

OPTIONS

   What service to contact:
	 -l <URL> ... a location where a Bibliographic Query service is
		      provided as a WebService
		      (default: http://www.ebi.ac.uk/openbqs/services/MedlineSRS)

   What query collection to use:
       Some options do not need to specify a collection, some do.

	 -i <collection_id>  ... the collection ID can be obtained in a
				 previous invocation by specifying argument
				 '-p' (print ID)
	 -find <keywords> [-attrs <attrs>]
			     ... create a collection from citations
				 containing given keywords - either in all
				 default attributes, or only in the given
				 attributes;

				 it is possible to repeat it, for example:
				    -find brazma -attrs authors -find -study
				 (the repetitions refine previous results)
				 both <keywords> and <attrs> may be
				 comma-delimited multi-values;
				 note that '-find' must be separated from
				 the rest of options by '-';

				 note that this script is a bit stupid
				 regarding quoted keywords, or keywords
				 containing commans... TBD better

	 what XML format is used for citations:
	 -Fm	 ... MEDLINE (default)
	 -Fp	 ... PubMed

   What to do (with the query collection):
	 -g <id>    ... get citation <id>
	 -c	    ... get count (a number of citations)
	 -p	    ... print collection ID (which may be used in the next
			invocation as an '-i' argument); it implies also '-k'
	 -b	    ... print citations in a non-XML format (TBD)

       Other options can be used only on a sub-collection - which can be obtained directly by specifying '-i' argument, or indirectly by
       specifying one or more queries by '-find' arguments:

	 -d	    ... get all citation IDs
	 -n	    ... get next citation
	 -m [<how_many>] ... get 'how_many' more
	 -r	    ... reset iteration to the first citation in the collection
			(now you can use '-n' or '-m' again)
	 -a	    ... get all citations - as an array
	 -s	    ... as '-a' but get it as one string
	 -e	    ... check if given collection exists and has more citations
	 -k	    ... keep resulting collection persistent (makes sense only
			when collection IDs are being printed otherwise you
			would not know how to contact the persistent collection
			next time)
	 -D	    ... destroy given collection (makes sense together with '-i')

       Options specifying output format of the results:

	 -Ox	    ... output in XML format (default)
	 -Oo	    ... output as Biblio objects
	 -Or	    ... output as a raw hashtable

	 The options above can be used also for converting an XML MEDLINE
	 local file without using any SOAP connection at all;

	 -f <filename> ... an XML file to be read and converted

       Options dealing with controlled vocabularies:

	 -Vn		      ... get all vocabulary names
	 -Vv::<name>	      ... get all values from vocabulary <name>
	 -Va::<name>	      ... get everything from vocabulary <name>
	 -Vd::<name>::<value> ... get description of <value>
				  from vocabulary <name>
	 -Ve::<name>::<value> ... return 1 if <value> exists
				  in vocabulary <name>

       And the remaining options:

	 -h  ... get help
	 -v  ... get version
	 -q  ... be quiet (less verbose)

EXAMPLES

	 biblio.PLS - -find Java -attrs abstract -find perl

       Several separate invocations sharing the same query collection:

	 biblio.PLS -p -q - -find Brazma,Robinson > b.tmp
	 biblio.PLS -i `cat b.tmp` -d
	 MEDLINE2005/10693778
	 MEDLINE2005/10977099
	 MEDLINE2005/11726920
	 MEDLINE2005/12225585
	 MEDLINE2005/12227734
	 biblio.PLS -i `cat b.tmp` -g 10693778
	 <MedlineCitation Status="Completed">
	  ...
	 </MedlineCitation>

	 biblio.PLS -i `cat b.tmp` -e
	 Exists: 1	 Has next: 1

	 biblio.PLS -i `cat b.tmp` -D
	 Destroyed OK.

	 biblio.PLS -i `cat b.tmp` -e
	 Exists: 0	 Has next: 0

       Access to controlled vocabularies:

	 biblio.PLS -Vn
	 MEDLINE2005/JournalArticle/properties
	 MEDLINENEW/resource_types
	 MEDLINE2005/resource_types
	 MEDLINE2005/Person/properties
	 MEDLINE2005/*/publication_type
	 MEDLINENEW/JournalArticle/properties
	 repository_subsets
	 MEDLINE2005/*/citation_subset

	 biblio.PLS -Vv::MEDLINE2005/JournalArticle/properties
	 AllText
	 ID
	 PMID
	 ISSN
	 ...

       Converting local XML MEDLINE file:

	 biblio.PLS -g 10693778 > a_file.xml
	 biblio.PLS -f a_file.xml -Oo	... to Perl objects
	 biblio.PLS -f a_file.xml -Or	... as a raw hash

ENVIRONMENT VARIABLES

	 HTTPPROXY = <HTTP proxy server>

       Use this if you use this script on a machine which needs to access remote HTTP targets via a proxy server.  For example:

	 export HTTPPROXY=http://128.243.220.41:3128
	 biblio.PLS -c

FEEDBACK

   Mailing Lists
       User feedback is an integral part of the evolution of this and other Bioperl modules. Send your comments and suggestions preferably to the
       Bioperl mailing list.  Your participation is much appreciated.

	 bioperl-l@bioperl.org			- General discussion
	 http://bioperl.org/wiki/Mailing_lists	- About the mailing lists

   Reporting Bugs
       Report bugs to the Bioperl bug trackingi system to help us keep track of the bugs and their resolution. Bug reports can be submitted via
       the web:

	 https://redmine.open-bio.org/projects/bioperl/

AUTHOR - Martin Senger
       Email martin.senger@gmail.com

HISTORY

       Written February 2002 Updated July 2005

perl v5.14.2							    2012-03-02							     BP_BIBLIO(1p)