-
Notifications
You must be signed in to change notification settings - Fork 1
/
Copy pathREADME.Rmd
154 lines (96 loc) · 5.45 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
---
output: github_document
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/README-",
out.width = "100%"
)
```
# XploRer
<!-- badges: start -->
[](https://www.repostatus.org/#wip)
[](https://github.com/VEZY/XploRer/actions)
<!-- badges: end -->
The goal of XploRer is to read, write, analyze and plot MTG (Multi-scale Tree Graph) files. These files describe the plant topology (i.e. structure) along with some attributes for each node (e.g. geometry, colors, state...).
> The package is under intensive development and is in a very early version. The functions may heavily change from one version to another until a more stable version is released.
## Table of Contents
* [1. Installation](#1-installation)
* [2. Brief introduction](#2-brief-introduction)
* [2.1 Read a file](#21-read-a-file)
* [2.2 Mutate](#22-mutate)
* [2.3 Plot](#23-plot)
* [3. Help](#3-help)
* [4. Contribute](#4-contribute)
* [5. Code of Conduct](#5-code-of-conduct)
* [6. Roadmap](#6-roadmap)
## 1. Installation
You can install the release version of XploRer from [GitHub](https://github.com/) with:
``` r
# install.packages("devtools")
devtools::install_github("VEZY/XploRer")
```
## 2. Brief introduction
A more in-depth introduction is available in the introductory vignette from the [getting started tab](https://vezy.github.io/XploRer/articles/XploRer.html).
Specialized articles from the Articles tab describe the functionality in details.
### 2.1 Read a file
Read a simple MTG file:
```{r}
library(XploRer)
MTG = read_mtg("https://raw.githubusercontent.com/VEZY/XploRer/master/inst/extdata/simple_plant.mtg")
```
### 2.2 Mutate
Mutate the MTG to add/recompute node attributes:
```{r}
MTG%>%
mutate_mtg(section_surface = pi * ((node$Width / 2)^2), .symbol = "Internode")%>%
mutate_mtg(s_surf_child_sum = sum(children(node$section_surface),na.rm=TRUE),
.symbol = "Internode")
print(MTG, ".symbol", "Width","section_surface", "s_surf_child_sum")
```
### 2.3 Plot
#### 2.3.1 Static plot
The plant topology can be plotted using the `autoplot()` function. This function is implemented by `ggplot2` so you'll need to load this package before-hand:
```{r}
library(ggplot2)
autoplot(MTG)
```
#### 2.3.2 Interactive plot
The same plot can be rendered as an interactive plot using:
```{r eval=FALSE}
plotly_mtg(MTG)
```
## 3. Help
Please see the [OpenAlea documentation](http://openalea.gforge.inria.fr/doc/vplants/newmtg/doc/_build/html/contents.html) (especially chapter 8) for more details on the MTG files.
If you have any other problem related to the package, please feel free to [fill an issue](https://github.com/VEZY/XploRer/issues) on Github.
## 4. Contribute
Contributions are more than welcome! Whatever your programming level really. If you need help on your first contribution, fill an issue about it.
If you find any issue, want to make a suggestion, or need a new functionality, please [fill an issue](https://github.com/VEZY/XploRer/issues). This is not more complicated than writing an email (but really simpler for us), just follow the steps one by one. Look into [this article](https://guides.github.com/features/issues/) for more info.
If you want to contribute, please read our [contribution guidelines](https://vezy.github.io/XploRer/CONTRIBUTING.html) first. It's a few minutes read only and guides you through the whole process of contributing (along with many useful tools).
## 5. Code of Conduct
Please note that the XploRer project is released with a [Contributor Code of Conduct](https://vezy.github.io/XploRer/CODE_OF_CONDUCT.html). By contributing to this project, you agree to abide by its terms.
## 6. Roadmap
To do before v1:
- [x] Make mtg helpers (`parent()`, `children()` and `ancestors()`) use NSE format to homogenize with `mutate_mtg()`
- [x] Add a "Get started" vignette (add the basic info on what we can do with the package)
- [x] Update the readme to display only very basic information about the package, and about contributions (very welcome)
- [ ] Add a vignette about mutating the mtg
- [ ] Add a vignette about plotting the mtg (e.g. add attributes on hover)
- [ ] Check the mtg validity:
- [ ] add all checks on the mtg in `read_mtg()` using the sections
- [ ] Add a new argument to remove the checks
- [ ] Print the problems nicely using [cli](https://cli.r-lib.org/) and/or [waldo](https://waldo.r-lib.org/)
- [x] Return the mtg with class data.tree + mtg and remove the sections (not a list anymore). This will make the mtg more usable
- [ ] Read mtg from XLSX
- [x] Replace node name by .symbol name:
- [x] Use scale on actual scale, and add a new filter for symbol.
- [x] Put back the scene node
In a more distant future (v2):
- [ ] Add a vignette about the mtg format, and on the basics (navigate, get value...)
- [ ] Add 3d plotting when geometry attributes are available. Make it compatible with XPlo and OpenAlea.
- [ ] Add an opf (open plant format) parser -> opf to mtg
- [ ] Add an opf writer when the geometry is available (using reference meshes)