Tutorial to QuotationFinder_0.4.3

Transcription

1 Tutorial to QuotationFinder_0.4.3 What is Quotation Finder and for which purposes can it be used? Quotation Finder is a tool for the automatic comparison of fully digitized texts. It can either detect quotations, allusions, plagiarism or other links between two textual corpuses. The program is individually adjustable in terms of language, encodings or the segmentation of the compared texts and can be useful in many contexts. For example: You might want to analyze the degree to which terms and phrases coined by a certain author influenced later publications in a field of study. Quotation Finder enables you to compare such a master-narrative to a huge corpus of other texts and analyze the use of equivalent phrases and terms. Quotation Finder also contains functional devices for the systematic and graphical display of the results thus obtained, like hit lists or different forms of charts, to facilitate more extended analysis. The Text Collection Analyzer Besides the above mentioned software, Quotation Finder contains a tool for the statistical evaluation of similarities between all text pairs in a collection, Text Collection Analyzer. Up to 24 measures capturing different levels and types of similarity can be calculated. The statistical data thereby generated complements the qualitative analysis of the Quotation Finder and is especially useful for the detection of plagiarism on a greater scale. Table of Contents Getting started 1 QuotationFinder 2 The user interface 2 Opening texts for comparison 2 The library 2 Metadata 3 Settings used for comparison 3 Running the comparison 4 Viewing the results 4 Results as a chart 5 Saving the results 6 Text Collection Analyzer 6 Opening the texts 6 Selecting the features 6 Viewing the results 7 Saving the results 8 Troubleshooting 8 Getting Started First steps: Download QuotationFinder_0.4.3 and unpack the archive. Windows: Start the program by double-clicking on "QuotationFinder_0.4.3.bat". Linux: Make "QuotationFinder_0.4.3.bat" executable and start it from command line (type "sh QuotationFinder_0.4.3.bat"). MacOS: Open the terminal, go to the QuotationFinder_0.4.3 folder and type "./QuotationFinder_0.4.3.bat". Possible operating systems: Microsoft Windows Linux MacOS (required version: 10.5 on 64-bit Intel-based Mac) other operating systems able to use the Java Virtual Machine (1.6+) System requirements: Java 1.6+: Java SE or JDK (available from Sun) 512 MB RAM After starting the software, choose what you would like to do first: Find Quotations, Compare Text Pairs or Add Collection to Library. You can always switch between the parts of the program by clicking on the Go tab (see image 1 and 9). 1

2 Quotation Finder 1. The user interface The Quotation Finder user interface consists of two panels: The left panel (Your Text) displays a single text file and the right panel (Library) displays the text collections that the single text can be compared to (see image 1). Image 1: Quotation Finder GUI 2. Opening text for comparison Click File and Open (see image 2) to browse your computer for the desired text. The following types of files are supported: Hypertext Markup Language (.html/.htm) Microsoft Word documents (.doc) Portable Document Format (.pdf) Plain Text (.txt) Rich Text Format (.rtf) The chosen text will be displayed in the left panel (Your Text). Then a small window will pop up asking you to select the language of the text (see also Settings used for comparison). Image 2: File menu The Library: To compare Your Text to a collection of texts, these texts have to be added as a collection to the library. To do this, click on Library and Add Collection (see image 3). A file chooser dialog allows you to select one file or directory, or several files or directories to be added as a collection to your library. Again, only the following file formats are accepted: txt, rtf, html, pdf, doc. Currently, the encoding of Plain Text documents cannot be extracted automatically. The program will ask you to select the correct encoding from a drop-down list. After adding a new collection, it will be displayed in the right panel. The data needed for the actual comparison (the index) is automatically generated and saved to the subfolder All collections of the folder containing Quotation Finder. The Library can hold as many collections as you need, but you can only compare Your Text to one collection at a time. By clicking on Add Files to Collection you can always enlarge a collection. To delete a collection, select the collection in the Library panel and click 2

