Merge pull request #21 from mquirosq/master

Fixed typos, errors and examples in the wiki

Backtesting.md

@@ -11,7 +11,7 @@ Backtesting is the main use case of ta4j.
 
 ### Running your backtest
 
-Once you constructed [your time series](Time-series-and-bars.md) and [your trading strategy](Trading-strategies.md), you can backtest the strategy by just calling:
+Once you constructed [your bar series](Bar-series-and-bars.md) and [your trading strategy](Trading-strategies.md), you can backtest the strategy by just calling:
 
 ```java
 BarSeries series = ...
@@ -22,7 +22,7 @@ TradingRecord tradingRecord = seriesManager.run(myStrategy);
 ```
 
 That's it! You get a `TradingRecord` object which is the record of the resulting trading session (basically a list of trades/orders).
-By providing different strategies to the `TimeSeriesManager#run(Strategy)` methods, you get different `TradingRecord` objects and you can compare them according to analysis criteria.
+By providing different strategies to the `BarSeriesManager#run(Strategy)` methods, you get different `TradingRecord` objects and you can compare them according to analysis criteria.
 
 ### Analyzing strategies
 

Bar-series-and-bars.md

@@ -0,0 +1,90 @@
+# Bar Series and Bars
+A `BarSeries` contains the aggregated data of a security/commodity into fixed intervals. Each interval ending is represented by a Bar.
+
+A `Bar` contains aggregated data of a security/commodity during a time period. "Aggregated" means that the Bar object does not contain direct exchange data. It merges all the orders operated during the time period and extract:
+
+  * an open price
+  * a high price
+  * a low price
+  * a close price
+  * a volume
+
+A Bar is the basic building block of a BarSeries. Then the bar series is used for backtesting or live trading.
+
+> Since release 0.12 the BarSeries and Bars supports different data types for storing the data and calculating.
+> Since release 0.12 the bar creation and management has moved to the BarSeries. That means it is possible to add the data of a bar directly to the BarSeries via #addBar(...) functions
+
+### Bar series for backtesting
+
+In order to backtest a strategy you need to fill a bar series with past data. To do that you just have to create a BarSeries and add data to it. The following example shows how to create a `BaseBarSeries` with help of the ``SeriesBuilder`` and how to add data to the series:
+
+```java
+BarSeries series = new BaseBarSeriesBuilder().withName("my_2017_series").build();
+
+ZonedDateTime endTime = ZonedDateTime.now();
+series.addBar(endTime, 105.42, 112.99, 104.01, 111.42, 1337);
+series.addBar(endTime.plusDays(1), 111.43, 112.83, 107.77, 107.99, 1234);
+series.addBar(endTime.plusDays(2), 107.90, 117.50, 107.90, 115.42, 4242);
+//...
+
+```
+
+You can also use a Builder for creating bars:
+
+````java
+BaseBar bar = BaseBar.builder(DecimalNum::valueOf, Number.class)
+                .timePeriod(Duration.ofDays(1))
+                .endTime(endTime)
+                .openPrice(openPrice)
+                .highPrice(highPrice)
+                .lowPrice(lowPrice)
+                .closePrice(closePrice)
+                .volume(volume)
+                .build();
+
+series.addBar(bar);
+
+````
+
+[Those examples](Usage-examples.html) show how to load bar series in order to backtest strategies over them.
+
+For this use case, the BarSeries class provides helper methods to split the series into sub-series, run a trading strategy, etc.
+
+### Bar series for live trading
+
+Live trading involves building a bar series for current prices. In this use case you just have to initialize your series.
+
+```java
+BarSeries series = new BaseBarSeries("my_live_series");
+```
+
+Then for each bar received from the broker/exchange you have to add it to your series:
+
+```java
+series.addBar(ZonedDateTime.now(), 105.42, 112.99, 104.01, 111.42, 1337);
+```
+
+Or if you are receiving interperiodic prices and want to add it to the last bar:
+
+```java
+series.addPrice(105.44); // will update the close price of the last bar (and min/max price if necessary)
+```
+
+The `BarSeries#addTrade(Number, Number)` function allows you to update the last `Bar` of the series with price and volume data:
+
+```java
+series.addTrade(price, volume);
+```
+
+You can use the `BarSeries#addBar(Bar, boolean)` function, thats `replaces` the last `Bar` of the series if the `boolean` flag is `true`.
+
+```java
+series.addBar(bar, true) // last bar will be replaced
+```
+
+In this mode, we strongly advise you to:
+
+  * initialize your series with the last data from the exchange (as it's described above for backtesting). It ensures your trading strategy will get enough data to be relevant.
+  * call the `BarSeries#setMaximumBarCount(int)` method on your series. It ensures that your memory consumption won't increase infinitely.
+
+**Warning!** Setting a maximum bar count to the series will turn it into a *moving* bar series. In this mode trying to get a removed bar will return the first bar found (i.e. the oldest still in memory). It may involve approximations but only for old bars.

FAQ.md

@@ -3,7 +3,7 @@
 We are at [discord](https://discord.gg/HX9MbWZ). Create your account and join!
 
 ### How to make a sell/short order when running a `Strategy` ?
-You can determine the kind of order in the `TimeSeriesManager#run` method with help of the `OrderType` parameter:
+You can determine the kind of order in the `BarSeriesManager#run` method with help of the `OrderType` parameter:
 
 ```java
 /**
@@ -18,8 +18,8 @@ public TradingRecord run(Strategy strategy, OrderType orderType) {
     return run(strategy, orderType, NaN);
 }
 ```
-The standard value for this mehtod is `OrderType.BUY`. That means entry signals generated by your `Strategy` will create a buying order and every exit signal will create a complementary (in this case `OrderType.SELL`) order. If you change this parameter to `OrderType.SELL`, the `TimeSeriesManager` will create **selling** orders for entry signals and **buying** orders for exit signals.
-* **Note:** At the moment it is only possible to run a `Strategy` with [long](https://www.investopedia.com/terms/l/long.asp) (buy-sell) **or** with [short](https://www.investopedia.com/terms/s/short.asp) (sell-buy) trades. There is no possibility to mix short and long trades in one and the same run done by the `TimeSeriesManager`.
+The standard value for this mehtod is `OrderType.BUY`. That means entry signals generated by your `Strategy` will create a buying order and every exit signal will create a complementary (in this case `OrderType.SELL`) order. If you change this parameter to `OrderType.SELL`, the `BarSeriesManager` will create **selling** orders for entry signals and **buying** orders for exit signals.
+* **Note:** At the moment it is only possible to run a `Strategy` with [long](https://www.investopedia.com/terms/l/long.asp) (buy-sell) **or** with [short](https://www.investopedia.com/terms/s/short.asp) (sell-buy) trades. There is no possibility to mix short and long trades in one and the same run done by the `BarSeriesManager`.
 
 ### What does `Num` or `Function<Number, Num>`?
 
@@ -29,13 +29,14 @@ With help of the `Num` interface and a `Function<Number, Num>` ta4j enables the
 
 If you are using an `Indicator` that uses an exponential moving average (EMA) such as `EMAIndicator` or `RSIIndicator` then you will have to understand data length dependence and convergence.  The short answer is that you need to "seed" your `Indicator` with several hundred `Bars` of data prior to the indices for which you seek the values or those values will have relatively large error.
 
-Since EMA's use the prior value in their calculation, the values depend on how many prior values you have.  Related, there is some question as to how to initialize the first value of an EMA.  The first problem is generally solved by including at least 200 `Bars` of `TimeSeries` data prior to the indices for which you are interested.  The second problem is currently solved by setting the first EMA value to the first data value:
+Since EMA's use the prior value in their calculation, the values depend on how many prior values you have.  Related, there is some question as to how to initialize the first value of an EMA.  The first problem is generally solved by including at least 200 `Bars` of `BarSeries` data prior to the indices for which you are interested.  The second problem is currently solved by setting the first EMA value to the first data value:
 ```
 @Override
 protected Num calculate(int index) {
     if (index == 0) {
         return indicator.getValue(0);
     }
+}
 ```
 If a different solution to initialization is required, then the `EMAIndicator` may be extended to a subclass with a different solution to `if (index == 0)`.
 

Getting-started.md

@@ -1,5 +1,4 @@
 # Getting Started
-
 Ta4j is an open source Java library for technical analysis. It provides the basic components for creation, evaluation and execution of trading strategies.
 
 About technical analysis:
@@ -17,71 +16,71 @@ Ta4j is available on Maven. You can [create a Maven project](http://www.tech-rec
   <version>0.15</version>
 </dependency>
 ```
-Another way could be to [clone this git repository](https://git-scm.com/book/en/v1/Git-Basics-Getting-a-Git-Repository) or to simply download this library and add the source code to your existing eclipse project.
+Another way could be to [clone this git repository](https://git-scm.com/book/en/v2/Git-Basics-Getting-a-Git-Repository) or to simply download this library and add the source code to your existing eclipse project.
 
 ### Getting started with ta4j
 
-In this quick example we will backtest a trading strategy over a price time series.
+In this quick example we will backtest a trading strategy over a price bar series.
 
-At the beginning we just need a time series.
+At the beginning we just need a bar series.
 
 ```java
-// Creating a time series (from any provider: CSV, web service, etc.)
-BarSeries series = new BaseBarSeriesBuilder().withName("AXP_Stock").build();
+// Creating a bar series (from any provider: CSV, web service, etc.)
+BarSeries series = CsvTradesLoader.loadBitstampSeries();
 ```
-After createing a `TimeSeries` we can add OHLC data and volume to the series:
+After creating a `BarSeries` we can add OHLC data and volume to the series:
 
 ```java
 // adding open, high, low, close and volume data to the series
 series.addBar(ZonedDateTime.now(), 105.42, 112.99, 104.01, 111.42, 1337);
-
 ```
-See the [Bar Series and Bars section](Time-series-and-bars.html) to learn about time series and to know how you can construct one.
+See the [Bar Series and Bars section](Bar-series-and-bars.html) to learn about bar series and to know how you can construct one.
 
 ##### Using indicators
 
 We can calculate indicator over this bar series, in order to forecast the direction of prices through the study of past market data.
 
 ```java
-// Getting the close price of the ticks
+// Getting the close price of the bars
 Num firstClosePrice = series.getBar(0).getClosePrice();
 System.out.println("First close price: " + firstClosePrice.doubleValue());
 // Or within an indicator:
 ClosePriceIndicator closePrice = new ClosePriceIndicator(series);
 // Here is the same close price:
 System.out.println(firstClosePrice.isEqual(closePrice.getValue(0))); // equal to firstClosePrice
 
-// Getting the simple moving average (SMA) of the close price over the last 5 ticks
+// Getting the simple moving average (SMA) of the close price over the last 5 bars
 SMAIndicator shortSma = new SMAIndicator(closePrice, 5);
-// Here is the 5-ticks-SMA value at the 42nd index
-System.out.println("5-ticks-SMA value at the 42nd index: " + shortSma.getValue(42).doubleValue());
+// Here is the 5-bars-SMA value at the 42nd index
+System.out.println("5-bars-SMA value at the 42nd index: " + shortSma.getValue(42).doubleValue());
 
-// Getting a longer SMA (e.g. over the 30 last ticks)
+// Getting a longer SMA (e.g. over the 30 last bars)
 SMAIndicator longSma = new SMAIndicator(closePrice, 30);
 ```
 Ta4j includes more than 130 [technical indicators](Technical-indicators.html).
 
 ##### Building a trading strategy
 
-Then we have to build our trading strategy. It is made of two trading rules: one for entry, the other for exit.
+Then we have to build our trading strategy. Strategies are made of two trading rules: one for entry (buying), the other for exit (selling).
 
 ```java
 // Buying rules
 // We want to buy:
-//  - if the 5-ticks SMA crosses over 30-ticks SMA
+//  - if the 5-bars SMA crosses over 30-bars SMA
 //  - or if the price goes below a defined price (e.g $800.00)
 Rule buyingRule = new CrossedUpIndicatorRule(shortSma, longSma)
-        .or(new CrossedDownIndicatorRule(closePrice, 800d));
+        .or(new CrossedDownIndicatorRule(closePrice, 800));
 
 // Selling rules
 // We want to sell:
-//  - if the 5-ticks SMA crosses under 30-ticks SMA
+//  - if the 5-bars SMA crosses under 30-bars SMA
 //  - or if the price loses more than 3%
 //  - or if the price earns more than 2%
 Rule sellingRule = new CrossedDownIndicatorRule(shortSma, longSma)
-        .or(new StopLossRule(closePrice, 3.0))
-        .or(new StopGainRule(closePrice, 2.0));
+        .or(new StopLossRule(closePrice, series.numOf(3)))
+        .or(new StopGainRule(closePrice, series.numOf(2)));
 
+// Create the strategy
 Strategy strategy = new BaseStrategy(buyingRule, sellingRule);
 ```
 
@@ -93,31 +92,31 @@ The backtest step is pretty simple:
 
 ```java
 // Running our juicy trading strategy...
-BarSeriesManager manager = new BarSeriesManager(series);
-TradingRecord tradingRecord = manager.run(strategy);
-System.out.println("Number of trades for our strategy: " + tradingRecord.getTradeCount());
+BarSeriesManager seriesManager = new BarSeriesManager(series);
+TradingRecord tradingRecord = seriesManager.run(strategy);
+System.out.println("Number of positions (trades) for our strategy: " + tradingRecord.getPositionCount());
 ```
 
 ##### Analyzing our results
 
 Here is how we can analyze the results of our backtest:
 
 ```java
-// Getting the profitable trades ratio
-AnalysisCriterion profitTradesRatio = new AverageProfitableTradesCriterion();
-System.out.println("Profitable trades ratio: " + profitTradesRatio.calculate(series, tradingRecord));
-// Getting the reward-risk ratio
-AnalysisCriterion rewardRiskRatio = new RewardRiskRatioCriterion();
-System.out.println("Reward-risk ratio: " + rewardRiskRatio.calculate(series, tradingRecord));
-
-// Total profit of our strategy
-// vs total profit of a buy-and-hold strategy
-AnalysisCriterion vsBuyAndHold = new VersusBuyAndHoldCriterion(new TotalProfitCriterion());
-System.out.println("Our profit vs buy-and-hold profit: " + vsBuyAndHold.calculate(series, tradingRecord));
+// Getting the winning positions ratio
+AnalysisCriterion winningPositionsRatio = new PositionsRatioCriterion(PositionFilter.PROFIT);
+System.out.println("Winning positions ratio: " + winningPositionsRatio.calculate(series, tradingRecord));
+
+// Getting a risk-reward ratio
+AnalysisCriterion romad = new ReturnOverMaxDrawdownCriterion();
+System.out.println("Return over Max Drawdown: " + romad.calculate(series, tradingRecord));
+
+// Total return of our strategy vs total return of a buy-and-hold strategy
+AnalysisCriterion vsBuyAndHold = new VersusEnterAndHoldCriterion(new ReturnCriterion());
+System.out.println("Our return vs buy-and-hold return: " + vsBuyAndHold.calculate(series, tradingRecord));
 ```
 
 Trading strategies can be easily compared according to [a set of analysis criteria](Backtesting.html).
 
 ### Going further
 
-Ta4j can also be used for [live trading](Live-trading.html) with more complicated [strategies](Trading-strategies.html). Check out the rest of the documentation and [the examples](Usage-examples.html).
+Ta4j can also be used for [live trading](Live-trading.html) with more complicated [strategies](Trading-strategies.html). Check out the rest of the documentation and [the examples](Usage-examples.html).

How-to-contribute.md

@@ -45,10 +45,10 @@ The last step would be to do a pull request **from your branch to the `master` b
 (in progress...)<br>
 First things first: Feel free to write awesome code! Do not hesitate to open an issue or a pull request just because you fear making a mistake. Others can review your code, give you tips and can correct you.
 * Be aware that your code is easily legible and transparent.
-* Stay in scope of your pull request. Do not make changes all over the project in one pull request. For example if you want to add a new indicator add but you also found bugs or little enhancements on TimeSeries and TradingRecord **fix them in a new pull request**.
+* Stay in scope of your pull request. Do not make changes all over the project in one pull request. For example if you want to add a new indicator add but you also found bugs or little enhancements on BarSeries and TradingRecord **fix them in a new pull request**.
 
 ## Hints
-* use `int startIndex = timeSeries.getBeginIndex()` instead of `int startIndex = 0` to get the first valid index of a TimeSeries.
+* use `int startIndex = BarSeries.getBeginIndex()` instead of `int startIndex = 0` to get the first valid index of a BarSeries.
 * ***Note the difference between `Decimal.min(other)` and` Decimal.minus(other)`***
 * It is not possible to store static references to ``Num`` implementations because they will be determined at runtime. If necessary store primitives and use the `numOf(Number n)` or the `numFunction` of series in the constructor. If you are using ``DoubleNum::valueOf`` or ``BigDecimalNum::valueOf`` you most probably do something wrong.
 * **Use primitive as inidcator parameters.*** For example a timeFrame parameter should be an ``int`` and a percentage value parameter should be ``double`` (avoid ``Num``). You can **convert a ``Number`` into ``Num`` using the ``numOf`` function**. This prevents that the user has to convert primitive input values to ``Num`` implementations manually.