Merchant of Venice, 0.51 alpha / 2/Apr/2005
===========================================

Copyright (C) 2003-5, Andrew Leppard (aleppard picknowl com au)
See COPYING.txt for license terms.

1 Introduction

Thank you for trying Merchant of Venice (Venice).

Venice is a stock market trading programme that supports portfolio
management, charting, technical analysis, paper trading and
experimental methods like genetic programming. Venice runs in a
graphical user interface with online help and has full documentation.
Venice runs on UNIX, including Mac OS X and Windows.

2 Preferences

2.1 Equations

You can store commonly used functions, such as indicators, so you do not
need to retype them. Once an equation is stored, you can access it from
any equation entry field by clicking on the small down arrow, which
appears next to all the equation entry fields. It will then display a list
of your stored equations.

You do not need to go to preferences to add, edit or delete stored equations.
Each equation entry field will display a menu if you right click on it.
It will give you the options to "Add", "Edit", "Delete",
or "Manage". Most of these options are self-explanatory; Manage
will display the equations preferences page.

You have to write the equations according to the English localization.
For example you cannot write a number inside an equation as 17,17
(with comma as decimal separator), but you have to write it as 17.17
(with point as decimal separator), without mattering what localization you're using.
This rule applies only to equations, all other numbers in Venice follow
the selected localization.

You can reach the equations page by:

    * Clicking on the "File" menu item.
    * Then clicking on the "Preferences" menu item.
    * Then selecting the "Equations" page.

2.2 Proxy

You can configure Venice to work with a web proxy. This allows
you to download quotes from the Internet through a web proxy. You can reach
the proxy configuration page by:

    * Clicking on the "File" menu item.
    * Then clicking on the "Preferences" menu item.
    * Then selecting the "Proxy" page.

To use the proxy, make sure the "Use Proxy" check box is
selected and enter the proxy host and port into the two fields.

2.3 Quote Source

Venice currently supports three methods for reading in quotes. It can
read in quotes directly from files containing quotes in MetaStock,
EzyChart or Insight Trader. It can read in quotes stored in a MySQL or
PostgreSQL database. And finally it can read in some inbuilt sample quotes,
so you can test out Venice. Reading from files is quick and easy to set up -
but access is much slower than from database. It is recommended that you set
up access for files to start with and if you plan to use Venice to switch to
the database. 

You can only access quotes directly from files, if each file
contains only a single day's worth of quotes. If any of your quote
files contain more than one date, you'll need to access your quote
files from the Database Quote Source instead

You can reach the quote source configuration page by:

    * Clicking on the "File" menu item.
    * Then clicking on the "Preferences" menu item.
    * Then selecting the "Quote Source" page.

2.3.1 File Quote Source

Once you have reached the quote source page, to tell Venice to read quotes
directly from files click on the "Files" tab and select the "Use Files"
radio button. You'll need to know the format of your quote files.
Venice supports the following:

    * "MetaStock"

      This format has 4 digit years and the quotes are in dollars. The first
      column is the symbol, then the date, open, high, low, close and volume.

      Example:

      XXX,19990715,1.73,1.82,1.71,1.81,3648921

    * "MetaStock (volume/100)"

      This format is the same as "MetaStock" above but the volume is divided
      by 100.

      Example:

      XXX,19990715,1.73,1.82,1.71,1.81,36489

    * "Insight Trader"

      This format has 2 digit years and quotes are in cents and volume is
      divided by 100. The first column is the symbol, then the date, open,
      high, low, close and volume.

      Example:

      XXX 07/15/99 173 182 171 181 36489

    * "EzyChart"

      This format has 2 digit years and quotes are in cents. The first column
      is the symbol, then the date, open, high, low, close and volume.

      XXX,990715,173,182,171,181,3648921


You can then tell Venice where the quotes files are by either adding them
here with the "Add" button or by using the Import Quotes dialog.

You can only access quotes directly from files, if each file
contains only a single day's worth of quotes. If any of your quote
files contain more than one date, you'll need to access your quote
files from the Database Quote Source. instead

2.3.2 Database Quote Source

Once you have played with Venice for a while you might get annoyed at the time
it takes Venice to load quotes from files. You can fix this by reading quotes
from a database. Currently Venice only supports reading quotes from a
MySQL or a PostgreSQL database. To read quotes from a database, you'll need to
download a copy of the database and the relevant Java software driver (JDBC)
that lets Venice talk to the database.

You can download MySQL from http://www.mysql.com and you can also download
a software driver from them too. Their software driver is available at
http://www.mysql.com/downloads/api-jdbc-stable.html. Venice also supports
a software driver called "mm.mysql" which is available
from http://sourceforge.net/projects/mmmysql. Both are good, get either,
although I use the latter. Once the database is set up you'll need to create
a database for Venice, call the database "shares".

Once all that is done, you'll need to configure Venice to use the database.
From the quote source page, to tell Venice to read quotes from the database
click on the "Database" tab and select the "Use Database"
radio button. You'll be confronted with several fields you need to fill in:

    * "Database" - Select the database that you are using.
    * "Host" - This is the IP address of the computer that the database is
      running on. If it is running on the same machine as Venice, you can just
      put "localhost" here if you want.
    * "Port" - This is the port that the database is listening on.
      You shouldn't need to touch this.
    * "Username" - This is the user name that Venice will connect with in
      the database. You should have created a user/password pair when setting
      up the database.
    * "Password" - This is the password that Venice will connect with in
      the database. You should have created a user/password pair when setting
      up the database.
    * "Database Name" - This is the name of the database that you created
      earlier. You shouldn't need to touch this.