3 Delete Collection. Note that when you restart the software, it will automatically display all previously added collections that have not yet been removed. Image 3: Library menu Changing or adding metadata: The name of each collection is generated automatically. You may change this name later by first selecting it from the list, then clicking on Library -> Rename Collection (see image 3). Some files contain metadata like author, title or date. This metadata is also automatically saved with the collection. You may view and change it by clicking on Library -> Edit Metadata (see image 3). All automatically generated or manually entered metadata like Collection, Title, Author etc. (see image 4) is displayed in a new screen. This metadata is important for two reasons: First, it is used in the display of comparison results (see image 7). Second, it is used for generating statistical output. Image 4: Changing or adding metadata 3. Settings used for comparison The success and results of your comparison depend on correctly specifying the settings. Therefore, before starting a comparison, click Settings and choose between the following options (see image 5) according to your requirements: Image 5: Settings menu Language: If you chose the wrong language when opening Your Text, you can change your selection again. Currently, the following languages are supported: English, Chinese, French, German, Japanese, Latin. Other languages may be added on demand. Just contact us. Currently, the language setting is only important for deciding whether a given token is smaller than the Minimum Length of Token (see below). For western languages, a token's word count is taken into consideration, for Chinese and Japanese the number of characters in a token are counted. If Your Text contains, for example, both English and Chinese sentences, you should choose Chinese as Language. Thus, both Chinese and English tokens will be searched, although for the English tokens the Minimum Length of Token restriction will not work properly. 3

4 Encoding: Choosing the correct encoding of a file is only important for Plain Text documents. By default, UTF-8 will be chosen. If Your Text is not displayed correctly, you may switch to another encoding. Currently the following encodings are supported: Chinese simplified (GB2312), Chinese traditional (Big5), English (US-ASCII), Japanese (Shift_JIS), UTF-8, Unicode (UTF-16 LE), Unicode (UTF-16 BE), Western (ISO ), Western (ISO ). Other encodings may be added on demand. Just contact us. Advanced: When you click on this menu item, a new window opens (see image 6). Use the available settings to adjust your comparison taking into consideration the characteristics of your texts: Tokenizer: Your text will not be searched in its entirety but as a series of phrases, also called tokens, the length of which you can adjust using the Tokenizer. Clause: The text is segmented after every.?!;:?!;:enter. Subclause: The text is segmented after every.?!;:,?!;:, Enter. (Note that a new token will only be generated after a comma (,) in subclause mode). n-gram: Here you can choose a number between 3 and 20 which indicates the length of the token. If you choose 3, for example, your text will be segmented into trigrams, meaning that every possible combination of three succeeding words or characters will be compared to the collection. In a document containing the text Today is Sunday not Monday, the tokens will be: Today is Sunday, is Sunday not, Sunday not Monday. This works for Chinese texts as well, but for them characters instead of words are considered. You can see the result of the tokenization in the left panel by clicking on the tab Segmented. (Note that the following two layers of settings are only available in the clause and subclause mode since the value of the ngrams already represents the length of the tokens.) Minimum Length of Token: Every token that is shorter than this number will be excluded from the comparison. Proximity: A scale from 1 to 10 allows you to determine the grade of fuzziness involved. The selected numeral represents the number of words or characters which may occur within a search phrase so that the phrase is still considered a match. Consequently, selecting a higher value on the proximity scale will increase the fuzziness of matching, while selecting "0" will only consider word-by-word matches. Image 6: Advanced options 4. Running the comparison After choosing Your Text and adjusting the settings accordingly, select a collection from the Library. Then click the Compare button at the bottom of the interface and the two sets of texts will be compared. When the comparison is finished, a small window will pop up displaying the results (see image 7). 5. Viewing the results The results of a comparison are displayed in several windows: the Result report, the Analyzed tab, the Hit List tab and the Hit(s) tab. The Result report contains five different types of information under the following headings: Number of Tokens: The complete number of tokens generated by the tokenizer from Your Text and used during comparison. Multiple hits: Tokens with at least two matches in the chosen collection. One hit: Tokens with exactly one match in the collection. No hit: Tokens with no match in the collection. 4

