User Interface

The user interface of jStock is based on how I would like a chart drawing application should be like, and not on how most applications user interface look like. That means that all common (by my definition) task is easily available with as few operations as possible needed to perform the task. No standard menu's like "file", "edit" and so on. Another important criteria was to make as much as possible of the screen area available to the chart itself, in particular the width.

To minimise the needed user interaction to perform a task, a lot of parameters are stored in a preferences file(e.g. directory for datafiles, extension of datafiles and so on). For me this has worked very well. Quite uncommon the "menu" line is at the bottom of the application. The reason for this is that I tend to have the mouse cursor more at the bottom of the screen than at the top. Also, it doesn't get mixed up with the tab's.

Installation & configuration

Please, take a look in the log file if you're having problems, once in a while there might be a usefull message there.

Setting the directory for data files

Before you use this application, push the "Options" button after you have started the application and modify the properties you would like to change. Note that the file isn't really saved before you quit the application in a "normal" way. There is also some properties that is automatically changed, e.g. window size.

You probably would like to change the path to data files and the extension in the System tab. Note that the filename need to be like this: /path/to/datafiles/maybe_some_txt<ticker>.extension where <ticker> is the text string you enter in the application to load a particular stock.

An example:
"/pub/brand/analyse/paperhistory.php?paper=ahm.OSE" where
path is "/pub/brand/analyse/paperhistory.php?paper="
<ticker> is "ahm"
extension is "OSE"

Format of data file

The File Input tab of the Options menu let you choose the file format of your datafiles. Two different formats is supported directly and there also is a slow, but very generic file reader that should be capable of reading most text based data formats. The file format is used, even if files is downloaded from the internet.

Netfonds format

The formats is currently named after their sources, and the original "Netfonds" format looks like this:

quote_date paper exch open high low close volume value
20040130 NSG OSE 132.25 133.5 131.5 131.5 1182997 156210591
20040129 NSG OSE 130.25 132 128.5 131.25 1797585 233788758

The last column is ignored completly, From version 0.3.7 the ones containing letters are also completly ignored (was earlier used generate a tickerId). To select this format just push the "Netfonds" button. The rest isn't magic, but it works.

Yahoo format

As from version 0.4 files from Yahoo is also directly supported. This one looks almost like this:

Date Open High Low Close Volume Adj. Close*
23-Jan-04 6.00 6.08 5.87 6.02 1927000 6.02
22-Jan-04 5.80 6.10 5.80 6.00 1699000 6.00

The last column, Adj. close, is not used.

Other formats

However other sources for quotes may have a different layout and formatting, in particular the date format can vary. If your format differs select the "Other" button, and fill in the column number for each of the fields (0 is the first). If one or more of the columns is not present set the column number to -1.

Date formatting (or, to be specific, parsing of a date) is very difficult. Is the year first or last? Is the year 2 or 4 digits? and so on. In order to make a reasonable easy way to parse the date, jStock relays on the java.text.SimpleDateFormat class. This class needs to be feed with a text string or pattern that describes the format. So enter that carefully into the "Date format" field. 'yyyy' for 4 digits year, 'MM' for two digits month and 'dd' for day, also include space or delimiters. If letters are used for the month, use the numbers of letters. Please note capital 'M'. Some examples:

Date Pattern
20040131 yyyyMMdd
21-jan-2004 dd-MMM-yyyy
21/01/04 dd/MM/yy
Jan 21, 2004 MMM dd, yyyy
210104 ddMMyy

(It looks so simple now.)

The number of days

This parameter is used to set the number of days that the application will read from a data file. This is a trade off between screen size, speed and memory. If set too low the will not be enough data to fill up the screen. If it is set too high the apploication may be slow and/or use too much memory. Also remember that weekly charts need 5 times as much data as a daily chart. The default of 1200 is ok for weekly charts at a resolution of 1024 x 640 using 4 pixels per chart.

Enabling download of data files from internet

jStock can get fresh files from internet. In the System menu, check the box, and enter the modified URL to your favorite provider of files. Now, why do the URL need to be modified? In order to get the right data file every time, the URL has to updated with things like ticker, exchange and maybe start and stop dates. If the application should try to guess where each of thoose parameters was in the URL, the chances for an incorrect URL would be big. If however, the application is told where the different parameters are located, it is both easy to modify the URL and get it correctly.

URL modifications
Parameter Modifier Comments
Ticker <ticker>
Exchange <exchange>
Year (from) <year> First in time
Month (from) <month> First in time
Day (from) <day> First in time
Year (to) <YEAR> Note capital letters
Month (to) <MONTH> Note capital letters
Day (to) <DAY> Note capital letters
Length <length>

If other parameters are needed, let me know. A few word of the date parameters. jStock uses the current system date in order to determine the value for the YEAR, MONTH and DAY. The number of days parameter (also on the system tab) is then used to calculate approximatly correct values for year, month and day (or used directly for length). The good thing about this approch is that there is no need to worry about entering start and stop dates, the downside is that it is close to impossible to get data for other dates in a easy way.

Even if internet download is selected the data is saved to files so they still would be available if you're offline.

Database

The db properties are only applicable if you intend to use a sql database with jStock. Only tested with postgresql. Without db support the notes button is rather meaningless, and using it would generate a few exceptions, so I have removed it if the database is disabled. In order for the database application to work, you need a jdbc driver for your database. Install according to instruction with the jdbc driver.

Currently the db password stored in the properties file is not encrypted. That means if you are concerned about security, you should create a separate user for the jstock database with no or limited rights for other databases. Give the jstock user a different password from other paswords you use. It also helps to remove any read and write access for other users on the jstock.properties file.

Use

When the installation is done, the worst part should be over.

