BrainTrain - User guide

By: Team BrainTrain Since: Jan 2019 Licence: MIT

1. Introduction
2. Quick start
3. Features
4. Future enhancements
5. Troubleshooting
6. FAQ
7. Command Summary

1. Introduction

BrainTrain is a spaced-repetition card application which makes memorizing easy and effective. With BrainTrain’s Spaced Repetition System (SRS) optimizing your card revision intervals, you will be able to learn more in less time.

Who is it for:

Anyone who needs to memorise anything (e.g. Japanese vocabulary, the periodic table, the human anatomy). BrainTrain’s card system is content-agnostic and flexible. It accommodates all forms of learning you may require.
Anyone who needs to create flashcards for educational purposes. BrainTrain’s cards are grouped as lessons which can be easily imported and exported. These lessons are also saved in .csv files which you can edit in your favourite spreadsheet application (e.g. Excel).

Main features of BrainTrain:

You can manage card lessons in BrainTrain’s management mode or alternatively do so in your preferred spreadsheet application.
You can attempt card lessons in BrainTrain’s quiz mode which will track and manage your user-specific spaced-repetition data automatically.

Read the next section, Section 2, “Quick start”, to start using BrainTrain.

2. Quick start

To begin using BrainTrain, follow the following set of instructions:

Ensure that Java version 9 or later is installed on your Computer. You can download it here.
Download the latest braintrain.jar file here. It is located under Assets.
Create a folder to store the downloaded file (e.g. braintrain/).
Move braintrain.jar into the created folder.
Double-click braintrain.jar to launch the BrainTrain app. You should see the following within a few seconds:

Figure 1. BrainTrain on first run
Read the next section, Section 3, “Features”, to find out what BrainTrain commands there are.

3. Features

Command Format

Words in UPPER_CASE are parameter values which you need to specify in order for the commands to work. For example, for deleteCard INDEX, INDEX is a parameter you have to specify.
Parameters in [ ] brackets are optional. For example, for the addCard t/TEST t/TEST [t/TEST]… [h/HINT]… command, you have to specify at least 2 TEST values, but you can optionally specify more than 2 TEST values. You can also specify 0 or more OPTIONAL values.
Parameters with trailing … can be specified more than once. For example, for the addLesson n/NAME t/TEST t/TEST [t/TEST]… [h/HINT]… command, you can specify 0 or more HINT values and 2 or more TEST values. On the other hand, you can only specify exactly 1 NAME value.
Parameters can be entered in any order. For example, for the addCard t/TEST t/TEST [t/TEST]… [h/HINT]… command, you can use the command as such: addCard t/Australia h/Starts with C t/Canberra t/English.

3.1. Management mode

3.1.1. Viewing help: `help`

Displays usage information on all commands.
Format: help

Alternatively, press F1 to display usage information on all commands.

3.1.2. Changing theme: `changeTheme`

Changes the theme from light to dark vice versa.
Format: changeTheme

3.1.3. Starting a quiz session: `start`

Starts a new quiz session.
Format: start LESSON_INDEX [c/COUNT] m/MODE

This command only works in lesson view. If you are currently editing a lesson in card view, you have to use the quit command to return to lesson view before you can use this command.

Usage rules:

You must specify the index of lesson to be started. If your input index is out of range of current Lesson List, an error will be thrown.
You can optionally specify the COUNT parameter. COUNT sets the number of cards to be tested in the quiz session.
- If no COUNT is specified, by default 1 card is tested.
- If COUNT is larger than the size of the current lesson, the COUNT will be reset to be the size of the lesson by default.
You must specify index and count as a valid number which should be less than the MAXIMUM_INTEGER(0*7ffffffff), otherwise an error will be thrown.
You must specify MODE. MODE sets the testing mode of the quiz session. The four available modes are LEARN, PREVIEW, REVIEW and DIFFICULT.
1. LEARN: Displays new cards with both question and answer before test begins, and then only question is shown to test you. If you have already learned all the cards in current lesson, an error of no more new card to learn will be thrown.
2. PREVIEW: Displays both question and answer of cards. You will not be tested.
3. REVIEW: Tests the words based on the spaced-repetition algorithm, which means that cards with the earliest test date are tested first. If no card has due date before current time, an error of no card for review will be thrown.
4. DIFFICULT: Displays cards you previously labelled as difficult with both question and answer shown. You will not be tested. If no card has been labelled as difficult, an error of no difficult card will be thrown.

Only in review mode, cards are tested based on the Space-Repetition system.

Examples:

start 1 m/LEARN
Starts a quiz in LEARN mode. Cards will be chosen from the first lesson in lesson list. Since count is not specified, the quiz will only contain one card by default.
start 2 c/20 m/PREVIEW
Starts a quiz containing 20 cards chosen from the second lesson in lesson list in PREVIEW mode, which only displays question and answer together one time.

