parsed_to_plot/lib.rs
1//!
2//!
3//! Plots constituency trees and dependency trees given by strings.
4//!
5//!
6//! # Input-Output
7//!
8//! * The API expects a string input. Multiple string inputs can be delivered in a file, through the command-line.
9//! * For constituency trees, the program takes a parsed string given in one line. The string can be syntactic, for example
10//! such that represents phrases and parts-of-speech (like the structure in [Berkeley Neural Parser](https://pypi.org/project/benepar/)
11//! in python). Such strings will have "double leaves" (see an example below). Alternatively, the strings can have singular leaves,
12//! representing, for example, mathematical expressions.
13//! * For dependency trees, the programs takes a conll format, in which every token has 10 fields, separated by tab, and
14//! presented in a new line. Sentences are separated by an empty line. (see an example below, using an output from
15//! [spaCy](https://spacy.io/) in python).
16//! * For multiple inputs of the same type, the program expects 3 arguments from the command line :
17//! * input type ("c" = constituency / "d" = dependency), String
18//! * input file path, String
19//! * output path, String
20//!
21//! See examples below.
22//!
23//! # Usage examples
24//! ## Constituency
25//!
26//! How to use the API in order to produce a png from a single parsed constituency string:
27//!
28//! ```rust
29//! // Example parsed sentence:
30//! // (S (NP (det The) (N people)) (VP (V watch) (NP (det the) (N game))))
31//!
32//! use parsed_to_plot::Config;
33//! use parsed_to_plot::String2Tree;
34//! use parsed_to_plot::Tree2Plot;
35//! use parsed_to_plot::String2StructureBuilder;
36//! use parsed_to_plot::Structure2PlotBuilder;
37//!
38//! let mut constituency = String::from("(S (NP (det The) (N people)) (VP (V watch) (NP (det the) (N game))))");
39//! let mut string2tree: String2Tree = String2StructureBuilder::new();
40//! string2tree.build(&mut constituency).unwrap(); // build the tree from the string
41//! let tree = string2tree.get_structure();
42//!
43//! // build plot from tree and save
44//! Config::make_out_dir(&"Output".to_string()).unwrap();
45//! let save_to: &str = "Output/constituency_plot.png";
46//! let mut tree2plot: Tree2Plot = Structure2PlotBuilder::new(tree);
47//! tree2plot.build(save_to).unwrap();
48//! ```
49//!
50//! ## Dependency
51//!
52//! How to use the API in order to produce a png from a single conll format:
53//!
54//! ```rust
55//! // Example conll:
56//! // 0 The the det _ _ 1 det _ _
57//! // 1 people people NOUN _ _ 2 nsubj _ _
58//! // 2 watch watch VERB _ _ 2 ROOT _ _
59//! // 3 the the DET _ _ 4 det _ _
60//! // 4 game game NOUN _ _ 2 dobj _ _
61//!
62//! use parsed_to_plot::Config;
63//! use parsed_to_plot::String2Conll;
64//! use parsed_to_plot::Conll2Plot;
65//! use parsed_to_plot::String2StructureBuilder;
66//! use parsed_to_plot::Structure2PlotBuilder;
67//!
68//! let mut dependency = [
69//! "0 The the DET _ _ 1 det _ _",
70//! "1 people people NOUN _ _ 2 nsubj _ _",
71//! "2 watch watch VERB _ _ 2 ROOT _ _",
72//! "3 the the DET _ _ 4 det _ _",
73//! "4 game game NOUN _ _ 2 dobj _ _"
74//! ].map(|x| x.to_string()).to_vec();
75//!
76//! let mut string2conll: String2Conll = String2StructureBuilder::new();
77//! string2conll.build(&mut dependency).unwrap(); // build the conll from the vector of strings
78//! let conll = string2conll.get_structure();
79//!
80//! // build plot from conll and save
81//! Config::make_out_dir(&"Output".to_string()).unwrap();
82//! let save_to: &str = "Output/dependency_plot.png";
83//! let mut conll2plot: Conll2Plot = Structure2PlotBuilder::new(conll);
84//! conll2plot.build(save_to).unwrap();
85//! ```
86//!
87//! ## Multiple inputs via file
88//!
89//! You can use a combination of the API and command-line to process multiple inputs of the same type through a file.
90//! The command-line format is as follows:
91//! ```text
92//! cargo run INPUT_TYPE INPUT_FILE OUTPUT_PATH
93//! ```
94//!
95//! when:
96//! * INPUT_TYPE should be replaced with "c" for constituency or "d" for dependency.
97//! * INPUT_FILE should be replaced with a path to a txt file with inputs.
98//! * OUTPUT_PATH should be replaced with a path to a requested output dir.
99//!
100//! For example, you can enter multiple constituencies by using the following command:
101//!
102//! ```text
103//! cargo run c constituencies.txt Output
104//! ```
105//!
106//! With the following usage:
107//!
108//! ```ignore
109//! use parsed_to_plot::Config;
110//! use parsed_to_plot::String2Tree;
111//! use parsed_to_plot::Tree2Plot;
112//! use parsed_to_plot::String2StructureBuilder;
113//! use parsed_to_plot::Structure2PlotBuilder;
114//! use std::env;
115//!
116//! // collect arguments from command line
117//! let args: Vec<String> = env::args().collect();
118//! // note: your command line args should translate to something similar to the following:
119//! // let args: Vec<String> = ["PROGRAM_NAME", "c", "Input/constituencies.txt", "ConOutput"].map(|x| x.to_string()).to_vec();
120//!
121//! // run configuration protocol and inspectations
122//! let sequences = match Config::new(&args) {
123//! Ok(sequences) => Vec::<String>::try_from(sequences).unwrap(),
124//! Err(config) => panic!("{}", config)
125//! };
126//!
127//! for (i, mut constituency) in sequences.into_iter().enumerate() {
128//!
129//! println!("working on input number {} ...", i);
130//! let save_to = &Config::get_out_file(&args[3], i.to_string().as_str());
131//!
132//! // build tree from consituency
133//! let mut string2tree: String2Tree = String2StructureBuilder::new();
134//! string2tree.build(&mut constituency).unwrap();
135//! let tree = string2tree.get_structure();
136//!
137//! // build plot from tree
138//! let mut tree2plot: Tree2Plot = Structure2PlotBuilder::new(tree);
139//! tree2plot.build(save_to).unwrap();
140//! }
141//! ```
142//!
143//! Those will save png images of constituency trees drawn for the inputs in constituencies.txt, in an Output dir.
144//! The dependency equivalent is similar.
145//!
146//! ## String reconstruction
147//!
148//! As of version 0.2.0 you can create a string from a built structure, tree or Vec-Token-. This can be useful, for example,
149//! to assert the built tree made from a string x, by making sure that x = Structure2String(String2Structure(x)).
150//! For example, on a dependency string (constituency equivalent is similar):
151//!
152//! ```rust
153//! // 0 The the det _ _ 1 det _ _
154//! // 1 people people NOUN _ _ 2 nsubj _ _
155//! // 2 watch watch VERB _ _ 2 ROOT _ _
156//! // 3 the the DET _ _ 4 det _ _
157//! // 4 game game NOUN _ _ 2 dobj _ _
158//!
159//! use parsed_to_plot::Config;
160//! use parsed_to_plot::String2Conll;
161//! use parsed_to_plot::Conll2String;
162//! use parsed_to_plot::String2StructureBuilder;
163//! use parsed_to_plot::Structure2PlotBuilder;
164//!
165//! let example = [
166//! "0 The the DET _ _ 1 det _ _",
167//! "1 people people NOUN _ _ 2 nsubj _ _",
168//! "2 watch watch VERB _ _ 2 ROOT _ _",
169//! "3 the the DET _ _ 4 det _ _",
170//! "4 game game NOUN _ _ 2 dobj _ _"
171//! ].map(|x| x.to_string()).to_vec();
172//! let mut dependency = example.clone();
173//!
174//! let mut string2conll: String2Conll = String2StructureBuilder::new();
175//! string2conll.build(&mut dependency).unwrap(); // build the conll from the vector of strings
176//! let conll = string2conll.get_structure();
177//!
178//! // from v0.2.0 - reconstruction of the original dependency from the built conll
179//! Config::make_out_dir(&"Output".to_string()).unwrap();
180//! let save_to: &str = "Output/dependency_reconstruction.txt";
181//! let mut conll2string: Conll2String = Structure2PlotBuilder::new(conll);
182//! conll2string.build(save_to).unwrap();
183//! let dependency_reproduction = conll2string.get_conll();
184//! assert_eq!(dependency_reproduction, example);
185//! ```
186//!
187//! # References
188//! * I used the crates: [id-tree](https://crates.io/crates/id_tree), [plotters](https://crates.io/crates/plotters).
189//! * I used [spaCy](https://spacy.io/) to create a couple of dependency-parsed examples for illustration.
190//!
191//! # License
192//! Under MIT license.
193//!
194//!
195
196mod config;
197mod string_2_tree;
198mod string_2_conll;
199mod tree_2_plot;
200mod conll_2_plot;
201mod tree_2_string;
202mod conll_2_string;
203mod sub_tree_children;
204mod generic_traits;
205mod generic_enums;
206
207pub use config::Config;
208pub use string_2_tree::String2Tree;
209pub use string_2_conll::String2Conll;
210pub use tree_2_plot::Tree2Plot;
211pub use conll_2_plot::Conll2Plot;
212pub use tree_2_string::Tree2String;
213pub use conll_2_string::Conll2String;
214pub use generic_traits::generic_traits::String2StructureBuilder;
215pub use generic_traits::generic_traits::Structure2PlotBuilder;