5 Not searched for: These are tokens that are shorter than the minimum length of token as selected in the advanced settings. In the Analyzed tab (see image 7) Your Text is segmented into tokens (one token per line) and those tokens that were also found in the collection are highlighted in blue. When clicking on such a token, the Hit List scrolls to the occurrences of the token in the collection. This list displays all hits per token. Underneath each token a link indicates the source text of the match (this link might also contain the name of the author, title etc., depending on how much metadata you added before). Clicking on a link will open up the corresponding text in the Hit(s) tab where you can see the token (highlighted in green) in context. Image 7: Viewing the results 6. Results as a chart To see the results of the comparison as a chart, click View at the upper part of the interface and scroll down to Chart View (note that the functions Table View and Text View can only be selected while using the Text Collection Analyzer). Chart: The chart displays the results of the comparison and can be manually labeled at the right side of the screen (see image 8). You can choose between certain Modes of Display (Hits per Author, per Date, per Path, per Source etc.), depending on how many texts with varying information were part of your collection, but you have to make sure that you have already added the relevant metadata (see The Library). You can also change the type of chart from Bar Chart (see image 8) to Line Chart or Pie Chart. Legend: The analyzed text is displayed at the lower part of the interface. As part of the Advanced Options to the right, you can switch between the display of all tokens or only tokens for which a hit was retrieved. Changed settings are only displayed after clicking Refresh at the lower right part of the interface. To return to Your Text or the Hit List, click View and scroll to File View or click Close at the lower right corner of the interface (see image 8). Image 8: Chart View 5

6 7. Saving the results After completing your comparison, you can save the results in different formats: To save the Chart graphically depicting the results (see Analyzing the Results), click Save As (see image 8), pick a certain quality of display and choose between two formats of picture compression (.jpg/jpeg or.png). The data represented in the chart can be exported as two tab delimited text files saved as a zip archive (see image 8). The tab delimited values can easily be copied into a Microsoft Excel sheet and further processed. By clicking on File and Save Results, the files displayed in the Analyzed and Hit List tabs are saved as html files. The entire comparison project can be saved by clicking on Save Project. Text Collection Analyzer Text Collection Analyzer calculates up to 24 different similarity scores for each text pair in a collection of texts. It can be used to detect plagiarism, but it is also useful for comparing different versions of a text. 1. Opening the texts Click File and Open to open the texts you want to analyze. The following types of files are supported: Hypertext Markup Language (.html/.htm) Microsoft Word documents (.doc) Portable Document Format (.pdf) Plain Text (.txt) Rich Text Format (.rtf) Choose the correct language and, if you are asked for it, the correct encoding. You only need to specify the encoding for Plain Text and Rich Text documents; for all other files types the encoding is detected automatically. The filepaths of the chosen texts will then be displayed in the left panel. You can always change the encoding of one or more documents by selecting them and setting the new encoding in the Settings - Encoding menu. If you want to remove one or more documents, select them and click on File and Remove. Image 9: Text Collection Analyzer 2. Selecting the features Text Collection Analyzer can calculate up to 24 different scores, ranging between 0% (no similarity at all) and 100% (highest possible similarity). These scores are divided into the following categories: Word: Every word or character will be considered. Trigram: Every possible combination of three succeeding words or characters will be considered. The trigrams of a document containing the text Today is Sunday not Monday, for example, are: Today is Sunday, is Sunday not, Sunday not Monday. Subclause: Every subclause (ending with.?!;:,?!;:,or Enter) will be considered. Clause: Every clause (ending with.?!;:?!;:or Enter) will be considered. 6