After you start a quiz session with the start command, BrainTrain will switch to quiz mode and you will only be allowed to enter quiz mode commands.

3.1.4. Listing all lessons: `listLessons`

Displays a numbered list of all lessons.
Format: listLessons

This command only works in lesson view. If you are currently editing a lesson in card view, you have to use the quit command to return to lesson view before you can use this command.

Figure 2. Listing of lessons by listLessons command

3.1.5. Adding a lesson: `addLesson`

Adds a lesson which is used to store cards of the same type and topic.
Format: addLesson n/NAME t/TEST t/TEST [t/TEST]… [h/HINT]…

This command only works in lesson view. If you are currently editing a lesson in card view, you have to use the quit command to return to lesson view before you can use this command.

Usage rules:

You must specify at least 2 TEST values. Flashcards added to this lesson must have corresponding TEST values.
- For example, a lesson for memorising muscle anatomy will have three TEST values: 'Muscle', 'Action' and 'Innervation'.
- By default, the first 2 TEST values ('Muscle' and 'Action') will be tested when the lesson is started in quiz mode.
- You can set the 2 TEST values to be tested by using the set command.
You can specify 0 or more HINT values (e.g. 'Muscle Group').
- HINT values are displayed during quiz mode when you enter \hint.

Examples:

addLesson n/Capitals of the world t/Country t/Capital t/Language h/Hint
- Adds a lesson named 'Capitals of the world' with 3 TEST values and 1 HINT value.
addLesson n/Chinese vocabulary t/English t/Chinese
- Adds a lesson named 'Chinese vocabulary' with 2 TEST values.

3.1.6. Deleting a lesson: `deleteLesson`

Deletes the lesson at the specified INDEX of the numbered lesson list.
Format: deleteLesson INDEX

This command only works in lesson view. If you are currently editing a lesson in card view, you have to use the quit command to return to lesson view before you can use this command.

Example:

Figure 3. BrainTrain with sample lessons loaded

In the above scenario, the command deleteLesson 2 will delete the second lesson in the numbered list, 'Sample-Muscle-Anatomy'.

3.1.7. Reloading all lessons: `reload`

Reloads all lessons from the lessons folder. The default lessons folder is /lessons/, found next to braintrain.jar.

Format: reload

This command only works in lesson view. If you are currently editing a lesson in card view, you have to use the quit command to return to lesson view before you can use this command.

Steps:

You have a newly downloaded .csv lesson file, new_lesson.csv, with no lessons currently loaded.

Figure 4. A new lesson file.

Figure 5. No lessons are currently loaded.
You drag the new file into the /lessons/ folder.

Figure 6. Dragging the file.
You enter reload into the app, and the new lesson appears.

Figure 7. Reloading lessons.
You verify again with listLessons.

Figure 8. New lesson has been loaded.

Lessons are automatically reloaded when you open the application.

If the lesson does not appear, please check Section 5, “Troubleshooting”.

3.1.8. Editing a lesson in card view: `edit`

Opens the lesson at the specified INDEX in Card View for editing.
Format: openLesson INDEX

In Card View, users will be able to use the following commands: set, addCard, deleteCard and listCards.

Example:

Figure 9. BrainTrain with sample lessons loaded

In the above scenario, the command edit 1 will open the first lesson in the numbered list, 'Sample-Capitals' in Card View for editing.

3.1.9. Quitting card view: `quit`

Quits Card View and returns to Lesson View.
Format: quit

Changes made to the lesson in Card View are saved automatically upon quitting Card View.

3.1.10. Setting the lesson’s test pair: `set`

Sets the 2 TEST values at the 2 specified INDEX of the numbered card list to be tested in quiz mode.
Format: set INDEX INDEX

This command only works in card view. You have to open a lesson in card view for editing with the edit command before you can use this command.

Usage rules:

You must specify exactly 2 valid INDEX values.

Example:

Figure 10. A lesson opened in card view, before set 1 3 is entered

In the above scenario, the command set 1 3 will set the first TEST value 'Muscle' and the third TEST value 'Innervation' as the values to be tested. After the command is entered, the interface updates accordingly:

Figure 11. A lesson opened in card view, after set 1 3 is entered

3.1.11. Listing all cards: `listCards`

Displays a numbered list of all cards in the lesson opened in Card View.
Format: listCards

This command only works in card view. You have to open a lesson in card view for editing with the edit command before you can use this command.

Figure 12. Listing of cards by listCards command

3.1.12. Adding a card: `addCard`

Adds a card to the lesson opened in Card View.
Format: addCard t/TEST t/TEST [t/TEST]… [h/HINT]…