Finally you'll need to import the quotes into the database, you can do this by
using the Import Quotes dialog.

Good luck!

With the current version you might get an error message saying that it
can't find a table. If you get this, it probably means that you haven't
imported any quotes into Venice yet. Venice will automatically create its
required tables the first time you import quotes. For reference, this is
the format of the SQL shares table:

+--------+----------+------+-----+------------+-------+
| Field  | Type     | Null | Key | Default    | Extra |
+--------+----------+------+-----+------------+-------+
| date   | date     |      | PRI | 0000-00-00 |       |
| symbol | char(12) |      | PRI |            |       |
| open   | float    | YES  |     | 0          |       |
| close  | float    | YES  |     | 0          |       |
| high   | float    | YES  |     | 0          |       |
| low    | float    | YES  |     | 0          |       |
| volume | int(11)  | YES  |     | 0          |       |
+--------+----------+------+-----+------------+-------+


2.3.3 Sample Quote Source

Venice has some inbuilt sample quotes, so you can test out Venice without
going to all the trouble of importing stock quotes. It contains a small
selection of quotes from the Australian Stock Exchange (ASX) from 1986.

2.4 Tuning

The tuning page allows you to configure Venice for optimal performance.

You can reach the tuning configuration page by:

    * Clicking on the "File" menu item.
    * Then clicking on the "Preferences" menu item.
    * Then selecting the "Tuning" page.

Loading quotes from files or database can sometimes take a while. For
this reason Venice caches the quotes it reads in. That is, it keeps them in
memory so that if you want to view them again, they come up much faster.
By default Venice keeps up to about 100,000 quotes in memory at one time.
On this page you can view the number of quotes Venice is currently
caching and set the maximum amount. From time to time, Venice may need
to go a little higher than this amount.

2.5 Windows Preferences

You can load from or save to an XML file the whole Venice preferences.

You can reach the windows preferences configuration page by:

    * Clicking on the "File" menu item.
    * Then clicking on the "Preferences" menu item.
    * Then selecting the "Windows Preferences" page.

This feature can be used in several ways:

    * You can do a library of XML files, so that you can choose many different
possible default configurations.
    * You can import preferences created with another user.
    * You can import preferences in another working copy of Venice.

2.6 Language

You can change the default language and use a different Venice localisation.

You can reach the language configuration page by:

    * Clicking on the "File" menu item.
    * Then clicking on the "Preferences" menu item.
    * Then selecting the "Language" page.

When you change the localisation language, you should restart Venice,
so that all menus are refreshed.

3 Importing Quotes

Before you import quotes, you'll need to decide whether Venice will read the
quotes directly from files or from a database. See Quote Source
to set this all up.

You can reach the import quotes dialog by:

    * Clicking on the "File" menu item.
    * Then clicking on the "Import Quotes" menu item.

This dialog is very versatile and lets you perform several import/export
operations:

3.1 Import quote files into the Database

To perform this operation:

Click on "Files" in the "Import From" area and on "Database"
in the "Import To" area.

This allows you to import multiple quote files into the database in one
operation. Importing quotes into the database can take a while, so please be
patient. You need to select the quote type you are importing, see
Quote Source for an explanation of these types.
When you click "Import" a dialog will come up and you can select
multiple quote files.

3.2 Import quote files into Venice

To perform this operation:

Click on "Files" in the "Import From" area and on "Files"
in the "Import To" area.

This allows you to import multiple quote files into Venice in one
operation. This operation only tells Venice about the quote files, it doesn't
copy them in anyway - so if you delete the original quote files, Venice
obviously won't be able to access them anymore.

3.3 Import quote files into Venice and the Database

To perform this operation:

Click on "Files" in the "Import From" area and on "Files"
and "Database" in the "Import To" area.

This operation performs the combination of the above two operations it will
import the files into the database and also into Venice. This is useful if
you access the files via the database, but would like Venice to be able to
cope if the database goes down.

3.4 Import quotes from the Internet

To perform this operation:

Click on "Internet" in the "Import From" area and on "Files"
and/or "Database" in the "Import To" area.
Enter a comma or space separated list of symbols you wish to import and the
date ranges you wish to import.

This allows you to import quotes directly from the internet and store
them in the database and/or in quote files on your hard drive. If you need
to use a web proxy, you can configure it in Venice's Preferences.

3.5 Export quote files from the Database

To perform this operation:

Click on "Database" in the "Import From" area and on "Files"
in the "Import To" area.

This allows you to export all the quote files from the database back into text
files. Each file will contain quotes for a single day. You'll need to specify
the format of the quotes in the file you want, see Quote Source
for more details. You'll also need to specify the path and file name for the
generated files in the text box showing. Each file is named with the date
as part of it's file name, you'll need to specify the format of the date.

E.g.

    * /home/aleppard/quotes-mm-dd-yyyy.txt
      -> /home/aleppard/quotes-12-31-2002.txt
    * /home/aleppard/market_ddMMMyy.txt
      -> /home/aleppard/market_31dec02.txt
    * C:\Quotes\Quotes_d?_m?_yy.txt
      -> C:\Quotes\Quotes_1_5_02.txt

What if the string "mm", "dd", "MMM" or "yy" appears in my
destination file but isn't meant to be part of the date string? Well it won't
work.

4 Tables

