Skip to content

Commit

Permalink
Merge pull request #56 from matthiasgomolka/#54
Browse files Browse the repository at this point in the history
[#54] README.Rmd updated
  • Loading branch information
matthiasgomolka authored Mar 18, 2024
2 parents 30f09f0 + d6a7758 commit ccbc87f
Show file tree
Hide file tree
Showing 5 changed files with 51 additions and 151 deletions.
84 changes: 26 additions & 58 deletions README.Rmd
Original file line number Diff line number Diff line change
Expand Up @@ -24,26 +24,25 @@ options("future.rng.onMisuse" = "ignore")
theme_set(theme_minimal())
```

# simfinapi <img src='man/figures/logo.png' align="right" height="139" />
# simfinapi <img src="man/figures/logo.png" align="right" height="139"/>

`r badge_lifecycle("experimental")`
[![CRAN release](https://www.r-pkg.org/badges/version/simfinapi)](https://CRAN.R-project.org/package=simfinapi)
`r badge_lifecycle("experimental")` [![CRAN
release](https://www.r-pkg.org/badges/version/simfinapi)](https://CRAN.R-project.org/package=simfinapi)
[![Status](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active)
[![R-CMD-check](https://github.com/matthiasgomolka/simfinapi/workflows/R-CMD-check/badge.svg)](https://github.com/matthiasgomolka/simfinapi/actions)
[![](https://codecov.io/gh/matthiasgomolka/simfinapi/branch/main/graph/badge.svg)](https://app.codecov.io/gh/matthiasgomolka/simfinapi)
`r badge_dependencies()`

## What does simfinapi do?
simfinapi wraps the https://www.simfin.com/ Web-API to make 'SimFin' data easily
available in R.

*To use the package, you need to register at https://app.simfin.com/login and obtain
a 'SimFin' API key.*
simfinapi wraps the <https://www.simfin.com/> Web-API to make 'SimFin' data easily available in R.

*To use the package, you need to register at <https://app.simfin.com/login> and obtain a 'SimFin'
API key.*

## Example
In this example, we download some stock price data and turn these into a simple
plot.

In this example, we download some stock price data and turn these into a simple plot.

```{r download_data}
# load package
Expand All @@ -52,11 +51,11 @@ devtools::load_all()
# download stock price data
tickers <- c("AMZN", "GOOG") # Amazon, Google
prices <- sfa_get_prices(tickers)
prices <- sfa_load_shareprices(tickers)
```

Please note that all functions in simfinapi start with the prefix `sfa_`. This
makes it easy to find all available functionality.
Please note that all functions in simfinapi start with the prefix `sfa_`. This makes it easy to
find all available functionality.

The downloaded data looks like this:

Expand All @@ -72,67 +71,36 @@ library(ggplot2)
# create plot
ggplot(prices) +
aes(x = date, y = close, color = ticker) +
geom_line()
```

Suppose we would like to display the actual company name instead of the ticker.
To do so, we download additional company information and merge it to the
`prices` data:

```{r download_info}
company_info <- sfa_get_info(tickers)
```

`company_info` contains these information:

```{r show_info, echo=FALSE}
kable(company_info)
```

Now we merge both datasets and recreate the plot with the actual company names.

```{r recreate_plot}
# merge data
merged <- merge(prices, company_info, by = "ticker")
# recreate plot
ggplot(merged) +
aes(x = date, y = close, color = company_name) +
aes(x = Date, y = `Last Closing Price`, color = name) +
geom_line()
```

## Installation

From [CRAN](https://CRAN.R-project.org/package=simfinapi):

```{r install_cran, eval = FALSE}
install.packages("simfinapi")
```
If you want to try out the newest features you may want to give the development
version a try and install it from
[GitHub](https://github.com/matthiasgomolka/simfinapi):

If you want to try out the newest features you may want to give the development version a try and
install it from [GitHub](https://github.com/matthiasgomolka/simfinapi):

```{r install_github, eval=FALSE}
remotes::install_github("https://github.com/matthiasgomolka/simfinapi")
```

## Setup
Using simfinapi is much more convenient if you set your API key and cache
directory^[simfinapi always caches the results from your API calls to obtain
results quicker and to reduce the number of API calls. If you set the cache
directory to a permanent directory (the default is `tempdir()`), simfinapi will
be able to reuse this cache in subsequent R sessions.] globally before you start
downloading data. See `?sfa_set_api_key` and `?sfa_set_cache_dir` for details.

## Code of Conduct
Please note that the 'simfinapi' project is released with a [Contributor Code of
Conduct](https://github.com/matthiasgomolka/simfinapi/blob/master/.github/CODE_OF_CONDUCT.md).
By contributing to this project, you agree to abide by its terms.
Using simfinapi is much more convenient if you set your API key and cache directory[^1] globally
before you start downloading data. See `?sfa_set_api_key` and `?sfa_set_cache_dir` for details.

## Relation to `simfinR`
[^1]: simfinapi always caches the results from your API calls to obtain results quicker and to
reduce the number of API calls. If you set the cache directory to a permanent directory (the
default is `tempdir()`), simfinapi will be able to reuse this cache in subsequent R sessions.

In case you also found `simfinR` ([CRAN](https://CRAN.R-project.org/package=simfinR),
[GitHub](https://github.com/msperlin/simfinR/)) you might want to know about the
differences between the `simfinapi` and `simfinR`. I tried to compile a list in
[this issue](https://github.com/matthiasgomolka/simfinapi/issues/22#issuecomment-847270864).
## Code of Conduct

---
Please note that the 'simfinapi' project is released with a [Contributor Code of
Conduct](https://github.com/matthiasgomolka/simfinapi/blob/master/.github/CODE_OF_CONDUCT.md). By
contributing to this project, you agree to abide by its terms.
107 changes: 22 additions & 85 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,26 +1,16 @@
# simfinapi <img src="man/figures/logo.png" align="right" height="139"/>

# simfinapi <img src='man/figures/logo.png' align="right" height="139" />

[![](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://lifecycle.r-lib.org/articles/stages.html#experimental)
[![CRAN
release](https://www.r-pkg.org/badges/version/simfinapi)](https://CRAN.R-project.org/package=simfinapi)
[![Status](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active)
[![R-CMD-check](https://github.com/matthiasgomolka/simfinapi/workflows/R-CMD-check/badge.svg)](https://github.com/matthiasgomolka/simfinapi/actions)
[![](https://codecov.io/gh/matthiasgomolka/simfinapi/branch/main/graph/badge.svg)](https://app.codecov.io/gh/matthiasgomolka/simfinapi)
[![Dependencies](https://tinyverse.netlify.com/badge/simfinapi)](https://cran.r-project.org/package=simfinapi)
[![](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://lifecycle.r-lib.org/articles/stages.html#experimental) [![CRAN release](https://www.r-pkg.org/badges/version/simfinapi)](https://CRAN.R-project.org/package=simfinapi) [![Status](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active) [![R-CMD-check](https://github.com/matthiasgomolka/simfinapi/workflows/R-CMD-check/badge.svg)](https://github.com/matthiasgomolka/simfinapi/actions) [![](https://codecov.io/gh/matthiasgomolka/simfinapi/branch/main/graph/badge.svg)](https://app.codecov.io/gh/matthiasgomolka/simfinapi) [![Dependencies](https://tinyverse.netlify.com/badge/simfinapi)](https://cran.r-project.org/package=simfinapi)

## What does simfinapi do?

simfinapi wraps the <https://www.simfin.com/> Web-API to make ‘SimFin’ data
easily available in R.
simfinapi wraps the <https://www.simfin.com/> Web-API to make ‘SimFin’ data easily available in R.

*To use the package, you need to register at <https://app.simfin.com/login>
and obtain a ‘SimFin’ API key.*
*To use the package, you need to register at <https://app.simfin.com/login> and obtain a ‘SimFin’ API key.*

## Example

In this example, we download some stock price data and turn these into a
simple plot.
In this example, we download some stock price data and turn these into a simple plot.

``` r
# load package
Expand All @@ -30,22 +20,21 @@ devtools::load_all()

# download stock price data
tickers <- c("AMZN", "GOOG") # Amazon, Google
prices <- sfa_get_prices(tickers)
prices <- sfa_load_shareprices(tickers)
```

Please note that all functions in simfinapi start with the prefix
`sfa_`. This makes it easy to find all available functionality.
Please note that all functions in simfinapi start with the prefix `sfa_`. This makes it easy to find all available functionality.

The downloaded data looks like this:

| id | ticker | date | currency | open | high | low | close | adj_close | volume | dividend | common_shares_outstanding |
|----------:|:-------|:-----------|:---------|-----:|-----:|-----:|------:|----------:|----------:|---------:|--------------------------:|
| 62747 | AMZN | 2000-01-03 | USD | 4.08 | 4.48 | 4.00 | 4.47 | 4.47 | 322352000 | NA | NA |
| 62747 | AMZN | 2000-01-04 | USD | 4.27 | 4.58 | 4.09 | 4.10 | 4.10 | 349748000 | NA | NA |
| 62747 | AMZN | 2000-01-05 | USD | 3.54 | 3.76 | 3.48 | 3.59 | 3.59 | 769148000 | NA | NA |
| 62747 | AMZN | 2000-01-06 | USD | 3.57 | 3.63 | 3.20 | 3.28 | 3.28 | 375040000 | NA | NA |
| 62747 | AMZN | 2000-01-07 | USD | 3.35 | 3.52 | 3.31 | 3.48 | 3.48 | 210108000 | NA | NA |
| 62747 | AMZN | 2000-01-10 | USD | 3.63 | 3.63 | 3.28 | 3.46 | 3.46 | 295158000 | NA | NA |
| name | id | ticker | currency | Date | Dividend Paid | Common Shares Outstanding | Last Closing Price | Adjusted Closing Price | Highest Price | Lowest Price | Opening Price | Trading Volume |
|:------------------|----:|:-------|:---------|:-----------|--------------:|--------------------------:|-------------------:|-----------------------:|--------------:|-------------:|--------------:|---------------:|
| Alphabet (Google) | 18 | GOOG | USD | 2014-03-27 | NA | 6721016620 | 27.92 | 27.92 | 28.40 | 27.65 | 28.40 | 262000 |
| Alphabet (Google) | 18 | GOOG | USD | 2014-03-28 | NA | 6721016620 | 28.00 | 28.00 | 28.32 | 27.93 | 28.06 | 822000 |
| Alphabet (Google) | 18 | GOOG | USD | 2014-03-31 | NA | 13489240000 | 27.85 | 27.85 | 28.35 | 27.85 | 28.34 | 216000 |
| Alphabet (Google) | 18 | GOOG | USD | 2014-04-01 | NA | 13489240000 | 28.36 | 28.36 | 28.42 | 27.94 | 27.94 | 158000 |
| Alphabet (Google) | 18 | GOOG | USD | 2014-04-02 | NA | 13489240000 | 28.35 | 28.35 | 30.24 | 28.11 | 28.26 | 2934000 |
| Alphabet (Google) | 18 | GOOG | USD | 2014-04-03 | NA | 13489240000 | 28.49 | 28.49 | 29.36 | 28.21 | 28.49 | 101704000 |

Let’s turn that into a simple plot.

Expand All @@ -55,41 +44,11 @@ library(ggplot2)

# create plot
ggplot(prices) +
aes(x = date, y = close, color = ticker) +
aes(x = Date, y = `Last Closing Price`, color = name) +
geom_line()
```

<img src="man/figures/README-plot_data-1.png" width="100%" />

Suppose we would like to display the actual company name instead of the
ticker. To do so, we download additional company information and merge
it to the `prices` data:

``` r
company_info <- sfa_get_info(tickers)
```

`company_info` contains these information:

| id | ticker | company_name | industry_id | month_fy_end | number_employees | business_summary |
|----------:|:-------|:------------------|------------:|-------------:|-----------------:|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| 62747 | AMZN | AMAZON COM INC | 103002 | 12 | 1298000 | Amazon.com Inc is an online retailer. The Company sells its products through the website which provides services, such as advertising services and co-branded credit card agreements. It also offers electronic devices like Kindle e-readers and Fire tablets. |
| 18 | GOOG | Alphabet (Google) | 101002 | 12 | 135301 | Alphabet (formerly known as Google) offers a variety of IT services to individuals and corporations alike. Their main revenues come from online advertising. |

Now we merge both datasets and recreate the plot with the actual company
names.

``` r
# merge data
merged <- merge(prices, company_info, by = "ticker")

# recreate plot
ggplot(merged) +
aes(x = date, y = close, color = company_name) +
geom_line()
```

<img src="man/figures/README-recreate_plot-1.png" width="100%" />
<img src="man/figures/README-plot_data-1.png" width="100%"/>

## Installation

Expand All @@ -99,40 +58,18 @@ From [CRAN](https://CRAN.R-project.org/package=simfinapi):
install.packages("simfinapi")
```

If you want to try out the newest features you may want to give the
development version a try and install it from
[GitHub](https://github.com/matthiasgomolka/simfinapi):
If you want to try out the newest features you may want to give the development version a try and install it from [GitHub](https://github.com/matthiasgomolka/simfinapi):

``` r
remotes::install_github("https://github.com/matthiasgomolka/simfinapi")
```

## Setup

Using simfinapi is much more convenient if you set your API key and
cache directory[^1] globally before you start downloading data. See
`?sfa_set_api_key` and `?sfa_set_cache_dir` for details.
Using simfinapi is much more convenient if you set your API key and cache directory[^readme-1] globally before you start downloading data. See `?sfa_set_api_key` and `?sfa_set_cache_dir` for details.

## Code of Conduct
[^readme-1]: simfinapi always caches the results from your API calls to obtain results quicker and to reduce the number of API calls. If you set the cache directory to a permanent directory (the default is `tempdir()`), simfinapi will be able to reuse this cache in subsequent R sessions.

Please note that the ‘simfinapi’ project is released with a [Contributor
Code of
Conduct](https://github.com/matthiasgomolka/simfinapi/blob/master/.github/CODE_OF_CONDUCT.md).
By contributing to this project, you agree to abide by its terms.

## Relation to `simfinR`

In case you also found `simfinR`
([CRAN](https://CRAN.R-project.org/package=simfinR),
[GitHub](https://github.com/msperlin/simfinR/)) you might want to know
about the differences between the `simfinapi` and `simfinR`. I tried to
compile a list in [this
issue](https://github.com/matthiasgomolka/simfinapi/issues/22#issuecomment-847270864).

------------------------------------------------------------------------
## Code of Conduct

[^1]: simfinapi always caches the results from your API calls to obtain
results quicker and to reduce the number of API calls. If you set
the cache directory to a permanent directory (the default is
`tempdir()`), simfinapi will be able to reuse this cache in
subsequent R sessions.
Please note that the ‘simfinapi’ project is released with a [Contributor Code of Conduct](https://github.com/matthiasgomolka/simfinapi/blob/master/.github/CODE_OF_CONDUCT.md). By contributing to this project, you agree to abide by its terms.
Binary file modified man/figures/README-plot_data-1.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
3 changes: 3 additions & 0 deletions simfinapi.Rproj
Original file line number Diff line number Diff line change
Expand Up @@ -22,3 +22,6 @@ PackageCheckArgs: --as-cran
PackageRoxygenize: rd,collate,namespace,vignette

QuitChildProcessesOnExit: Yes

MarkdownWrap: Column
MarkdownWrapAtColumn: 99
8 changes: 0 additions & 8 deletions simfinapi.code-workspace

This file was deleted.

0 comments on commit ccbc87f

Please sign in to comment.