This command only works in card view. You have to open a lesson in card view for editing with the edit command before you can use this command.

Usage rules:

You must specify at least 2 TEST values. This is because a card needs at least 2 TEST values to be testable in quiz mode.
You can specify 0 or more HINT values.

You can only add cards to the opened lesson if they have the same number of TEST values as the opened lesson. See addLesson command for more information.

Examples:

addCard t/Australia t/Canberra t/English h/Starts with C
- Adds a card with 3 TEST values and 1 HINT value.
- By default, the lesson will be set to test the first 2 TEST values. In this case, 'Australia' and 'Canberra' are the 2 values to be tested by default.
addCard t/Cake t/蛋糕 h/🎂
- Adds a card with 2 TEST values which are both tested in quiz mode.

3.1.13. Deleting a card: `deleteCard`

Deletes the card at the specified INDEX of the numbered card list.
Format: deleteCard INDEX

This command only works in card view. You have to open a lesson in card view for editing with the edit command before you can use this command.

Example:

Figure 13. BrainTrain with sample cards loaded

In the above scenario, the command deleteCard 2 will delete the second card in the numbered list, 'Orbicularis oculi / Facial nerve'.

3.1.14. Listing entered commands : `history`

Lists all the commands you have entered in reversed chronological order.
Format: history

Pressing the ↑ and ↓ arrows will display the previous and next input respectively in the command box.

3.1.15. Exiting the program : `exit`

Exits the program.
Format: exit

3.2. Quiz mode

When you start a quiz, you will enter quiz mode. In this mode, you will only be allowed to enter the following set of quiz commands. Management commands are disabled in this mode.

3.2.1. Answering a card : `[ANSWER]`

An input without the \ prefix will be treated as an answer to the current card.
Format: [ANSWER]…

Usage rules:

You can answer with one or more words (e.g. "Tokyo" or "Aland Islands").

What a card contains:

For each card, total attempts and answer streak are tracked.
Total attempts refers to the number of times you have attempted this card, regardless of whether you were answered it correctly.
The answer streak is the number of times you have answered the card correctly consecutively.

The streak will be reduced to 0 after you answer a card wrongly twice in a row. Hence, if you accidentally enter the wrong answer once, your streak for the question will not be affected, unless you answer wrongly again.

You can press ENTER twice without entering any other input to reveal the answer.

Going through the different scenarios in a quiz:

Step 1:
The question is "Japan" and is asking for the capital of "Japan":
Enters Tokyo as answer
The picture shown below shows the expected result if the question has been answered correctly, which the total correct question counter increased by 1.

Figure 14. Expected result of answering the question correctly.

Step 2:
The question is "Tokyo" and is asking for the country of "Tokyo":
Enters Japaan as wrong answer
The picture shown below shows the expected result if the question has been answered wrongly once, which the total attempts counter increased by 1.

Figure 15. Expected result of answering the question wrongly once.

Step 3:
Same question as above, "Tokyo" and is asking for the country of "Tokyo":
Enters Jappan as another wrong answer
The picture shown below shows the expected result if the question has been answered wrongly twice, which shows the correct answer and the total attempts counter increased by 1.

Figure 16. Expected result of answering the question wrongly twice.

Step 4:
Same question as above, "Tokyo" and is asking for the country of "Tokyo":
Enters Japan as correct answer
The picture shown below shows the expected result if the question has been answered correctly after answer has been revealed, which shows how well each question is performed in this quiz.

Figure 17. Expected result of quiz after questions have been completed.

3.2.2. Labelling the current card as difficult: `\difficult`

Labels the current card as difficult.
Format: \difficult

Examples:

The question is "Japan" and is asking for the capital of "Japan":
Enters \difficult
Labelled this card as difficult as shown in the picture below.

Figure 18. Expected result of card labelled as difficult.

The question is "Japan" and is asking for the capital of "Japan":
Enters \difficult
Enters \difficult
Labelled this card as difficult as shown in the picture below.

Figure 19. Expected result of card labelled as difficult.

3.2.3. Viewing help: `\help`

Displays usage information on all quiz mode commands and acceptable inputs for answering cards.
Format: \help

3.2.4. Viewing the current card’s hint(s): `\hint`

Reveals the hint(s) for the current card (if any).
Format: \hint

Example:

Enters \hint
Reveals the hint of the current card

Figure 20. Expected result revealing the hint of the card.

3.2.5. Quitting the quiz session: `\quit`

Quits the current quiz session and switches back to management mode.
Format: \quit

Example:

The question is "Japan" and is asking for the capital of "Japan":
Enters Tokyo as answer
Enters \quit to quit the quiz.
Saves the progress of 1 attempted question "Japan".

Figure 21. Expected result of quitting a quiz after answering a question correctly.

