@acransac/index 中文文档教程

Question

Introduction

index 是一个命令行程序，可以打印一系列投资业绩的报告。 绩效由指数来衡量，这些指数用图表、亮点和完整的价值列表来描述。 目前，指数是：

• the relative market value of the investment compared with the first valuation. For example, starting with 100, a reading of 101.23 means that the assets appreciated by 1.23% relatively to the inception value. This index is not affected by cashing into or out of the investment.
• the return on investment. This is the ratio of cash withdrawn to cash invested over time, considering a full sale of assets and cash out at the date of the index computation. The time value of cash flows is not accounted for.

该程序的输入是用户提供的描述投资的 json 数据，特别是市场价值和现金流的时间序列。 用户选择要报告的时间间隔。 输出旨在易于在终端（甚至是图形）中打印和阅读，并被格式化为 Markdown。

例如，请参阅此处，在 Vanguard 的交易所交易基金 VOO（跟踪 S& ;P500 指数）在 2020 年作为指数的输出。

Installation

index 作为 npm 包交付，如果全局安装则使用起来更方便：

    $ npm install --global @acransac/index

可以通过以下方式卸载：

    $ npm uninstall --global @acransac/index

Usage

Providing Input

程序的输入是描述资产市场价值和现金流量的 json 数据或随着时间的推移从投资中退出。

一项投资称为基金，输入中可以有多项投资。 除了估值和现金流量表之外，基金还有一个名称和一种基础货币，用于表示市场价值和现金流量。

架构如下：

    <input>        ::= <fund>+
    <fund>         ::= <fundName> <currency> <assetsValue>+
    <fundName>     ::= string
    <currency>     ::= string
    <assetsValue>  ::= <valueDate> <marketValue> <addedCash>
    <valueDate>    ::= string
    <marketValue>  ::= number
    <addedCash>    ::= number

起息日的格式为 YYYY-MM-DD，添加的现金分别为存款正数和取款负数。

查看 json 输入示例：

[
  {
    "fundName": "Investments In The USA",
    "currency": "USD",
    "assetsValues":
      [
        {"valueDate": "2020-01-01", "marketValue": 1000.00, "addedCash": 1000.00},
        {"valueDate": "2020-12-31", "marketValue": 1100.00, "addedCash": 0.00}
      ]
  },
  {
    "fundName": "Investments In The EU",
    "currency": "EUR",
    "assetsValues":
      [
        {"valueDate": "2021-01-01", "marketValue": 1000.00, "addedCash": 1000.00}
      ]
  }
]

您还可以在此处查看介绍示例的输入。

Using The Command Line Program

首先，简要总结一下如何使用 index 以及以下选项可用的选项：

    $ index --help

您可以通过将 json 数据管道化或将其路径作为参数来为程序提供输入命令。 然后，您可以调整两个参数：

• the time interval to report on. You can specify a begin date and / or an end date. If you don't, the earliest and / or the latest valuations' dates are used. The format is YYYY-MM-DD. Note that this interval has no impact on the computation of the indices, it just focuses the reports on the given time period.
• the dimensions of the charts, height and width. The former is only for comfort of reading but the latter has an impact on the accuracy. Indeed, the charts are just printed characters so that every printed column covers a fixed slice of the choosen time interval. Increasing the width, that is the number of columns, allows the latter to cover smaller amounts of time hence revealing patterns of shorter terms.

尝试一下，打印 介绍示例

    $ cat docs/example.json | index

或

    $ index docs/example.json

自定义输出:

    $ index docs/example.json -b 2020-07-01 -e 2021-01-01 -h 20 -w 140