7 For each of these categories, five different scores can be calculated: Similarity: Calculates to what degree the two documents contain the same tokens. This score is similar to resemblance, but produces higher values. Similarity is calculated as two times the number of intersecting tokens (i.e. tokens that occur in both documents) divided by the number of all tokens in both documents. Several occurrences of the same token are counted separately. Multiplying by 2 is necessary to get the result 1 when comparing two identical documents. Example: Document1 = "Today is Sunday", Document2 = "Today is Sunday Today is Sunday". Then the similarity between the documents is 2 * 3 / 9 *100 = 67. Resemblance: Calculates to what degree the two documents contain the same tokens. This score is similar to similarity, but produces lower values. Resemblance is calculated as the number of intersecting tokens divided by the number of all tokens. Several occurrences of the same token are labeled with their occurrence numbers. Example: Document1 = "Today is Sunday", Document2 = "Today is Sunday Today is Sunday". First we label all tokens with their occurrence numbers: Document1 = "Today1 is1 Sunday1", Document2 = "Today1 is1 Sunday1 Today2 is2 Sunday2". Then the resemblance between the documents is 3 / 6 * 100 = 50. Index Resemblance: Calculates to what degree the two documents contain the same tokens. The difference to resemblance is that several occurrences of the same token are not considered (i.e. it does not matter if a token occurs seventy-four times or only once). The score is calculated as the number of intersecting tokens divided by the number of all tokens. Example: Document1 = "Today is Sunday", Document2 = "Today is Sunday Today is Sunday". Then the index resemblance between the documents is 3 / 3 *100 = 100. Containment: Calculates to what degree the smaller document is contained in the bigger document. The score is calculated as the number of intersecting tokens divided by the number of tokens in the smaller document. Several occurrences of the same token are labeled with their occurrence numbers. Example: Document1 = "Today is Sunday Sunday", Document2 = "Today is Monday or Tuesday". First we label all tokens with their occurrence numbers: Document1 = "Today1 is1 Sunday1 Sunday2", Document2 = "Today1 is1 Monday1 or1 Tuesday1". Then the containment between the documents is 2 / 4 *100 = 50. Index Containment: Calculates to what degree the smaller document is contained in the bigger document. The difference to containment is that several occurrences of the same token are not considered (i.e. it does not matter if a token occurs seventy-four times or only once). The score is calculated as the number of intersecting tokens divided by the number of tokens in the smaller document. Example: Document1 = "Today is Sunday Sunday", Document2 = "Today is Monday or Tuesday". Then the index containment between the documents is 2 / 3 *100 = 67. Additionally, the Text Collection Analyzer includes features for the evaluation of formal similarities: Number of Words/Sentences/Paragraphs: Calculates how similar the two documents are concerning their size. For both documents the number of words, sentences or paragraphs is counted. Then the smaller number is divided by the bigger number. Example: Document1 = "It is snowing", Document2 = "I would love to go for a walk". Then the number of words/sentences/paragraphs ratio between the documents is 3 / 8 *100 = 375. Vocabulary Size: Calculates how similar the two documents are concerning the size of the vocabulary used. For both documents the number of different words is calculated. Then the smaller number is divided by the bigger number. Example: Document1 = "It is snowing", Document2 = "Jingle Bells Jingle Bells". Then the vocabulary size ratio between the documents is 2 / 3 *100 = 67. Note that you can always click on the help button right next to every feature for further explanations and examples. 3. Viewing the results After you have selected the features, click on Calculate and the results will be displayed in the form of a table. Similarity scores range between 0% and 100%. The higher the score, the more similar the two documents are. You can get an explanation for each feature by selecting the respective column and choosing Feature Explanation from the Help Menu. By either double-clicking on a table cell or choosing View -> Text View (see image 10), you can see the details for all document pairs and features. The intersecting tokens are highlighted in grey in the documents and are also displayed in the Hits / Details list on the right. When you select a token from the list, it is highlighted in blue in the documents and you can jump from one occurrence to the next by pressing Return. Again you can see the feature explanations by selecting the respective feature in the results list and choosing Feature Explanation from the Help Menu. Note that only the occurrences that are taken into account for the calculation are highlighted. For index resemblance and index containment all occurrences are taken into account, but for similarity, resemblance and containment that is not the case. So you might see passages where a token is highlighted in one document, but not in the other because the highlighted token has already been matched to an earlier occurrence of the token in the other document. If you want to return to the Table view, click on View -> Table View. 7

8 Image 10: Text View 4. Saving the results By clicking on File and Save Results, the result table is saved as a tab delimited text file. The contents of this file can easily be copied into a Microsoft Excel sheet and further processed. The entire comparison project can be saved by clicking on Save Project. Troubleshooting Creating the library directory failed QuotationFinder creates a directory in its working directory named "Library". All the user's collections are stored there. Creating this directory may fail if QuotationFinder does not have write permission in its working directory. Please adjust the permissions accordingly and restart QuotationFinder. If creating the directory still fails, create it manually and restart the program. A window is smaller than its contents Screens with small resolution sometimes have problems showing the whole content of QuotationFinder windows. Sometimes this problem can be solved by enlarging the window. If this does not help, please send us a screen shot and we will try to fix the problem. An error occured when generating file view When you use Text Collection Analyzer to compare very large files, the program may run out of memory, and an error message will advise you to divide your files into smaller sections. Another way of solving this problem is to increase the memory (RAM) given to the program: Open QuotationFinder_0.4.3.bat in an editor and rename "-Xmx256m" to "-Xmx1024m" for example. Be careful not to exceed the RAM of your computer system. Save the file and restart the program. 8