Merge pull request #24 from psrenergy/mk/add-quiver-docs

Adding documentation for Quiver: home, reading, writing and examples

.github/workflows/documentation.yml

@@ -0,0 +1,22 @@
+name: Documentation
+on:
+  push:
+    branches: [master]
+    tags: '*'
+  pull_request:
+    types: [opened, synchronize, reopened]
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: julia-actions/setup-julia@latest
+        with:
+          # Build documentation on Julia lastest stabel release
+          version: '1'
+      - name: Install dependencies
+        run: julia --project=docs/ -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()'
+      - name: Build and deploy
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # For authentication with GitHub Actions token.
+        run: julia --project=docs/ docs/make.jl

README.md

@@ -1,36 +1,9 @@
 # Quiver.jl
 
-Quiver is an alternative data-structure to represent time series data. It is designed for time series that can have extra dimensions such as scenarios, blocks, segments, etc.
+| **Build Status** | **Coverage** | **Documentation** |
+|:-----------------:|:-----------------:|:-----------------:|
+| [![Build Status][build-img]][build-url] | [![Codecov branch][codecov-img]][codecov-url] |[![](https://img.shields.io/badge/docs-latest-blue.svg)](https://psrenergy.github.io/Quiver.jl/dev/)
 
-Quiver is not the fastest data-structure for time series data, but it is designed to be flexible and easy to use. The main idea behind Quiver
-is to have a set of dimensions that can be used to index the data and a set of values from the time serires attributes. This allows to have a
-table-like data-structure that can be used to store time series data. 
+Repository to read and write open-source formats for PSR models.
 
-Files that follow the Quiver implementation can be stored in any format that maps directly to a table-like structure with metadata. The metadata stores the frequency of the time series, the initial date, the unit of the data, the number of the dimension, the maximum value of each dimension, the time dimension and the version of the file.
-
-The matadata is always stored in a TOML file in the following format:
-
-```toml
-version = 1
-dimensions = ["stage", "scenario", "block"]
-dimension_size = [10, 12, 744]
-initial_date = "2006-01-01 00:00:00"
-time_dimension = "stage"
-frequency = "month"
-unit = ""
-labels = ["agent_1", "agent_2", "agent_3"]
-```
-
-And the data is stored in a csv or binary file that contains the values of the time series. The csv format is as follows:
-```csv
-stage,scenario,block,agent_1,agent_2,agent_3
-1,1,1,1.0,1.0,1.0
-1,1,2,1.0,1.0,1.0
-1,1,3,1.0,1.0,1.0
-```
-
-## Installation
-
-```julia
-pkg> add Quiver
-```
+For reading and writing Graf files in the csv format please add https://github.com/psrenergy/GrafCSV.jl to your project. 

docs/Project.toml

@@ -0,0 +1,2 @@
+[deps]
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"

docs/docs.bat

@@ -0,0 +1,5 @@
+@echo off
+
+SET DOCSPATH=%~dp0
+
+CALL "%JULIA_1100%" --project=%DOCSPATH% %DOCSPATH%\make.jl

docs/make.jl

@@ -0,0 +1,40 @@
+import Pkg
+Pkg.activate(dirname(@__DIR__))
+Pkg.instantiate()
+using Quiver
+
+Pkg.activate(@__DIR__)
+Pkg.instantiate()
+using Documenter
+
+makedocs(;
+    modules = [Quiver],
+    doctest = false,
+    clean = true,
+    format = Documenter.HTML(;
+        mathengine = Documenter.MathJax2(),
+        prettyurls = false,
+        # Prevents the edit on github button from showing up
+        edit_link = nothing,
+        footer = nothing,
+        disable_git = true,
+        repolink = nothing,
+    ),
+    sitename = "Quiver.jl",
+    warnonly = true,
+    pages = [
+        "Home" => [
+            "Overview" => "home.md",
+        ],
+        "Manual" => [
+            "Reading Data" => "reading.md",
+            "Writing Data" => "writing.md",
+            "Examples" => "examples.md",
+        ],
+    ],
+)
+
+Documenter.deploydocs(;
+    repo = "https://github.com/psrenergy/Quiver.jl.git",  
+    push_preview = true,  
+)

docs/src/examples.md

@@ -0,0 +1,97 @@
+## Examples
+
+Here are some practical examples demonstrating how to use Quiver for time series data operations, such as writing, reading, merging, and converting between formats.
+
+### 1. Writing and Reading Time Series
+
+This example shows how to write and read time series data with Quiver, using multiple dimensions like stage, scenario, and block.
+
+```julia
+using Quiver
+using Dates
+
+# Define the dimensions and metadata
+filename = "path/to/output/file"
+initial_date = DateTime(2006, 1, 1)
+num_stages = 10
+num_scenarios = 12
+num_blocks_per_stage = Int32.(Dates.daysinmonth.(initial_date:Dates.Month(1):initial_date + Dates.Month(num_stages - 1)) .* 24)
+dimensions = ["stage", "scenario", "block"]
+labels = ["agent_1", "agent_2", "agent_3"]
+time_dimension = "stage"
+dimension_size = [num_stages, num_scenarios, maximum(num_blocks_per_stage)]
+
+# Initialize the Writer
+writer = Quiver.Writer{Quiver.binary}(
+    filename;
+    dimensions,
+    labels,
+    time_dimension,
+    dimension_size,
+    initial_date = initial_date
+)
+
+# Write data
+for stage in 1:num_stages
+    for scenario in 1:num_scenarios
+        for block in 1:num_blocks_per_stage[stage]
+            data = [stage, scenario, block]
+            Quiver.write!(writer, data, stage=stage, scenario=scenario, block=block)
+        end
+    end
+end
+
+# Close the writer
+Quiver.close!(writer)
+
+# Now, read the data back
+reader = Quiver.Reader{Quiver.binary}(filename)
+
+for stage in 1:num_stages
+    for scenario in 1:num_scenarios
+        for block in 1:num_blocks_per_stage[stage]
+            data = Quiver.goto!(reader, stage=stage, scenario=scenario, block=block)
+            println(data)
+        end
+    end
+end
+
+Quiver.close!(reader)
+```
+
+### 2. Converting Between Formats
+
+This example demonstrates how to convert time series data from binary format to CSV. To convert the data in the opposite direction (from CSV to binary), simply switch the positions of `Quiver.binary` and `Quiver.csv` in the function below.
+
+```julia
+using Quiver
+
+# Convert binary file to CSV
+filename = "path/to/file"
+Quiver.convert(filename, Quiver.binary, Quiver.csv)
+```
+
+### 3. Merging Multiple Files
+
+This example shows how to merge multiple time series files into a binary single file.
+
+```julia
+using Quiver
+using Dates
+
+# Define metadata and filenames
+filename = "path/to/output/file"
+filenames = ["path/to/input_file_1", "path/to/input_file_2", "path/to/input_file_3"]
+initial_date = DateTime(2006, 1, 1)
+num_stages = 10
+num_scenarios = 12
+num_blocks = 24
+dimensions = ["stage", "scenario", "block"]
+time_dimension = "stage"
+dimension_size = [num_stages, num_scenarios, num_blocks]
+
+# Merge the files
+Quiver.merge(filename, filenames, Quiver.binary)
+```
+
+---

docs/src/home.md

@@ -0,0 +1,36 @@
+# Quiver.jl
+
+Quiver is an alternative data-structure to represent time series data. It is designed for time series that can have extra dimensions such as scenarios, blocks, segments, etc.
+
+Quiver is not the fastest data-structure for time series data, but it is designed to be flexible and easy to use. The main idea behind Quiver
+is to have a set of dimensions that can be used to index the data and a set of values from the time serires attributes. This allows to have a
+table-like data-structure that can be used to store time series data. 
+
+Files that follow the Quiver implementation can be stored in any format that maps directly to a table-like structure with metadata. The metadata stores the frequency of the time series, the initial date, the unit of the data, the number of the dimension, the maximum value of each dimension, the time dimension and the version of the file.
+
+The metadata is always stored in a TOML file in the following format:
+
+```toml
+version = 1
+dimensions = ["stage", "scenario", "block"]
+dimension_size = [10, 12, 744]
+initial_date = "2006-01-01 00:00:00"
+time_dimension = "stage"
+frequency = "month"
+unit = ""
+labels = ["agent_1", "agent_2", "agent_3"]
+```
+
+And the data is stored in a csv or binary file that contains the values of the time series. The csv format is as follows:
+```csv
+stage,scenario,block,agent_1,agent_2,agent_3
+1,1,1,1.0,1.0,1.0
+1,1,2,1.0,1.0,1.0
+1,1,3,1.0,1.0,1.0
+```
+
+## Installation
+
+```julia
+pkg> add Quiver
+```

docs/src/reading.md

@@ -0,0 +1,45 @@
+## Reading
+
+To read time series with Quiver, the Reader structure is used to manage the file, data, and dimensions. This structure helps load the relevant data from time series files, which can be either in CSV or binary format. Below is a more detailed example of how to use the `Reader`:
+
+#### Example of initializing a Reader:
+
+```julia
+using Quiver
+
+# Path to the time series file
+filename = "path/to/your/timeseries_file"
+
+# Initialize the Reader (assuming binary format for simplicity)
+reader = Reader{Quiver.binary}(filename)
+
+# Fetch data from the reader by specifying the stage, scenario, and block
+data = goto!(reader, stage=1, scenario=2, block=5)
+
+# Display the retrieved data
+println(data)
+```
+### Key Functions:
+```@docs
+Quiver.goto!
+```
+
+```@docs
+Quiver.next_dimension!
+```
+
+```@docs
+Quiver.file_to_array
+```
+
+```@docs
+Quiver.file_to_df
+```
+
+#### Closing the Reader:
+
+Always close the reader when done to release resources.
+
+```@docs
+Quiver.close!
+```

docs/src/writing.md

@@ -0,0 +1,8 @@
+```@docs
+Quiver.Writer
+```
+
+### Key Functions:
+```@docs
+Quiver.array_to_file
+```