Venice has the ability to list quote prices for a single day's trading in a
table, and the ability to list all quote prices for a list of given stocks.
When listing you need to decide which stocks you are interested in. Currently
you can select from "All Ordinaries", "Market Indices" and "All Symbols".
These categories are based on the ASX (Australian Stock Exchange) so might not
be very relevant for other exchanges. Currently Venice is very ASX-centric. At
the moment Venice does not have access to any data relating to the symbols it
is given, so it has to guess which category the symbol falls in. All
Ordinaries lists all 3 letter symbols except those starting with an *X*.
Market Indices lists all symbols starting with an *X*, on
the ASX almost all of these are market indices. All Symbols lists all the
symbols.

You can display a table by doing the following:

    * Clicking on the "Table" menu item.
    * Then clicking on either "All Ordinaries", "Market Indices",
      "All Stocks" or "Stocks".
    * Then clicking on either "List All", "List By Date", "List By Rule" or
      "List By Symbols".

The "List All" option allows you to list all the stock quotes
on the given date.

The "List By Date" option allows you to specify the date of the stock
quotes to list.

The "List By Rule" option allows you to specify the initial
filter. The filter is an equation which specifies which stocks should be
listed and which hidden, see below for more details about this, also see the
Gondola Language for details about the format of
the equations.

The "List By Symbols" option allows you to specify the stock symbols
to list. Then all the quotes for those stock symbols will be listed.

4.1 Apply Equations

You can run multiple equations against every stock listed in the table and
list the result of the equation. Click on the "Table" menu item, then
click on the "Apply Equations" menu item. This will bring up a dialog
where you can enter up to 5 equations that can be run against each stock. For
each you can enter the name of the column and the equation to be run. See
Gondola Language for details about the format of these equations.
Also see Preferences for how to get Venice to remember equations
so you don't have to keep typing them in all the time. To get you started, an
example equation is avg(close, 30, 0) which will calculate the average
day close value over the last 30 days, including today.

4.2 Apply Filter

You can restrict which stocks are listed in the table by setting up an equation
filter. This equation is run against each stock listed in the table, if the
equation equates to true for a stock, then that stock is listed. Otherwise it
is hidden. You can reach this by clicking on the "Apply Filter" menu item.
Again, see Gondola Language for details about the format of these equations.
Also see Preferences for how to get Venice to remember equations so
you don't have to keep typing them in all the time. To get you started, an
example equation filter is lag(close, 0) > lag(close, -1) which will
list all quotes where the day close of today is higher than the day close of
the last trading day.

4.3 General Table Features

Every table in Venice supports the following:

By clicking on a column header you can sort by that column, click again and
you reverse the sort. You can change the order of the columns by dragging a
column and dropping it into a new position.

Some tables in Venice support the following:

By right clicking on a row you can raise a context sensitive menu. If you
double click on a row the most common operation is invoked, typically
Graphing. Some tables also have a menu item "Show Columns" which lets
you specify which columns are shown.

5 Watch Screens

Venice currently does not support real-time or intra-day quote data, but
it does support end-of-day watch screens. These watch screens are useful for
grouping and displaying stocks that are interesting. You can create a new
watch screen by doing the following:

    * Clicking on the "Table" menu item.
    * Then clicking on the "Watch Screen" menu item.
    * Then clicking on the "New Watch Screen" menu item.

This will create a new watch screen which you will need to name. You
can then add symbols that should be displayed in this watch screen.

6 Graphs

6.1 Portfolio Graphs

You can graph the value of any portfolio over time by doing the following:

    * Clicking on the "Graph" menu item.
    * Then clicking on the "Portfolio" menu item.
    * Then clicking on the name of the portfolio you wish to graph.

Depending on the size of your portfolio and the time it has existed, this
might take a while as Venice has to load in stock quotes for every stock
traded for every day of the portfolio.

Apart from graphing the value of the portfolio over time, you can also graph
the profit/loss of the portfolio. To do this, graph the portfolio as above,
then click on the menu item with the same name as your portfolio, then select
the "Graph" menu item and then click on "Profit/Loss". The profit and loss
graph is calculated by ignoring any deposits and withdrawals made to the
portfolio, the balance of that portfolio over time will reflect the profit and
loss made.

6.2 Market Indicator Charts

A market indicator is an indicator that can be used to help determine the
state of the market. They are calculated using multiple stocks on the market,
for example "Advance/Decline" uses all ordinary stocks in its calculations.

6.2.1 Advance/Decline

Currently the only market indicator that Venice can graph is the
advance/decline indicator. You can graph this indicator by:

    * Clicking on "Graph" menu item.
    * Then clicking on the "Market Indicator" menu item.
    * Then clicking on the "Advance/Decline" menu item.

This operation reads in almost all of the available stock quotes, so it might
be very slow.

The advance/decline indicator is calculated by taking an arbitrary start value
(currently 0). Each day's value is calculated by taking the number of stocks
that advanced (i.e. have a higher day close than day open) minus the number of
stocks that declined and adding that to the previous day's value. This creates
a cumulative graph whose trend may be used to give an indication of possible
future direction of the market.

6.3 Stock Charts

Venice supports a variety of technical charts. Some of these charts are
described below, for the others, please consult the literature for their
meaning and interpretation.

6.3.1 Custom

Venice supports the charting of user-defined custom indicators. Using the
Gondola Language you can write custom indicators which can
then be charted. The custom chart user interface allows you to enter a Gondola
equation to chart and to specify the chart as either primary or secondary.
A primary chart is one that appears in the top graph. A secondary chart will
appear in its own smaller graph below.

7 Portfolios

Venice allows you to keep track of multiple portfolios. One portfolio
might be for your actual portfolio and others could be used for paper
trading. You can create a new portfolio by:

    * Clicking on the "Files" menu item.
    * Then clicking on the "Portfolio" menu item.
    * Then clicking on the "New Portfolio" menu item.