3.2.6. Viewing the status of the current quiz: `\status`

Displays information on the current quiz’s status such as question progress (i.e. number of correct questions).
Format: \status

What does status display:

Total attempts refers to the number of times you have attempted this card, regardless of whether you answered it correctly.
Total correct answers refers to the number of times you correctly answered, regardless of the streak.
Current progress refers to which card are you currently on, out of all the cards in the quiz.

Example:

The question is "Japan" and is asking for the capital of "Japan":
Enters Tokyo as answer
Enters \status to view the status of the current quiz.
Saves the progress of 1 attempted question "Japan".

Figure 22. Expected result of viewing the status of a quiz after answering a question correctly.

3.3. User Transfer mode

You can use BrainTrain across different devices. This is an in-built feature that is automated in BrainTrain.

3.3.1. Using BrainTrain across different devices

To transfer your files:

Store the userdata and lessons folder into your transfer device (thumbdrive etc.).
On another device, ensure that BrainTrain has been executed at least once.
Transfer and overwrite the userdata and lessons folder.
Your progress will be automatically imported on that device.

4. Future enhancements

4.1. Importing data from website [Coming in v2.0]

Easily transfer files using import command to get files directly from a specific link without the use of transfer devices.
The usage of hard drives to transfer and pull documents has reduced overtime as new cloud storage are introduced. Thus, with this new feature, it will help to pull the user file and lessons from links.
Example : import User l/[INSERT_DESIRED_LINK_HERE]

4.2. Supporting timer countdown in quiz mode [Coming in v2.0]

User will see a 10 seconds timer countdown when answering a question (e.g. learn or review mode).

4.3. Supporting auto generation of mcq in quiz mode [Coming in v2.0]

BrainTrain will auto generate a list of mcq options depending on the list of values in the user specified lesson.

4.4. Support other spreadsheet formats such as .xlsx [Coming in v2.0]

BrainTrain will be able to accept more robust spreadsheet file formats.

4.5. Supporting starting a quiz session with multiple lessons [Coming in v2.0]

Format: start LESSON_INDEX_1 LESSON_INDEX_2 [c/COUNT1] [c/COUNT2] m/MODE
You can start a quiz session with cards from more than one lesson. The sequence of cards will be random instead of following the sequence of lessons to increase the difficulty for you to memorize.
Example: start 1 2 c/5 c/5 m/learn
- Starts a quiz with 5 words from the first lesson and 5 words from the second lesson in LEARN mode.

5. Troubleshooting

Q: Why are my card values shown as ??????
A: If your lesson contains non-English characters such as:

Characters with accents: à
Non-English words : こんにちは السلام عليكم 你好

This can be fixed by opening the lesson file in your preferred spreadsheet application (e.g. Excel), and then saving it as CSV UTF-8 (Comma delimited) (*.csv). UTF encoding allows a computer to show non-English characters.

The default encoding setting is unable to process special characters. As a result, you will need to save it as a UTF-8 encoded file.

Note that externally created lesson files have to be saved with UTF-8 encoding before using them in BrainTrain.
If the files are saved without UTF-8 encoding, any non-English data may be saved as ?????, and the data will be lost.

Q: Why are my lessons not loading?
A: Please verify if the location of BrainTrain is suitable. Depending on your computer’s permissions and security settings, places such as the Desktop may not be usable, and your operating system may prevent BrainTrain from loading the lesson files.

If BrainTrain still does not load lessons despite trying other locations, please contact Team BrainTrain at our issue tracker or email us at eugenef@u.nus.edu, and attach any generated braintrain.log files.

Viewing help: help
Changing theme: changeTheme
Starting a quiz session: start LESSON_INDEX [c/COUNT] m/MODE
- e.g. start 1 c/15 m/LEARN
Listing all lessons: listLessons
Adding a lesson: addLesson n/NAME t/TEST t/TEST [t/TEST]… [h/HINT]…
- e.g. addLesson n/Capitals of the world t/Country t/Capital t/Language h/Hint
Deleting a lesson: deleteLesson INDEX
Reloading all lessons: reload
Editing a lesson in Card View: edit INDEX
Quitting card view: quit
Listing all cards: listCards
Adding a card: addCard t/TEST t/TEST [t/TEST]… [h/HINT]…
- e.g. addCard t/Australia t/Canberra t/English h/Starts with C
Deleting a card: deleteCard INDEX
Listing entered commands: history
Exiting the program: exit

7.2. Quiz mode

Answering a card: [ANSWER]…
Labelling the current card as difficult: \difficult
Viewing help: \help
Viewing the current card’s hint(s): \hint
Quitting the quiz: \quit
Viewing the quiz session’s status: \status

7.3. User transfer

Using BrainTrain on another device