Skip to content

Commit 23b02b3

Browse files
joeclark-phdjoeclark-phd
committed
update README and docs for release 1.1
1 parent 2739f1e commit 23b02b3

27 files changed

+131
-72
lines changed

‎README.md

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -62,6 +62,41 @@ MarkovTextGenerator ignores case, converting your input text and filters to lowe
6262

6363
A subclass of MarkovTextGenerator that learns and reproduces upper/lower case usage in the training data. With a given dataset, this model may learn less effectively from the training data because it builds separate models for "A" and "a" (to give an example) instead of combining observations. However, it may be preferable if the input data has interesting uses of capitalization (such as names that begin with "Mc" and "Mac" followed by capitals) that you want to re-generate. Any start/end filter(s) you configure will also be case-sensitive.
6464

65+
### ClusterChainGenerator
66+
67+
Quick start:
68+
69+
ClusterChainGenerator ccgen = new ClusterChainGenerator().train(myTextStream);
70+
System.out.println(ccgen.generateOne());
71+
72+
(or with all the optional configuration...)
73+
74+
ClusterChainGenerator ccgen = new ClusterChainGenerator().withMaxOrder(2).withStartFilter("J").withEndFilter("ia").withMinLength(3).withMaxLength(15).withRandom(myRandom).train(myTextStream).andAddPriors(0.01);
75+
System.out.println(ccgen.generateOne());
76+
77+
A class that uses a vowel/consonant clustering algorithm to generate new random text. Based loosely on [an algorithm described by Kusigrosz at RogueBasin](http://roguebasin.roguelikedevelopment.org/index.php?title=Cluster_chaining_name_generator), it scans input text for clusters of vowels and clusters of consonants, after converting it all to lowercase, keeping track of all clusters that have been observed to follow any given cluster. For example, "Elizabeth" would yield clusters `#-e-l-i-z-a-b-e-th-#` and "Anne" would yield `#-a-nn-e-#` where "`#`" is a control character marking the start or end of a string.
78+
79+
Much like MarkovTextGenerator, the implementation is based on a multi-order Markov chain (one difference is that priors aren't added by default and must be added explicitly after training). Internally we would keep track of the possible successors of each cluster, e.g.:
80+
81+
```
82+
# -> [e,a]
83+
e -> [l,th,#]
84+
a -> [b,nn]
85+
th -> [#]
86+
...etc...
87+
```
88+
89+
The `generateOne()` method takes a random walk through the cluster chain, only following paths that were found in the training data. To continue our example, a new string could begin with "e" or "a", with equal likelihood, an "e" could be followed by "l", by "th", or by the end of a string, and so on. With this training dataset of only two words, you could get a few different results, e.g.:
90+
91+
```
92+
elizanneth
93+
abelizanne
94+
anneth
95+
...etc...
96+
```
97+
98+
Each newly generated candidate string is compared to filters (minLength, maxLength, startsWith, endsWith) and returned if it passes. If the candidate string is filtered out, we generate another, until one passes. (Be aware that if you configure very difficult-to-match filters, generation time may increase greatly. If you set up impossible-to-match filters, e.g. requiring characters that aren't in the training data set's alphabet, you will get an infinite loop.
99+
65100
### RandomDrawGenerator
66101

67102
Quick start:
@@ -144,3 +179,27 @@ An alternative strategy is simply to train the generator on a single-sex dataset
144179
ingeltorg ingrta hromund orleif
145180

146181
Note that the **MarkovTextGenerator** automatically infers an alphabet from the training data, including Scandinavian characters that aren't on my keyboard.
182+
183+
### ClusterChainGenerator examples
184+
185+
The ClusterChainGenerator does what the MarkovTextGenerator does, but with clusters of consonants or vowels instead of individual characters. Using the same training dataset of Roman names, I generated these 25 random Roman names in 83ms:
186+
187+
festus minus frumerinus clodius aebuteo
188+
acitalina docilusius marcellus rectus placilius
189+
tertulus brictius viber nepius salvian
190+
burrus stertinus gordianus sevtonius protus
191+
allobrogicus didicus christianus quietus hosidonax
192+
193+
## Release notes
194+
195+
**Release 1.1**
196+
197+
- added `ClusterChainGenerator`
198+
199+
**Release 1.0.1**
200+
201+
- `MarkovNameGenerator.train()` no longer clears the alphabet and model before running. Therefore, you can now train a model on multiple input streams.
202+
203+
**Release 1.0**
204+
205+
- initial launch including `MarkovTextGenerator`, `RandomDrawGenerator`, and `DoubleTextGenerator`

‎docs/allclasses-frame.html

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,9 @@
22
<!-- NewPage -->
33
<html lang="en">
44
<head>
5-
<!-- Generated by javadoc (1.8.0_211) on Wed Aug 28 14:04:28 EDT 2019 -->
5+
<!-- Generated by javadoc (1.8.0_211) on Wed Aug 28 14:32:29 EDT 2019 -->
66
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
7-
<title>All Classes (Random Text Generators by joeclark.net 1.1-SNAPSHOT API)</title>
7+
<title>All Classes (Random Text Generators by joeclark.net 1.1 API)</title>
88
<meta name="date" content="2019-08-28">
99
<link rel="stylesheet" type="text/css" href="stylesheet.css" title="Style">
1010
<script type="text/javascript" src="script.js"></script>

‎docs/allclasses-noframe.html

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,9 @@
22
<!-- NewPage -->
33
<html lang="en">
44
<head>
5-
<!-- Generated by javadoc (1.8.0_211) on Wed Aug 28 14:04:28 EDT 2019 -->
5+
<!-- Generated by javadoc (1.8.0_211) on Wed Aug 28 14:32:29 EDT 2019 -->
66
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
7-
<title>All Classes (Random Text Generators by joeclark.net 1.1-SNAPSHOT API)</title>
7+
<title>All Classes (Random Text Generators by joeclark.net 1.1 API)</title>
88
<meta name="date" content="2019-08-28">
99
<link rel="stylesheet" type="text/css" href="stylesheet.css" title="Style">
1010
<script type="text/javascript" src="script.js"></script>

‎docs/constant-values.html

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,9 @@
22
<!-- NewPage -->
33
<html lang="en">
44
<head>
5-
<!-- Generated by javadoc (1.8.0_211) on Wed Aug 28 14:04:27 EDT 2019 -->
5+
<!-- Generated by javadoc (1.8.0_211) on Wed Aug 28 14:32:29 EDT 2019 -->
66
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
7-
<title>Constant Field Values (Random Text Generators by joeclark.net 1.1-SNAPSHOT API)</title>
7+
<title>Constant Field Values (Random Text Generators by joeclark.net 1.1 API)</title>
88
<meta name="date" content="2019-08-28">
99
<link rel="stylesheet" type="text/css" href="stylesheet.css" title="Style">
1010
<script type="text/javascript" src="script.js"></script>
@@ -13,7 +13,7 @@
1313
<script type="text/javascript"><!--
1414
try {
1515
if (location.href.indexOf('is-external=true') == -1) {
16-
parent.document.title="Constant Field Values (Random Text Generators by joeclark.net 1.1-SNAPSHOT API)";
16+
parent.document.title="Constant Field Values (Random Text Generators by joeclark.net 1.1 API)";
1717
}
1818
}
1919
catch(err) {

‎docs/deprecated-list.html

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,9 @@
22
<!-- NewPage -->
33
<html lang="en">
44
<head>
5-
<!-- Generated by javadoc (1.8.0_211) on Wed Aug 28 14:04:28 EDT 2019 -->
5+
<!-- Generated by javadoc (1.8.0_211) on Wed Aug 28 14:32:29 EDT 2019 -->
66
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
7-
<title>Deprecated List (Random Text Generators by joeclark.net 1.1-SNAPSHOT API)</title>
7+
<title>Deprecated List (Random Text Generators by joeclark.net 1.1 API)</title>
88
<meta name="date" content="2019-08-28">
99
<link rel="stylesheet" type="text/css" href="stylesheet.css" title="Style">
1010
<script type="text/javascript" src="script.js"></script>
@@ -13,7 +13,7 @@
1313
<script type="text/javascript"><!--
1414
try {
1515
if (location.href.indexOf('is-external=true') == -1) {
16-
parent.document.title="Deprecated List (Random Text Generators by joeclark.net 1.1-SNAPSHOT API)";
16+
parent.document.title="Deprecated List (Random Text Generators by joeclark.net 1.1 API)";
1717
}
1818
}
1919
catch(err) {

‎docs/help-doc.html

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,9 @@
22
<!-- NewPage -->
33
<html lang="en">
44
<head>
5-
<!-- Generated by javadoc (1.8.0_211) on Wed Aug 28 14:04:28 EDT 2019 -->
5+
<!-- Generated by javadoc (1.8.0_211) on Wed Aug 28 14:32:29 EDT 2019 -->
66
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
7-
<title>API Help (Random Text Generators by joeclark.net 1.1-SNAPSHOT API)</title>
7+
<title>API Help (Random Text Generators by joeclark.net 1.1 API)</title>
88
<meta name="date" content="2019-08-28">
99
<link rel="stylesheet" type="text/css" href="stylesheet.css" title="Style">
1010
<script type="text/javascript" src="script.js"></script>
@@ -13,7 +13,7 @@
1313
<script type="text/javascript"><!--
1414
try {
1515
if (location.href.indexOf('is-external=true') == -1) {
16-
parent.document.title="API Help (Random Text Generators by joeclark.net 1.1-SNAPSHOT API)";
16+
parent.document.title="API Help (Random Text Generators by joeclark.net 1.1 API)";
1717
}
1818
}
1919
catch(err) {

‎docs/index-all.html

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,9 @@
22
<!-- NewPage -->
33
<html lang="en">
44
<head>
5-
<!-- Generated by javadoc (1.8.0_211) on Wed Aug 28 14:04:28 EDT 2019 -->
5+
<!-- Generated by javadoc (1.8.0_211) on Wed Aug 28 14:32:29 EDT 2019 -->
66
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
7-
<title>Index (Random Text Generators by joeclark.net 1.1-SNAPSHOT API)</title>
7+
<title>Index (Random Text Generators by joeclark.net 1.1 API)</title>
88
<meta name="date" content="2019-08-28">
99
<link rel="stylesheet" type="text/css" href="stylesheet.css" title="Style">
1010
<script type="text/javascript" src="script.js"></script>
@@ -13,7 +13,7 @@
1313
<script type="text/javascript"><!--
1414
try {
1515
if (location.href.indexOf('is-external=true') == -1) {
16-
parent.document.title="Index (Random Text Generators by joeclark.net 1.1-SNAPSHOT API)";
16+
parent.document.title="Index (Random Text Generators by joeclark.net 1.1 API)";
1717
}
1818
}
1919
catch(err) {

‎docs/index.html

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,9 @@
22
<!-- NewPage -->
33
<html lang="en">
44
<head>
5-
<!-- Generated by javadoc (1.8.0_211) on Wed Aug 28 14:04:28 EDT 2019 -->
5+
<!-- Generated by javadoc (1.8.0_211) on Wed Aug 28 14:32:29 EDT 2019 -->
66
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
7-
<title>Random Text Generators by joeclark.net 1.1-SNAPSHOT API</title>
7+
<title>Random Text Generators by joeclark.net 1.1 API</title>
88
<script type="text/javascript">
99
tmpTargetPage = "" + window.location.search;
1010
if (tmpTargetPage != "" && tmpTargetPage != "undefined")

‎docs/net/joeclark/proceduralgeneration/ClusterChainGenerator.html

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,9 @@
22
<!-- NewPage -->
33
<html lang="en">
44
<head>
5-
<!-- Generated by javadoc (1.8.0_211) on Wed Aug 28 14:04:27 EDT 2019 -->
5+
<!-- Generated by javadoc (1.8.0_211) on Wed Aug 28 14:32:28 EDT 2019 -->
66
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
7-
<title>ClusterChainGenerator (Random Text Generators by joeclark.net 1.1-SNAPSHOT API)</title>
7+
<title>ClusterChainGenerator (Random Text Generators by joeclark.net 1.1 API)</title>
88
<meta name="date" content="2019-08-28">
99
<link rel="stylesheet" type="text/css" href="../../../stylesheet.css" title="Style">
1010
<script type="text/javascript" src="../../../script.js"></script>
@@ -13,7 +13,7 @@
1313
<script type="text/javascript"><!--
1414
try {
1515
if (location.href.indexOf('is-external=true') == -1) {
16-
parent.document.title="ClusterChainGenerator (Random Text Generators by joeclark.net 1.1-SNAPSHOT API)";
16+
parent.document.title="ClusterChainGenerator (Random Text Generators by joeclark.net 1.1 API)";
1717
}
1818
}
1919
catch(err) {

‎docs/net/joeclark/proceduralgeneration/DoubleTextGenerator.html

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,9 @@
22
<!-- NewPage -->
33
<html lang="en">
44
<head>
5-
<!-- Generated by javadoc (1.8.0_211) on Wed Aug 28 14:04:27 EDT 2019 -->
5+
<!-- Generated by javadoc (1.8.0_211) on Wed Aug 28 14:32:28 EDT 2019 -->
66
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
7-
<title>DoubleTextGenerator (Random Text Generators by joeclark.net 1.1-SNAPSHOT API)</title>
7+
<title>DoubleTextGenerator (Random Text Generators by joeclark.net 1.1 API)</title>
88
<meta name="date" content="2019-08-28">
99
<link rel="stylesheet" type="text/css" href="../../../stylesheet.css" title="Style">
1010
<script type="text/javascript" src="../../../script.js"></script>
@@ -13,7 +13,7 @@
1313
<script type="text/javascript"><!--
1414
try {
1515
if (location.href.indexOf('is-external=true') == -1) {
16-
parent.document.title="DoubleTextGenerator (Random Text Generators by joeclark.net 1.1-SNAPSHOT API)";
16+
parent.document.title="DoubleTextGenerator (Random Text Generators by joeclark.net 1.1 API)";
1717
}
1818
}
1919
catch(err) {

0 commit comments

Comments
 (0)