A portfolio is made up of several "Cash Accounts" and several
"Share Accounts". A "Cash Account" can be a bank account, a term deposit,
a Cash Management Account or any account which stores money. A "Share Account"
is any account where you can trade shares. To create a trading account you
will need at least one of each.

A portfolio is made up of several accounts and also transactions. A
transaction is any financial transaction that involves one or more of the
accounts. See transactions for more details.

7.1 Import/Export

You can import and export portfolios to CSV files (comma separated values)
these files can then be read by an Excel spreadsheet and other tools. This
can be useful for backup purposes. Venice is alpha after all! The format of
the output files is:

dd/mm/yyyy,transaction name,value,symbol,share number,trade cost,cash
account1,cash account2,share account

Not all of these fields will be present, an example exported line is:

02/01/2003,Accumulate,4000.00,XYZ,100,20.50,Bank,,Broker

7.2 Graph

You can graph the value of a portfolio over time. See Graphs
for more details.

7.3 Transaction History

You can view a list of all the transactions that have occurred in the
portfolio. You can reach this by clicking on the "Transaction" menu
item and then clicking on the "Show History" menu item.

7.4 Transactions

Venice currently supports several common transactions:
"Accumulate Transaction", "Deposit Transaction", "Dividend Transaction",
"Dividend DRP Transaction", "Fee Transaction", "Interest Transaction",
"Reduce Transaction", "Transfer Transaction" and "Withdrawal Transaction".

Once a portfolio is open, you can add a transaction by clicking on the
"Transaction" menu item, then clicking on the "New" menu item.
You will see in a drop down box a list of the transactions available. Some of
these might not be available yet, e.g. you cannot enter a Reduce Transaction
(sell shares) without having bought any.

7.4.1 Accumulate Transaction

The accumulate transaction is the "buy shares" transaction. To enter this
transaction you will need the date the transaction took place, the cash
account where you withdrew the money from, the share account that accumulated
the shares, the symbol of the stock you accumulated (e.g. CBA), the number of
shares you accumulated, the total value of the shares at the time of purchase
and finally the cost of the trade. This information should all be available
from your broker.

7.4.2 Deposit Transaction

The deposit transaction is the transaction where you
deposit money into a cash account such as a bank account. To enter this
transaction you will need the date the transaction took place, the cash
account you deposited the money to and the amount you deposited.

7.4.3 Dividend Transaction

The dividend transaction is the transaction when you receive a share
dividend. To enter this transaction you will need the date the transaction
took place, the cash account that received the money, the share account
containing the stock, the symbol of the stock and the dividend amount paid to
you.

7.4.4 Dividend DRP Transaction

The dividend DRP (dividend re-investment programme) transaction is the
transaction when you receive a share dividend that is automatically
re-invested back into the company by buying more shares. To enter this
transaction you will need the date the transaction took place, the
share account containing the stock, the symbol of the stock and the amount
of shares acquired.

7.4.5 Fee Transaction

The fee transaction is the transaction when you receive any kind of
fee such as account keeping fees, Tax etc. To enter this transaction you
will need the date the transaction took place, the cash account that
received the fee and the amount that you were charged.

7.4.6 Interest Transaction

The interest transaction is the transaction when you receive any
interest in one of your cash accounts. To enter this transaction you will
need the date the transaction took place, the cash account that received
the interest and the amount that you were credited. If your account is in
the negative and this was the interest that was debited from your account,
then put a minus sign in front of the value.

7.4.7 Reduce Transaction

The reduce transaction is the "sell shares" transaction. To enter this
transaction you will need the date the transaction took place, the cash
account where the money from the sale will go, the share account that
reduced the shares, the symbol of the stock you reduced (e.g. CBA), the
number of shares you reduced, the total value of the shares at the time of
sale and finally the cost of the trade. This information should all be
available from your broker.

7.4.8 Transfer Transaction

The transfer transaction is the transaction where you transfer money from
one cash account to another. To enter this transaction you will need the
cash account where you withdrew the money, the destination cash account and
the amount you transferred. If there was a fee for the transfer, you need
to enter this as a separate transaction.

7.4.9 Withdrawal Transaction

The withdrawal transaction is the transaction where you
withdraw money from a cash account such as a bank account. To enter this
transaction you will need the date the transaction took place, the cash
account you withdrew the money from and the amount you withdrew.

8 Gondola Language

The "Gondola Language" is a language for analysing stock market data.
The language allows you to do a variety of tasks from listing stocks in tables
that only match your criteria to creating automated buy/sell paper trade rules.
The language is closely modelled after the C programming language, so if you
know that language, then you should find Gondola easy and familliar to
work with.


Whenever you enter a Gondola expression there are two implicit variables that
are always set: the current date and the current stock. For example if
you are displaying a Table of stock quotes, you can execute an
equation for each stock. If you entered this line:

avg(close, 30)

It would display, for each stock, the average day close value over the last
30 days starting from today. Here the current date would be set to the most
recent day you have a quote for and the current stock would be set to the
current stock.

You can also enter equations when performing Paper Trading. If you
entered the following as a buy rule:

avg(close, 15) > avg(close, 30, -1)

It would only buy the stock when the average day close over the last 15 days
was higher than the average day close of over the last 30 days, where the
30 day average would be calculated starting from the previous day and working
backwards. So here the current date would be set to whatever date the trade
was to be analysed for.

