Computer-Aided Gift Exchange – Online Help

Computer-Aided Gift Exchange (CAGE) determines the most equitable and satisfactory distribution of gifts in a gift exchange among 3–12 participants. (If there are more than 12 participants, they must divide into groups of 12 or fewer.) Each participant contributes one gift to the pool. When the gifts have been opened and arranged so that all the participants can see all the gifts, the participants rank the gifts in order of preference, where 1 signifies the best gift. For example, if there are nine participants and nine gifts, each participant ranks the gifts from 1 to 9. The program then determines the best way to distribute the gifts, assigning one of the gifts to each participant.

Input

The program takes as input each participant's rankings for the gifts. This information must be in CSV (comma-separated values) format, which you can produce easily using a spreadsheet program.

To prepare the input, follow these steps:

  1. Using a spreadsheet program, either create a new spreadsheet or open an existing CAGE spreadsheet for modification.
  2. In the upper-left cell, enter the word Participant (or the equivalent in any written language).
  3. Below that (down the left column), enter the participant names, and to the right (across the top row), enter the gift labels. Each participant name and each gift label must be unique.
  4. In all the other significant cells, enter positive integers. These must range from 1 to the total number of gifts. In each row (which corresponds to a participant), each number must be unique, and there must be a number specified for each gift label. The number 1 signifies the gift most preferred by the participant, and the highest number signifies the gift least preferred by the participant.
  5. When you have entered all the data, save the spreadsheet in CSV format. Note that you can save only a single worksheet in this format, so if you are using a workbook with multiple worksheets, make sure that the pertinent worksheet is showing when you perform the Save As operation. If the spreadsheet program prompts you to select delimiters, select the comma as the field delimiter and the double quotation mark as the text delimiter.

When the input is ready, click the Browse button in CAGE, locate and select the CSV file that you want to process, and then click Submit. CAGE calculates and displays the results.

Output

The output that CAGE produces is a simple mapping that assigns one of the gifts by label to each participant by name. CAGE displays this information after performing the necessary calculations, and CAGE also stores the information in a file so that you can print the information or refer to it as needed after you have closed the program. The file is named results.txt, and you can find it in the directory that contains the CAGE program (ComputerAidedGiftExchange.jar).

How the Program Decides

If possible, CAGE avoids any arrangement in which a participant receives a gift ranked in the bottom third by that participant. Of the remaining possible arrangements, CAGE determines which produce the most net joy for the group based on the participants' rankings. When there is a tie between two possible arrangements in the "net joy" category, CAGE favors the arrangement with the most equal distribution of joy.

NOTE ABOUT CHOOSING GIFTS: For best results, set a price limit and instruct each gift buyer to choose a gift that is as nice as possible within that limit—a gift of the same quality as one that the buyer would like to receive. (Indeed, the buyer of a gift has a chance of receiving that gift.) Also, instruct the buyers to choose generic gifts—that is, gifts that a girl, a boy, a tall person, a short person, an old person, or a young person would enjoy.

Copyrights and Acknowledgments

Copyright Benjamin Fitch 2008. All rights reserved.

Computer-Aided Gift Exchange uses javacsv.jar, which comes with the following copyright statement:

Java CSV is a stream based library for reading and writing
CSV and other delimited data.

Copyright (C) Bruce Dunwiddie bruce@csvreader.com

This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation; either
version 2.1 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU Lesser General Public License for more details
(http://www.gnu.org/licenses/lgpl-3.0.txt).