Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[#54] README.Rmd updated #56

Merged
merged 1 commit into from
Mar 18, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
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.

Loading