The Gondola language is very type strict. What this means is that each value
has a given type, whether it is an "integer", "real" or "boolean". This means
that the numbers 12 and 12.0 are different, and 1 and true
are different. If you get a type mismatch error, you've probably entered an
"integer" number (e.g. 12) instead of a "real" number (e.g. 12.0).

8.1 Gondola Operators

The Gondola language supports the following boolean operators: "and", "or"
and "not". For example:

    * close > 12.0 or open > 12.0
    * close > 12.0 and open > 12.0
    * not(avg(open, 15) > 12.0)

It also supports basic arithmetic: +, -, * and /. For example:

    * close + lag(close, -1)
    * close - lag(close, -1)
    * close / lag(close, -1)
    * close * lag(close, -1)

The type of returned value of arithmetic operators is the same of the first operand.
The following examples explain the behaviour:

    * INTEGER_TYPE + INTEGER_TYPE returns an INTEGER_TYPE    * INTEGER_TYPE - FLOAT_TYPE returns an INTEGER_TYPE    * FLOAT_TYPE / INTEGER_TYPE returns a FLOAT_TYPE    * FLOAT_TYPE * FLOAT_TYPE returns a FLOAT_TYPE
And finally it also supports the relational operators: "==", ">", ">=", "<",
"<=" and "!=". For example:

    * volume == lag(volume, -1)
    * close > lag(close, -1)
    * close >= lag(close, -1)
    * close < lag(close, -1)
    * close <= lag(close, -1)
    * volume != lag(volume, -1)

8.2 Gondola Variables

The Gondola language has full support for variables, which allow you to
store, retrieve and manipulate values. When defining a new variable you
need to specify whether the variable can change or is constant, the variable
type, the name of the variable and optionally the initial value of the
variable.

Examples:

    * int averageValue
    * const boolean myValue = true
    * float averageValue = 10.0*12.0

8.3 Gondola Functions

8.3.1 Absolute Value

The absoluate value function returns the absolute value of the given value.
The absolute value is the positive value of a number. For example the absolute
value of -12 is 12, and the absolute value of 12 is 12.

abs(VALUE)

Where VALUE is the initial value.

Example:

abs(-28.0)

Returns the absolute value of -28.0 which is 28.0.

8.3.2 Average

The average function averages a series of stock quotes.

avg(QUOTE, DAYS[, START_OFFSET])

Where QUOTE is "open", "close", "low", "high" or "volume".
Where DAYS is the number of days to average.
Where START_OFFSET is the most recent date to average, 0 means the current
trading date, -1 means the previous trading date, etc.

Example:

avg(open, 15, -1)

Returns the average of the day open value for the current stock for the last
15 days, ending with yesterday.

8.3.3 Bollinger Bands

The bollinger bands are: bol_upper=avg+2sd, bol_lower=avg-2sd .

bol_lower(QUOTE, DAYS[, START_OFFSET])

bol_upper(QUOTE, DAYS[, START_OFFSET])

Where QUOTE is "open", "close", "low", "high" or "volume".
Where DAYS is the number of days to average.
Where START_OFFSET is the most recent date to average, 0 means the current
trading date, -1 means the previous trading date, etc.

Example:

bol_upper(close, 26, -1)

Returns the bollinger band value of the day close value for the current stock for the last
26 days, ending with yesterday.

The expression bol_lower(close, 26, 0) is the same as bol_lower(close, 26)
similarly for open, high and low.

The expression bol_upper(close, 26, 0) is the same as bol_upper(close, 26)
similarly for open, high and low.

8.3.4 Correlation

The correlation function returns the correlation between two stock
quotes.

corr(SYMBOL, QUOTE, DAYS[, START_OFFSET])

Where SYMBOL is the stock symbol. Where QUOTE is "open", "close",
"low", "high" or "volume".
Where DAYS is the number of days to correlate.
Where START_OFFSET is the most recent date to correlate, 0 means the current
trading date, -1 means the previous trading date, etc.

Example:

corr("CBA", close, 30, -1)

Returns the correlation of the day close values of this stock and
CBA over 30 days ending in yesterday.

8.3.5 Day

The day function returns the current day of the month.

day()

Example:

day()

Returns the current day, which will be 31, if it is the 31st.

8.3.6 Day of Week

The day of week function returns the current day of the week.

dayofweek()

Example:

dayofweek()

Returns the current day of the week, which will be 1, if it is a Sunday.

8.3.7 Day of Year

The day of year function returns the current day of the year.

dayofyear()

Example:

dayofyear()

Returns the current day of the year, which might be 365, if it is New Years Eve.

8.3.8 Exponential Moving Average