The 3 checkboxes on the menu line is for enabling or disabling the functions Draw lines, Weekly charts and the notes window. The Notes box is only visible if database support is enabled (see Options).

Keyboard and mouse input

Please note that the user interface is slightly updated in version 0.5. 'l' and 'L' are now used for selecting lines and endpoints. The "Draw" button is removed so that both selcted sticks and lines may be viewed at the same time. 'v' for view mode can be used for enabling or disabling the line view.

The keyboard and/or the mouse are used for two purposes in the chart panels:

  1. Select a particular day and display additional information about that day
  2. Draw or move lines in the chart area

A day can be selected either by a (left) click on the stick with the mouse or by using the keyboard. The following keys are used for keyboard navigation:

(*) When a line is selected, the arrow keys will be used for moving the line or one of the endpoints.

A selected day will be marked by a dashed box in all indicator panels.

To draw a line in an indicator panel, just press and hold the right mouse button at one of the endpoints. Then move the mouse to the other end of the desired line and release the button. The line will be visible during the operation. If the optional database is enabled the drawn line may be saved to the database by pressing 'CTRL-s'. Displayed lines can be selcted for editing by pressing 'l'. Repeat untill the correct line is selcted. By default the entire line is selcted and can be moved with the arrow keys. To select an end point, press'L' ('SHIFT l').

To select a line only the keyboard can be used

Drawn lines may be moved and deleted by keyboard commands:

Note that movement in the x directions (left, right) is dependent on the size of the candlestick. The reason for this is that in order to display the lines correctly if the panel is resized, the endpoints of a line is stored as date for the x direction and a value for the y direction. As a date is minimum 4 pixels wide, the endpoints may be drawn at a slightly different location than intended.

Show weekly

Enables or disables the drawing of weekly charts. The weekly charts are marked with a yellow "w" on the tabs.

Notes (only with db support enabled)

Opens a separate Notes window where you can add you're own comments.

In the notes window, Date addes the current date at the begin. Watch adds or removes the current ticker from the watchlist. Restore reloads the the notes field from the database. All changes are lost and there's no warnings, I assume you know what you are doing. Clear empties the notes, but what's in the database can still be restored. Save writes the content to the database. Again, there's no undo for this.

Ticker input

Just type in the ticker and press the Get button or "enter". If all things are correctly set up a chart should be drawn.

Exchange input

This is really the file extension, so if that doesn't match the exchange name it might be a bit confusing. A default value will be used at startup, so if all your files has the same extension, just set it up correctly and leave it alone. The default value is set in the system tab of options menu.

Options

Allows you to modify a few of the parameters in the properties files. The path and extension must be correct in order to get the application working.

The RSI option is used to set how many days that shall be used in the RSI calculation. 14 is quite common. Set this to 0 if the RSI graph is unwanted.

Checking the "Enable db" box adds a few db related options. Change to suit your needs. Note that the jstock database and tables has to be created before you attempt to use the database. See the included jstock*.sql file.

Indicators

RSI

Note: Sources on the internet does not agree on how to compute RSI. The formula itself is not the problem, it is (most commenly expressed as):
RSI = 100 - [100/(1+RS)] where
RS = Average of up day's closes / Average of down day's closes

It's the RS part that is the problem - does average of up day closes mean sum of positive changes divided by number of days with positive changes or divided by the whole periode? I have found no definitive answer to this, but the most convincing (to me) sites stick with the whole periode.

It seems that historically the RS part has been computed in a special way. The first value of RSI was computed with division of the whole peridode. The next value was computed by multiplying the previous value with periode -1, then adding/subtracting the new price change and then divide again by the whole periode. By this way a price change once used in the calculation is never completly forgotten and the resulting RSI will vary depending on where you start your calculation.

A note: This is my interpretation of several sources found on the internet, among them:

MA

A simple moving average calculation over n days, where all days has equal weight. Closing price is used in the calculation.

EMA

Exponential moving average calculation over n days. The days close to current days have more weight than older days. Closing price is used in the calculation.

MACD

The Moving Average Convergence/Divergence (MACD) is the difference between 2 EMA's (drawn as tick line). In addition a third EMA is used as a trigger line (drawn as thin line). The difference between MACD and the trigger is drawn as a histogram (yellow boxes).

Database

As I have a postgresql server running I have chosen to use that instead of using a files or an integreted db for storing information that should be preserved. That means that if you intend to use the notes window a sql db is required. I have only tested with Postgresql, but the sql is very simple so others may work. Find a jdbc driver for your db and try. The schema for the db is included.

From my own experience most problems with databases (for new users that is, experienced db users may have their own problems) are access rights dependent. Look at the documentation for the database. It usually helps.

For PostgreSQL users it should be possible to use the jstock.sql more or less directly to create the tables. For other databases it may be necessary to modify the files a bit or create the tables manually. The tables used are:

Database tables used by jStock
Table name Field name Field type Comments
notes index integer not null, primary key
tickerid integer
note text
tickers index integer not null, primary key
exchangeid integer not null
ticker character varying(15) not null
exchange index integer not null, primary key
exchangename character varying(20) not null
events index integer not null, primary key
eventshort character varying(5)
event character varying(20)
watchlist tickerid integer not null, primary key
lines index integer not null, primary key
tickerid integer
type integer
datex1 character(8)
valuey1 double precision
datex2 character(8)
valuey2 double precision

Note that the password for the database is stored in clear text by the application. Create a new user with no or very limited rights outside this database if that is a concern to you. The application needs rights to view insert and delete rows. Future use may also include creating and deleting tables within the database.

Final remark

As I have released this application as open source, I will of course listen to feedback from users others than myself. I am open for requests and/or help with coding. Also, as this started as an attempt to learn Java, I very much would like critique and suggestions on how I could improve the way I write Java. Mail me at: jstock (at) exponto.com