Skip to content

Commit

Permalink
More README updates, break usage into 2 sections
Browse files Browse the repository at this point in the history
  • Loading branch information
atsmith813 committed Mar 19, 2019
1 parent 01a3ce0 commit 80edbd6
Showing 1 changed file with 49 additions and 31 deletions.
80 changes: 49 additions & 31 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -54,8 +54,6 @@ gem install technical-analysis
```

## Usage
There are 2 ways to use this gem for technical analysis.

First, for the sake of these code samples, we'll load some test data from `spec/ta_test_data.csv`. This is the same data used for the unit tests. The data will be an `Array` of `Hashes`.

```ruby
Expand All @@ -68,31 +66,25 @@ input_data = SpecHelper.get_test_data(:close)
# ]
```

### 1) Call the `calculate` method on the specific technical indicator class
```ruby
TechnicalAnalysis::Sma.calculate(input_data, period: 30, price_key: :close)
```

### 2) Call the generic indicator class and pass params to the `calculate` method
The `calculate` method on the `Indicator` class accepts:
- The indicator `symbol` as a String - `"sma"`
- The data to be used for calculations as an Array of Hashes - `input_data`
- The symbol of the calculation to be performed - `:technicals`
- The options for the indicator as a Hash - `options`
```ruby
options = { period: 30, price_key: :close }
TechnicalAnalysis::Indicator.calculate('sma', input_data, :technicals, options)
```

Each technical indicator has the following methods:
- `calculate` - Each technical indicator returns an Array of values. These values are instances of a class specific to each indicator. It's typically in the format of SymbolValue. For example, Simple Moving Average (SMA) returns an Array of `SmaValue` instances. These classes contain the appropriate data fields for each technical indicator.
- `indicator_symbol` returns the symbol of the technical indicator as a String.
- `indicator_name` returns the name of the technical indicator as a String.
- `valid_options` returns an Array of keys (as Symbols) for valid options that the technical indicator accepts in its `calculate` method.
- `validate_options` returns true if the options provided are valid or raises a `ValidationError`.
- `min_data_size` returns the minimum number of observations needed (as an Integer) to calculate the technical indicator based on the options provided.
- `calculate` - Each technical indicator returns an Array of values. These values are instances of a class specific to each indicator. It's typically in the format of SymbolValue. For example, Simple Moving Average (SMA) returns an Array of `SmaValue` instances. These classes contain the appropriate data fields for each technical indicator.

For example:
### Class-Based Usage
You can call methods on the class of the specific technical indicator that you want to calculate. To calculate a Simple Moving Average, for example, you would just call `calculate` on the Simple Moving Average class like so:

```ruby
input_data = SpecHelper.get_test_data(:close)

TechnicalAnalysis::Sma.calculate(input_data, period: 30, price_key: :close)
```

Here are examples of other methods for technical indicators:

```ruby
TechnicalAnalysis::Sma.indicator_symbol
# "sma"
Expand All @@ -112,44 +104,70 @@ TechnicalAnalysis::Sma.min_data_size(options)
# 30
```

### Generic Usage
You can also use the generic indicator class. The purpose of this class is to be a sort of master class that will find and call the correct indicator based on the params provided to it.

The `calculate` method on the `Indicator` class accepts:
- The indicator symbol as a String - `"sma"`
- The data to be used for calculations as an Array of Hashes - `input_data`
- The calculation to be performed as a Symbol - `:technicals`
- The options for the indicator as a Hash - `options`

```ruby
input_data = SpecHelper.get_test_data(:close)
options = { period: 30, price_key: :close }

TechnicalAnalysis::Indicator.calculate('sma', input_data, :technicals, options)
```

Here's each example again using the generic indicator class:

```ruby
input_data = SpecHelper.get_test_data(:close)

TechnicalAnalysis::Indicator.calculate('sma', input_data, :indicator_symbol)
# "sma"

TechnicalAnalysis::Indicator.indicator_name('sma', input_data, :indicator_name)
TechnicalAnalysis::Indicator.calculate('sma', input_data, :indicator_name)
# "Simple Moving Average"

TechnicalAnalysis::Indicator.valid_options('sma', input_data, :valid_options)
TechnicalAnalysis::Indicator.calculate('sma', input_data, :valid_options)
# [:period, :price_key]

options = { period: 30, price_key: :close }
TechnicalAnalysis::Indicator.validate_options('sma', input_data, :validate_options, options)
TechnicalAnalysis::Indicator.calculate('sma', input_data, :validate_options, options)
# true

options = { period: 30, price_key: :close }
TechnicalAnalysis::Indicator.min_data_size('sma', input_data, :min_data_size, options)
TechnicalAnalysis::Indicator.calculate('sma', input_data, :min_data_size, options)
# 30
```

Or you can use it to find the correct technical indicator class based on symbol:
```ruby
input_data = SpecHelper.get_test_data(:close)
Or you can use it to find the correct technical indicator class based on indicator symbol:

indicator = TechnicalAnalysis::Indicator.find("sma")
```ruby
simple_moving_average = TechnicalAnalysis::Indicator.find("sma")
# TechnicalAnalysis::Sma

indicator.indicator_symbol
input_data = SpecHelper.get_test_data(:close)
simple_moving_average.calculate(input_data, period: 30, price_key: :close)

simple_moving_average.indicator_symbol
# "sma"

indicator.indicator_name
simple_moving_average.indicator_name
# "Simple Moving Average"

indicator.calculate(input_data, period: 30, price_key: :close)
simple_moving_average.valid_options
# [:period, :price_key]

options = { period: 30, price_key: :close }
simple_moving_average.validate_options(options)
# true

options = { period: 30, price_key: :close }
simple_moving_average.min_data_size(options)
# 30
```

## Further documentation
Expand Down

0 comments on commit 80edbd6

Please sign in to comment.