The exponential moving average function averages a series of stock quotes according to
the following equation: EMA(current) = EMA(previous) + SMOOTHING_CONSTANT * (QUOTE - EMA(previous).

ema(QUOTE, DAYS[, START_OFFSET][, SMOOTHING_CONSTANT])

Where QUOTE is "open", "close", "low", "high" or "volume".
Where DAYS is the number of days to average.
Where START_OFFSET is the most recent date to average, 0 means the current
trading date, -1 means the previous trading date, etc.
Where SMOOTHING_CONSTANT is the smoothing constant.

Example:

ema(close, 26, 0.1, -1)

Returns the average of the day close value for the current stock for the last
26 days, ending with yesterday.

The expression ema(close, 26, 0, 0.1) is the same as ema(close, 26)
similarly for open, high and low.

The expression ema(close, 26, 0, 0.2) is the same as ema(close, 26, 0.2)
similarly for open, high and low.

The expression ema(close, 26, -1, 0.1) is the same as ema(close, 26, -1)
similarly for open, high and low.

8.3.9 For

The for function is a looping function that allows you to loop over
an expression of code. Typically the loop is tied to a variable, so you
need to set the initial value of the variable, a condition where the loop
will terminate, and how the variable should change after each loop.

for(INITIAL; CONDITION; LOOP) { COMMAND }

The function will execute the INITIAL expression, then execute
the COMMAND expression, and then execute the LOOP expression. It will
then execute the CONDITION expression. If the CONDITION expression
was FALSE then the function will return. Otherwise it will run the
COMMAND expression, then the LOOP expression, then check the CONDITION
expression, etc.

Example:

int b = 0

for(int i = 0; i < 10; i = i + 1) {
  b = b + i
}


The above code will sum the numbers 0, 1, 2, ... 9 and store the result
in the b variable.

8.3.10 If

The if function allows a selection of which code to be executed.

if(VALUE) { TRUE } else { FALSE }

If the value of the VALUE expression is true, then the TRUE expression
will be executed, otherwise the FALSE expression will be.

Example:

if(lag(open, 0) > lag(open, -1)) {
   lag(open, 0)
}
else {
   lag(open, -1)
}

Returns the greater of today and yesterday's day open values.

8.3.11 Lag

The lag function returns a stock quote.

lag(QUOTE[, OFFSET])

Where QUOTE is "open", "close", "low", "high" or "volume".
Where OFFSET is the date to retrieve the stock quote, 0 means the current
trading date, -1 means the previous trading date, etc.

Example:

lag(high, -5)

Returns the day high value of the current stock, 5 days previous.

The expression lag(close, 0) is the same as lag(close) and they can both be
abbreviated to close; similarly for open, high and low.

8.3.12 Minimum

The minimum function finds the minimum of a series of stock quotes.

min(QUOTE, DAYS[, START_OFFSET])

Where QUOTE is "open", "close", "low", "high" or "volume".
Where DAYS is the number of days to search.
Where START_OFFSET is the most recent date to search, 0 means the current
trading date, -1 means the previous trading date, etc.

Example:

min(volume, 15, -1)

Returns the minimum volume of trade for the current stock for the last
15 days, ending with yesterday.

8.3.13 Maximum

The maximum function finds the maximum of a series of stock quotes.

max(QUOTE, DAYS[, START_OFFSET])

Where QUOTE is "open", "close", "low", "high" or "volume".
Where DAYS is the number of days to search.
Where START_OFFSET is the most recent date to search, 0 means the current
trading date, -1 means the previous trading date, etc.

Example:

max(volume, 15, -1)

Returns the maximum volume of trade for the current stock for the last
15 days, ending with yesterday.

8.3.14 Moving Average Convergence Divergence

The MACD is: MACD = 26 days EMA - 12 days EMA.

macd(QUOTE[, START_OFFSET])

Where QUOTE is "open", "close", "low", "high" or "volume".
Where START_OFFSET is the most recent date to average, 0 means the current
trading date, -1 means the previous trading date, etc.

Example:

macd(close, -1)

Returns the macd value of the day close value for the current stock ending with yesterday.

The expression macd(close, 0) is the same as macd(close)
similarly for open, high and low.

The expression macd(close, 0) is the same as ema(close,26,0,0.1)-ema(close,12,0,0.1)
similarly for open, high and low.

8.3.15 Momentum

The momentum is: momentum(now)=quote(now)-quote(period deleyed).

momentum(QUOTE, DAYS[, START_OFFSET])

Where QUOTE is "open", "close", "low", "high" or "volume".
Where DAYS is the number of days to delay.
Where START_OFFSET is the most recent date to average, 0 means the current
trading date, -1 means the previous trading date, etc.

Example:

momentum(close, 26, -1)

Returns the momentum value of the day close value for the current stock for the last
26 days, ending with yesterday.

The expression momentum(close, 26, 0) is the same as momentum(close, 26)
similarly for open, high and low.

8.3.16 Month

The month function returns the current month.

month()

Example:

month()

Returns the current month, which will be 8, if it is August.

8.3.17 On Balance Volume

The OBV is the sum of volumes in the period, counted as positive if close is greater than open or
as negative if open is greater then close.

obv(DAYS[, START_OFFSET[, INITIAL_VALUE]])

Where DAYS is the number of days to count over.
Where START_OFFSET is the most recent date to average, 0 means the current
trading date, -1 means the previous trading date, etc.
Where INITIAL_VALUE is the initial value which counting from

Example:

obv(200, -1, 50000)

Returns the obv value counted over the last
200 days, ending with yesterday, starting with value 50000.

The expression obv(200) is the same as obv(200, 0, 50000).

8.3.18 Percent

The percent function returns the given percent of the given value.

percent(VALUE, PERCENT)

Where VALUE is the initial value and PERCENT is the ratio to return.

Example:

percent(200, 10)

Returns 10% of 200 which is 20.

8.3.19 Relative Strength Index

This function calculates the Relative Strength Index (RSI) of the current stock.

rsi([PERIOD[, START_OFFSET]])

Where PERIOD is the period to apply the RSI.
Where START_OFFSET is the most recent date to calculate, 0 means the current
trading date, -1 means the previous trading date, etc.

Example:

rsi()

Returns the RSI of the current stock.

8.3.20 Square Root

The square root function returns the square root of the given value.

sqrt(VALUE)

Where VALUE is the initial value.

Example:

sqrt(144)

Returns the square root of 144 which is 12.

8.3.21 Standard Deviation

sd(QUOTE, DAYS[, START_OFFSET])

Where QUOTE is "open", "close", "low", "high" or "volume".
Where DAYS is the number of days to average.
Where START_OFFSET is the most recent date to average, 0 means the current
trading date, -1 means the previous trading date, etc.

Example:

sd(close, 26, -1)

Returns the standard deviation value of the day close value for the current stock for the last
26 days, ending with yesterday.

The expression sd(close, 26, 0) is the same as sd(close, 26)
similarly for open, high and low.

8.3.22 Sum

The sum function sums a series of stock quotes.

sum(QUOTE, DAYS[, START_OFFSET])

Where QUOTE is "open", "close", "low", "high" or "volume".
Where DAYS is the number of days to sum.
Where START_OFFSET is the most recent date to sum, 0 means the current
trading date, -1 means the previous trading date, etc.

Example:

sum(open, 15, -1)

Returns the sum of the day open value for the current stock for the last
15 days, ending with yesterday.

8.3.23 While

The while function is a looping function that allows you to loop over an
expression of code. The loop contains an expression that will be executed until
a specific condition is not met.

while(CONDITION) { COMMAND }

The function will execute the COMMAND expression until the CONDITION
is not met. If the CONDITION is never met, the loop will not be entered.

Example:

int sum = 1

while(sum < 100) {
  sum = sum + 1
}


The above code will keep increment the value of sum until it is equal to 100.

8.3.24 Year

The year function returns the current year.

year()

Example:

year()

Returns the current year, which will be 2004, if it is 2004.

9 Jython Macros

Since version 0.5, Venice supports the use of the Jython (http://www.jython.org)
scripts to automate the operation of the program.  More information and example scripts
will be available soon.  For the moment, suffice to say that any Java object that can be
accessed by Venice source code is fair game for macrofication.

Here's a trivial example of a simple script that displays a progress dialog:


import org.mov.ui.ProgressDialogManager as PM
import java.lang.Thread as T
p = PM.getProgressDialog()
p.setMaximum(10)
p.setProgress(0)
p.show("performing task");
p.setProgress(6)
T.sleep(500);
p.setProgress(4)
T.sleep(500);
p.setProgress(3)
T.sleep(500);
p.setProgress(9)


10 Analysis

10.1 Paper Trade

Venice allows you to perform historical paper trading, this allows you to test
buy/sell rules using historical share data. You need to enter basic data such
as which shares you wish to trade (either from a select list or say all
ordinary shares), the buy/sell rules you wish to trigger the trades, the date
range over which to trade, and the initial capital. Venice will then pretend
to buy and sell shares over that time range and will generate a portfolio
detailing all its trades and the final portfolio value. You can bring up
the paper trade dialogue by:

    * Clicking on the "Analysis" menu item.
    * Then clicking on the "Paper Trade" menu item.

10.1.1 The Range Page

The range page defines the range and order of the paper trade. The
"Date Range" defines the range of dates that the paper trade will be
active. The "Symbols" field defines which symbols the paper trade will be
restricted to. You can either use the set groups such as "All Ordinaries"
or you can enter any specific set of symbols. For each day that the paper
trade runs, it will iterate through all the symbols it is allowed to
trade. For each symbol, it will run the buy rule to see if it triggers a
trade. If the paper trade has no more money left to purchase shares for
that day, it will move to the next day. If you want to control the order
that the paper trade iterates through the symbols, you can using the
"Order Symbols" options. You can either order the
symbols by the given options, or by entering an equation.

Some example values:

    * Start Date: 3/1/2000
    * End Date: 24/1/2001
    * Symbols: ANZ WBC CBA NAB
    * By: Change Decreasing

10.1.2 The Rules Page

The rules page defines the buy/sell rules that trigger trades. Venice
supports the concept of "Rule Famillies". The idea is that you
might want to try several hundred very similar equations.
For example, if you wanted to trigger a buy on a moving average, you might
have the following buy equation:
avg(close, 15, 0) > avg(close, 30, 0). But what if you wanted
to try not only 15 and 30, but all the values up to 100? You could do this
by entering the equation: avg(close, a, 0) > avg(close, b, 0).
Then making sure the "Enable multiple rules" checkbox is ticked.
Then entering the maximum values for a and b into the "Range" entries.

Venice makes two additional variables available to paper trade equations:

    * held - defines the number of days that the stock has been
      held.
    * order - if you selected any order besides "No Real Order" this variable
      will be available. It will be set to the order that the symbol is
      analysed by the paper trade. If it is the first symbol analysed, then
      order will be set to 0. For example, if you are ordering
      by volume decreasing, the stock with the highest volume will be
      analysed first, and the order variable will be set to 0.

Some example values:

    * Buy Rule: order == 0
    * Sell Rule: order < a || held > b
    * Enable multiple fules: Ticked
    * Range a: 1 to: 10
    * Range b: 1 to: 50
    * Range c: 1 to: leave empty

10.1.3 The Portfolio Page

The portfolio page defines the portfolio that is used when paper trading. You
need to enter the "initial capital" that the portfolio has before it starts
trading, and a value for a fixed "Trade Cost".
Next you need to decide how many stocks the portfolio can contain. You
can specify either a fixed "Number of Stocks", in which case Venice works out
the average value of each stock. Or you can specify the "Stock Value", in which
case Venice works out the maximum number of stocks.

Some example values:

    * Initial Capital: 400000
    * Trade Cost: 25
    * Number of Stocks: 1

10.1.4 The Trade Value Page

The trade value page defines the strategy used to buy or sell the stocks. You
need to enter an "equation for buying" and "another for selling";
if you prefer you can use the suggested equations instead, you can do that selecting one of the equations in the combo box.
The equation gives to the system the value at which you buy or sell the stock the next day.
The rules, in the Rules Page section, give you if you buy or sell the stock the next day,
while the equations, in the Trade Value Page section, give you the fixed price at which you wish to buy or sell the stock the next day.
The combo box has the following selectable options:
open value of tomorrow (in Gondola: open),
close value (in Gondola: close),
an average value between maximum and minimum values (in Gondola: (low+high)/2.0),
an average value between open and close values (in Gondola: (open+close)/2.0),
the minimum value (in Gondola: low),
the maximum value (in Gondola: high).
Pain attention to the 'open' key word: if you put 'open' alone, you will buy or sell the stocks at open price the next day;
if you put 'lag(open,0)', you will buy or sell the stocks at a price equal to the open price of the day before and only if this price will be reached by the stock during the next day.

10.2 Genetic Programming

Venice supports using evolutionary computation to create new buy/sell rules
based on historical data. The default way it works is that Venice initially creates a
set of random buy/sell rule equations. A pair of buy/sell rule equations is
refered to as an individual. It will then use algebraic simplification
to reduce the size of the individual's equations and also to remove any
unecessary computation. It will then check the individual's equations using a
few simple rules, e.g. is the equation big enough to be meaningful?
Is the equation not too large? If the individual's equations look like they
could be meaningful, it will paper trade with them, in the same method as the
Paper Trade Module. If the individual makes a loss or beaks even,
then it will be immediately rejected.

Once Venice has created a set of these random individuals, it will then
move onto the second generation. For this generation it will pick two
random individuals (with a strong bias to the better performing individuals)
and combine them, using a combination of cross-over and mutation, to create
a new individual. This process is refered to as breeding. It will again apply
algebraic simplification to the resultant individual's equations. It will
then paper trade this new individual. If the new individual has a greater
return than any of the previous individuals, it will be recorded. Venice will
then repeat this process, creating several new individuals. The number of
individuals created is refered to as the popluation. The number of the
highest returning individuals created which are bred in the next generation,
is refered to as the breeding population.

Once a given number of individuals have been created, Venice will then move
onto the third generation. Here, it is the same as the second generation,
except that instead of breeding from the random individuals that were
initially created, it will breed from individuals created that were bred
from the random individuals. Each generation then breeds from the
individuals bred from the last generation.

While equations created from Genetic Programming can give fantastic
returns on historical data, they unfortunately do not transfer directly to
different date and symbol ranges, than the ones that they were created with.
However, it is an experimental technique to see whether they can actually
come up with any principles that can be generally applied.

10.2.1 The Range Page

This is the same as the range page in the Paper Trade Module.

10.2.2 The Portfolio Page

This is the same as the portfolio page in the Paper Trade Module.

10.2.3 The Trade Value Page

This is the same as the trade value page in the Paper Trade Module.

10.2.4 The GP Parameters Page

The genetic programming (GP) parameters page defines the Genetic Programme settings.
You can set the number of "Generations"
to run; you can set the "Population" size; you can set
the "Breeding Population", and you can set
the "Display Population". The display population is
the number of highest returning individuals that are displayed when that
generation has completed.

Some example values:

    * Generations: 50
    * Population: 10000
    * Breeding Population: 250
    * Display Population: 5

10.2.5 The Initial Population Page

In the initial population page you can set many buy/sell rules as you wish.
For each of them you need to specify the percentage that it will be used to generate
the first population of GP algorithm.
You can set "Percentage of Random Population",
it is used to know the probability to generate a random individual, during the first
step of GP algorithm;
you can set "Percentage of Initial Population",
it is used to know the probability to generate an individual got from user defined ones,
during the first step of GP algorithm;
you can set "Number of Mutations",
it is the number of mutations that will be applied to the user defined individuals.
You can click two buttons: the former can be clicked to calculate the values
so that their sum is 100%, the latter can be clicked to set all the tabbed pane values
to the default. Normal behaviour should be: put values as you like, then click on
the former button to transform the inserted values to percentages.

The GP algorithm will generate the first population in this way:
it will choose between a random individual and an individual got from user defined ones,
this is done in accordance with the two values
"Percentage of Random Population"
and "Percentage of Initial Population";
then if a user defined is choosen, it will be applied on it a number of mutations
equal to "Number of Mutations";
then if the individual is not fine for breeding,
other mutations will be done until it is.


10.2.6 The GP Language Page

The Genetic Programme (GP) Language page defines the Gondola settings.
Currently you can set the probabilities for each word of Gondola. So the random
GP algorithm will choose the words in accordance with user defined probabilities.
If you set any of these values to zero, the GP algorithm will work do not considering
this word as a Gondola language's word.

To make easy the selection, there are some selectable tabbed panes.
Each of them has two buttons: the former can be clicked to calculate the values
so that their sum is 100%, the latter can be clicked to set all the tabbed pane values
to the default. Normal behaviour should be: put values as you like, then click on
the former button to transform the inserted values to percentages.

10.3 Genetic Algorithm

Genetic Algorithm is similar to Genetic Programming Module.
Differently from Genetic Programming, you have to write a buy and a sell rule with many parameters as you wish.
Then you have to declare the minimum and the maximum values for each parameter.
If you'll use minimum and maximum values of float type (2.3, 1.7, 1.1, ...) you'll use that parameter as float,
so be aware to put it in the rules so that it doesn't generate syntax error.
If you'll use minimum and maximum values of integer type (2, 3, 4, ...) you'll use that parameter as integer,
so be aware to put it in the rules so that it doesn't generate syntax error.
The Genetic Algorithm process will modifiy the parameter values inside the rules,
according to the range inserted.

