Netica-J Reference Manual
Contents
1. from a file of cases import java io File import norsys netica public class LearnCPTs public static void main String args System out printin Running Netica J LearnCPTs example try Environ env new Environ null Read in the net created by the BuildNet java example program Net net new Net new Streamer AsiaEx dne NodeList nodes net getNodes int numNodes nodes size Remove CPTables of nodes in net so new ones can be learned for int n 0 n lt numNodes n Node node Node nodes get n node deleteT ables Read in the case file created by the SimulateCases java example program and learn new CPTables Streamer caseFile new Streamer AsiaEx cas net reviseCPTsByCaseFile caseFile nodes 1 0 net write new Streamer Learned_AsiaEx dne net finalize catch Exception e e printStackTrace JAVA VERSION 2 20 NETICA API 17 This alternate way can replace the net reviseCPTsByCaseFile line above if you need to filter or adjust individual cases y long casePosn new long 1 casePosn 0 Net FIRST_CASE while true net retractFindings net readCase casePosn caseFile nodes null null if casePosn 0 Net NO_MORE_CASES break net reviseCPTsByFindings nodes 1 0 casePosn 0 Net NEXT_CASE2. directory The javadocs very thoroughly document every class and every function of the Netica API You will find it an invaluable companion during development 1 7 Customized Installation Considerations Using Java IDEs VisualAge JBuilder JDeveloper Forte etc You must inform your IDE of the locations of the three library files NeticaJ dll or so Netica J jar and Netica dll so Assuming Netica J was installed at the following location on your filesystem Windows C NeticaJ_220 Unix Linux hnome NeticaJ_220 1 NeticaJ dll so must appear on the java library path Typically this is done with a D option to the JVM For example Windows java Djava library path C NeticaJ_220 bin Unix Linux java Djava library path home NeticaJ_220 bin 2 Netica J jar must appear on the java CLASSPATH For example Windows java classpath C NeticaJ_220 bin Netica J jar Unix Linux java classpath home NeticaJ_220 bin Netica J jar 3 Netica dll so must appear on the Windows Unix Linux execution path so that Windows Unix Linux can find it For example Windows set PATH C NeticaJ_220 bin SPATH Unix Linux setenv path home NeticaJ_220 bin Spath 1 8 Feedback welcome We at Norsys have worked hard to make Netica J a very high quality and robust package that is easy and natural to use If you have any ideas for how it can be improved please send your suggestions to netica j norsys com 1 9 Join the Netic
3. Tuberculosis or Cancer visitAsia state visit setTitle Visited Asia within the last 3 years tuberculosis addLink visitAsia puts link from visitAsia to tuberculosis cancer addLink smoking tbOrCa addLink tuberculosis tbOrCa addLink cancer xRay addLink tbOrCa visitAsia setC PTable 0 01 0 99 smoking setCPTable 0 5 0 5 NVisitAsia present absent tuberculosis setCPTable visit 0 05 0 95 tuberculosis setCPTable no_visit 0 01 0 99 Smoking present absent cancer setCPTable smoker 0 1 0 9 cancer setCPTable nonsmoker 0 01 0 99 ToOrCa abnormal normal xRay setCPTable true 0 98 0 02 xRay setCPTable false 0 05 0 95 tbOrCa setEquation TbOrCa Tuberculosis Cancer Tuberculosis Cancer tbOrCa equationToTable 1 false false Streamer stream new Streamer AsiaEx dne net write stream net finalize free resources immediately and safely not strictly necessary but a good habit catch Exception e e printStackTrace After this program executes you may want to look at the AsiaEx dne file it creates using a text editor 14 NETICA API JAVA VERSION 2 20 3 2 Performing Probabilistic Inference The following program can be found in the examples directory of your Netica J installation It reads back into memory the AsiaEx dne file created above and then does probabilistic inference on the net For additional information on th
4. Netica J Manual Version 2 20 and Higher Java Version of Netica API Norsys Software Corp 2 NETICA API JAVA VERSION 2 20 Netica J Reference Manual Version 2 20 May 7 2002 Copyright 2002 by Norsys Software Corp This document may be copied and stored freely provided it is duplicated in its entirety without modification and including the copyright notice Published by Norsys Software Corp 2315 Dunbar Street Vancouver BC Canada V6R 3N1 www norsys com Netica and Norsys are registered trademarks of Norsys Software Corp Microsoft Windows Windows NT and MS DOS are registered trademarks of Microsoft Inc Sun and JAVA are registered trademark of Sun Microsystems Inc Unicode is a trademark of Unicode Inc PostScript and PDF are registered trademarks of Adobe Systems Inc Other brands and product names are trademarks of their respective holders While great precaution has been taken in the preparation of this manual we assume no responsibility for errors or omissions Neither is any liability assumed for damages resulting from the use of the information contained herein JAVA VERSION 2 20 NETICA API 3 1 Introduction This reference manual is for Netica J the Java version of the Netica API Programmer s Library It is meant to be used in conjunction with the onscreen Netica J javadocs reference see below Netica J is a set of Java classes and an accompanying Java Native Interface JNJ library that allo
5. a J Mailing List If you would like to be notified of version updates and other new regarding Netica J please visit https www norsys com mailing_list html interests Netica J and supply us with your e mail address Mailings are infrequent 8 NETI CA API AVA VERSION 2 20 2 Netica J Package Design and Usage This section outlines programming principles and issues as they relate to Netica J s operation and organization If you are an experienced Java developer or are planning a sizeable development effort with Netica J you will definitely want to read and understand this section before beginning your design 2 1 The Ex classes NetEx NodeEx and NodeListEx The Ex classes inherit from their parent class NodeEx extends Node NetEx extends Net etc They do not offer any additional constants or instance variables All they offer is additional functionality the Ex stands for Extra Example External Experimental and Excellent These are utilities and convenience methods that were deemed useful but not basic enough to belong in the base class Some of them are Ex methods because they are more useful in source code form so that you can customize them to your needs Because their Java source is included the Ex classes are a good place to look for coding examples Indeed many of the coding examples found in the javadocs are taken from the Ex classes The Ex classes may change in
6. a directory called NeticaJ_220 or the current version number Test your installation with the Demo application provided a Change to the demo directory and at the command line type compile bat Or click on the compile bat icon This will compile Demo java and create Demo class b At the command line type run bat Or click on the run bat icon This will run Demo class c If it displays a welcome message and does simple probabilistic inference without declaring any errors then your installation was probably successful Now that you have the example program running you can duplicate the demo directory replace Demo java with your own source files and you are ready to build your own application Don t forget to replace null in new Environ null with your own license password if you want to have the full functionality of Netica Demo java is a good starting point for developing your own applications You may wish to cut and paste from it Similar examples showing how to build a net from scratch do inference generate cases and learn from cases are provided in the examples directory If you are familiar with the Hugin or JavaBayes systems and would like information on equivalent Netica functions contact Norsys J AVA VERSION 2 20 NETICA API 7 1 6 Complete Javadocs Reference For javadocs style documentation for Netica J simply point your browser at the index html file in the docs javadocs
7. an be found in the examples directory of your Netica J installation It builds the following Bayes net in memory Visit To Asia Smoking Visit 1 0 Smoker 50 0 No Visit 99 0 pam NonSmoker 50 0 Tuberculosis Lung Cancer _ Present 1 041 Present 5 50 Absent 99 0 Absent 94 5 Tuberculosis or Cancer True 6 48 False 93 5 XRay Result Abnormal 11 0 Wm Normal 89 0 For additional information on this topic see the Building and Saving Nets chapter in the C API Manual ii BuildNet java Example use of Netica J to construct a Bayes net and save it to file ii import norsys netica import norsys neticaEx aliases Node public class BuildNet public static void main String args try Node setConstructorClass norsys neticaEx aliases Node Environ env new Environ null Net net new Net net setName AsiaEx Node tuberculosis new Node Tuberculosis present absent net Node smoking new Node Smoking smoker nonsmoker net Node cancer new Node Cancer present absent net Node tbOrCa new Node TbOrCa true false net Node xRay new Node XRay abnormal normal net Node visitAsia new Node VisitAsia visit no_ visit net JAVA VERSION 2 20 NETICA API 13 visitAsia setTitle Visit to Asia cancer setTitle Lung Cancer tbOrCa setTitle
8. ative interface library dll for Windows so for Unix Linux e the native Netica API library Windows only e A class containing useful Net methods e oe ee Node ee e NodeList e A convenience class that renames NodeEx as Node S NetEx as Net g3 g3 g3 e NodeListEx as NodeList e a sample application to test your Netica J installation e a sample batch file for compiling Demo java bat for Windows sh for Unix Linux e a sample batch file for running Demo class bat for Windows sh for Unix Linux e demonstrates building a Bayes net from scratch e demonstrates doing inference e demonstrates creating case instances that statistically derive from a given net e demonstrates learning from cases e an example net file required by SimulateCases java and LearnCPTs java e a sample batch file for compiling all the java files in this directory e a sample batch file for running all the java programs in this directory after they have been compiled The Netica J directory structure The doc directory contains manuals javadocs license agreements and any other documentation The bin directory contains the Netica J runtime software without which Netica J will not function The sre directory contains source software that is distributed with Netica J You are free to examine compile or copy from these source files We suggest that you leave the original files unmodified These functions may change in future version o
9. ces discussed in the Finalizers section below or when working in a Model View Controller MVC environment where things could be happening to the native model objects and the Java environment is presenting but one view on that model This can happen for instance if Netica J is communicating with peer objects inside Netica Application A user of Netica Application could delete a native node via the GUI and the Java environment would then find that its Node object had been disconnected from its peer Netica J has a standard Java Publish and Subscribe mechanism using NeticaEventListeners for Java objects to be made aware of such occurrences on the native side of the universe see the Event Handling section below 2 3 Exception Handling Exception handling in Netica J works in the normal Java way If a method encounters an unexpected situation it cannot resolve a NeticaException is thrown The vast majority of Netica J methods are able to throw a NeticaException The toString method of NeticaException details the reason for the Exception Hence your typical try catch block will look something like this try call Netica J methods catch NeticaException e e printStackTrace If you are familiar with the Netica C API you will find that Netica J s exception handling mechanism makes coding much more convenient and straightforward since you no longer need to actively check if an error has occurred Netica J looks afte
10. e their javadocs pages for examples Some users will want to use the words Net and Node for their own net and node classes that inherit from norsys netica Net and norsys netica Node respectively The supplied files in src neticaEx aliases have examples of this Although overloading the terms Net and Node like this is not difficult namespace conflicts may arise In general if you explicitly import your Node or Net class the Java compiler will use those as the default classes 2 5 Event Handling If you wish your program to receive events Netica J has the ability to call your program when such events occur Any Java object can choose to listen to Netica events by simply implementing the NeticaEventListener interface and asking the node or net that generates the events to add itself to that node or net s listener list The methods Node addListener and Net addListener are supplied for this purpose Since Node and Net objects are already NeticaEventListeners they each possess an eventOccurred NeticaEvent method If you should choose to override this method it is important that you call the base class method super eventOccurred event in your method so that this node or net will still be able to handle delete events properly Future versions of Netica J will include more types of events If you have a request please let us know J AVA VERSION 2 20 NETICA API 11 2 6 Multi threading If you are runn
11. f Netica The demo directory contains a simple program that should be compiled and run after installation to establish that your Netica J system is correctly installed and ready to use The examples directory contains assorted sample data and source code that you may examine copy and edit freely JAVA VERSION 2 20 NETICA API 5 1 4 License Agreement Before using Netica J make sure you accept the license agreement that is included with this package as file LicAgree txt If you have purchased the C version of Netica API you are entitled to the same rights and privileges with this Java version and the license password you were issued will work identically with Netica J The license password is provided to the constructor for Environ For example Environ env new Environ your unique license string If you do not have a license then you can simply supply null to the Environ constructor in which case Netica J will be fully functional except for the size of the Nets it can manage and the number of cases it can learn from at one time 6 NETICA API AVA VERSION 2 20 1 5 Getting Started Recommended Installation steps 1 A Java 2 platform is required There are many suppliers for example SUN Microsystems at http java sun com products Download Netica J from the Norsys ftp site ftp norsys com pub users norsys dl NeticaJ_Win zip or the version for your OS platform Unzip it and it will form
12. f that file T SimulateCases java Example use of Netica J for generating random cases that follow the probability distribution given by a Bayes net gi import java io File import norsys netica public class SimulateCases public static void main String args int numCases 200 System out printin Creating numCases random cases try Environ env new Environ null Read in the net created by the BuildNet java example program Net net new Net new Streamer AsiaEx dne NodeList nodes net getNodes new File AsiaEx cas delete AsiaEx cas may exist from a previous run Streamer caseFile new Streamer AsiaEx cas net compile for int n 0 n lt numCases n net retractFindings int res net generateRandomCase nodes 0 20 if res gt 0 net writeCase nodes caseFile n 1 0 net finalize catch Exception e e printStackTrace 16 NETICA API JAVA VERSION 2 20 3 4 Learning CPTs from Cases The following program can be found in the examples directory of your Netica J installation It learns the CPTables not structure for a net structurally identical to AsiaEx dne from the case file temp cases generated by the SimulateCases program above For additional information on this topic see the Learning From Cases chapter in the C API Manual i LearnCPTs java Example use of Netica J for learning the CPTs of a Bayes net
13. future versions methods may be added removed or modified For this reason you may want to keep copies of the Ex classes for future reference or you may want to copy out any methods you need to form your own extensions of the parent classes Since the Ex classes contain so many useful methods many users will want to use the Ex classes in place of the more basic parent classes See Section 3 Inheritance below for considerations when doing this The Ex classes are meant to be supported by the entire community of Netica J users so please feel welcome to submit additional methods that you have found useful or to suggest improvements to the ones already there Some of the Ex class methods are static while others are not The basic criterion of choosing to make a method static was whether that method could be thought of as a standalone utility that would be useful to have around even when you didn t have an Ex object present Since none of the Ex classes define new state data it is a trivial exercise to convert a static method to be non static or vice versa should you prefer the alternate Because the Ex classes are so useful many developers will want to use them directly To make this easy their compiled classes have been included in the NeticaJ jar distribution All you need dois import norsys neticaEx and you are ready to use them without the need to compile your own versions of them F
14. inally as a convenience we also supply in the norsys neticaEx aliases package three wrapper classes for NetEx NodeEx and NodeListEx that are named Net Node and NodeList JAVA VERSION 2 20 NETICA API 9 respectively They allow you to use the base class names and still use the Ex classes See demo Demo java and examples BuildNet java for examples of how to use these convenience classes 2 2 Java objects and native object peers Since Netica J is a JNI API many of the Java objects created are proxies of their native or peer counterpart objects internal to the core Netica binary This is true of Environ Net Node NetTester NeticaError Sensitivity and Streamer The remaining Java classes Generic NeticaEvent NeticaException NeticaListener NodeList User Util and VisualNode do not have peer equivalents Those of you familiar with the Netica C API may be surprised that NodeList does not represent the native peer nodelist_bn This approach was chosen because nodelist_bn is simply a convenience collection and Java already has excellent collection classes that Java developers prefer to use The existence of peer relationships is usually transparent to the Java developer Netica J was designed to give the developer as much as possible the sense he she is working in a 100 pure Java environment The only situations where you need to know about peer objects is when considering finalization and the cleanup of native resour
15. ing Netica J within a single process and are not creating more than one thread in that process you needn t be bothered with this issue The large majority of users will fall in this category However if you are operating in a concurrent usage environment then please read on Netica J s approach to thread safety is to share the responsibility of thread safety with the developer Netica J guarantees thread safety whenever two threads are operating on two separate nets and also when two threads are operating on separate nodes or sets of nodes where the sets share no member nodes within the same net However in the case where two threads can operate on the same node simultaneously Netica J does not guarantee thread safety and so in this case only it is the responsibility of the developer to synchronize such code This compromise was made for efficiency reasons since it is very likely you will need to synchronize such code blocks anyhow in order to avoid situations where one thread is changing a node that another thread is simultaneously using 2 7 Finalizers amp Memory Management For large networks and large node tables Netica can consume large amounts of memory Often Java developers cease to worry about memory management as the JVM s garbage collector will automatically collect Java objects that can no longer be referenced However the Java specification does not require that a JVM actually call the garbage collector whenever a Ja
16. is topic see the Probabilistic Inference chapter in the C API Manual a Dolnference java Example use of Netica J for doing probabilistic inference g import norsys netica public class Dolnference public static void main String args try Environ env new Environ null Read in the net created by the BuildNet java example program Net net new Net new Streamer AsiaEx dne Node visitAsia net getNode VisitAsia Node tuberculosis net getNode Tuberculosis Node xRay net getNode XRay net compile double belief tuberculosis getBelief present System out printIn nThe probability of tuberculosis is belief xRay enterFinding abnormal belief tuberculosis getBelief present System out printIn nGiven an abnormal X ray n the probability of tuberculosis is belief visitAsia enterFinding visit belief tuberculosis getBelief present System out printin nGiven an abnormal X ray and a visit to Asia n the probability of tuberculosis is belief n net finalize catch Exception e e printStackTrace JAVA VERSION 2 20 NETICA API 15 3 3 Creating Cases The following program can be found in the examples directory of your Netica J installation It reads back into memory the AsiaEx dne file created from the BuildNet example above and then creates a case file of cases that follow the probability distribution o
17. r that for you and will throw a NeticaException automatically if any serious show stopper error occurs By serious we mean any errors of severity level ERROR_ERR or XXX_ERR which means the requested operation was not completed 10 NETICA API AVA VERSION 2 20 Note that this means that WARNING_ERR and lower warnings do not result in a NeticaException being thrown so in those cases where such warnings can occur you can actively call the static method NeticaError getWarnings after the method call to determine if a warning has occurred and if so what the warning was about See the javadocs for NeticaError getWarnings for examples of this It is okay to call NeticaError getWarnings only once in awhile since warnings will cumulate until the next getWarnings invocation whereupon they are cleared from the warnings list 2 4 Inheritance of the Node and Net classes Advanced users will want to create their own specialized Node and Net classes To make this task easier and avoid the need for copy constructors we have supplied you with a means to inform Netica J what class you would like it to use when constructing a Net or Node for example when Netica J is reading a net in from a file The static methods Net setConstructorClass String className and Node setConstructorClass String className have been supplied for this purpose All they require is that your Net or Node extension have a default constructor Se
18. va object reference goes out of scope It may or may not do so and it may choose to do so on its own schedule Accordingly you may want to actively call the delete or finalize methods on resource hungry objects when you are done with those objects rather than wait for the JVM to free them Note that with Netica J 2 20 Net delete has been merged into Net finalize so that calling Net finalize will now free all of a net s native resources This is not the case for Node Node finalize and Node delete remain distinct since you typically do not want a node s native resources to be freed just because the node is out of scope Call Node delete when you want to free its native resources Note if you do override the finalize method of any Netica J class be certain that you always call the base class finalizer method super finalize as your last instruction so that Netica J can do its own housekeeping upon the Java object being collected For example if your class extends norsys netica Streamer and you need to override the finalize method to perform special close down handling of files and such then your finalize method would look something like this overrides Streamer finalize 7 public void finalize throws NeticaException your own finalization logic super finalize 12 NETICA API JAVA VERSION 2 20 3 Sample Software 3 1 Building and Saving a Net The following program c
19. w a Java developer to use the Netica API Programmer s Library This manual assumes that you are familiar with the Java programming language It also assumes familiarity with Bayes nets Bayesian belief networks or influence diagrams Questions and comments about material in this manual may be sent to netica j norsys com 1 1 1 2 Netica J Features A complete implementation of the Netica API in Java A clean object oriented design A comprehensive installation guide and user s manual Sample applications to get you started Source code for dozens of powerful utility functions in Extra classes NetEx NodeEx and NodeListEx High performance relying on the same ultra reliable industrial strength computation engine in Netica s C API with hundreds of fielded applications over the past five years Written by Java developers for Java developers For instance it e Possesses a complete and thorough javadocs e Uses Java s exception handling mechanism in the natural way e Supports event listening by any Java object for events such as the creation deletion duplication etc of Nets or Nodes e Supports user data fields for any Serializable Java object e Supports multiple threads e Supports standard Java I O streams Thoroughly tested and reliable Comes at no extra cost with Netica API for other languages Works with your existing Netica API license with the same rights restrictions and support arrangements Download it from http w
20. ww norsys com netica j html In a version to be available soon it will have an interface to Netica Application allowing you to control the powerful GUI from Java and vice versa Netica Programmer s Library The Netica Programmer s Library also known as the Netica API is described thoroughly in the Netica API Programmer s Library Reference Manual C Version which is available for free download from http www norsys com netica_api html If you have never programmed Netica before you may want to read the first chapters of that manual first to familiarize yourself with the general operation of Netica before venturing to use Netica J 4 1 3 Files Included The following files are included in the distribution of Netica J the Java version of Netica API Directory doc bin src neticaEx src neticaEx aliases demo examples File e NeticaJ_Man pdf e javadocs e LicAgree txt e NeticaJ jar e NeticaJ dll so e Netica dll e NetEx java e NodeEx java e NodeListEx java e Net java e Node java e NodeList java e Demo java e compile bat sh e run bat sh e BuildNet java e DoInference java e SimulateCases java e LearnCPTs java e AsiaEx dne e compile bat sh e run bat sh NETICA API AVA VERSION 2 20 Description e this file e the javadocs directory for Netica J e a legal document relating to the use of Netica API e the Java class library that defines Netica J e the Java to N
Download Pdf Manuals
Related Search