Difference between revisions of "Census Addons"

From Gramps
Jump to: navigation, search
(Future Enhancements)
(Writing your own defintions)
(25 intermediate revisions by 7 users not shown)
Line 1: Line 1:
[[Category:Plugins]][[Category:Developers/General]]
+
[[Category:Plugins]][[Category:Developers/General]][[Category:Reports]][[Category:Gramplets]]
 +
 
 
There are two census addons: a gramplet and a report.
 
There are two census addons: a gramplet and a report.
  
Line 10: Line 11:
 
Before using the census addons you need to define which of your sources are census sources.
 
Before using the census addons you need to define which of your sources are census sources.
  
To do this you need to edit each source and add an entry in the Data tab.  The entry must have a key of "Census" and a value which is a code that identifies the census.
+
To do this you need to edit each source and add an entry in the Data tab.  The entry must have a key of "Census" and a value which is a code that identifies the census. After typing the value code you must press "Enter" before clicking "OK", or the value will not be saved.
  
 
[[Image:SourceForCensus.png]]
 
[[Image:SourceForCensus.png]]
  
Supported values are:
+
=== Supported definitions ===
{| {{Prettytable}}
+
 
|-
+
A number of supported [[Census Definitions|definitions]] are included with the download.
! Code !! Description
+
 
|-
+
A full list of codes is available. See: [[Census Definitions]]
| UK1841 || 1841 England and Wales Census
+
 
|-
+
=== Writing your own defintions ===
|  UK1851 || 1851 England and Wales Census
+
 
|-
+
If a census you require is not in the list of supported definitions then you can write your own.
|  UK1861 || 1861 England and Wales Census
+
 
|-
+
Census defintions are stored in a XML files. These are located in the Census directory beneath your plugins directory. The file called census.xml, provided in the download, contains some common definitions. Additional files called custom.xml and test.xml will also be searched.
|  UK1871 || 1871 England and Wales Census
+
 
|-
+
Definition files consist of an XML declaration followed by a censuses element.  
| UK1881 || 1881 England and Wales Census
+
 
|-
+
  <?xml version="1.0" encoding="UTF-8" ?>
| UK1891 || 1891 England and Wales Census
+
  <censuses>
|-
+
 
| UK1901 || 1901 England and Wales Census
+
The censuses element contains a number of census elements, each representing a census definition. The census start-tag contains 3 attributes:
|-
+
 
| UK1911 || 1911 England and Wales Census
+
* id : A unique code to identify the census definition.
|-
+
* title : A description of the census.
|}
+
* date : The date of the census in a Gramps date format.
{| {{Prettytable}}
+
 
|-
+
  <census id='UK1841' title='1841 UK Census' date='6 Jun 1841'>
! Code !! Description
+
 
|-
+
Each census element should contain a column element for each column in the census. Column elements describe information that may be recorded for each person on the census.
| - || 1774 French Census
+
 
|-
+
A column element contains:
| FR1790 || 1790 French Census
+
 
|-
+
* An _attribute element. This contains the key used to store column information in the Attributes of Event Reference objects within the Gramps database. Once defined this text must not be changed.
|  FR1793 || 1793 (An II) French Census
+
* An optional _longname element. This contains a fuller description of the column that is used in the tooltips in the editor and for the heading in the census report.
|-
+
* A size element. This contains the size of the column in the census report. It is a percentage of the page width. The sum of all size elemnts in a definition should total 100.
|  FR1796 || 1796 (An V) French/Belgian Census
+
 
|-
+
  <column>
|  FR1801 || 1801 (An X) French/Belgian Census
+
    <_attribute>At Home</_attribute>
|-
+
    <_longname>Working at Home</_longname>
|  FR1806 || 1806 French/Belgian Census
+
    <size>7</size>
|-
+
  </column>
| - || 1817 French Census
+
 
|-
+
Note: The underscore is important and indicates that the text should be translated by translators.
|  FR1820 || 1820/1821 French Census
+
 
|-
+
Each census element may optionally contain heading elements. Heading elements describe information that is recorded once for each census.
|  FR1826 || 1826 French Census
+
 
|-
+
A heading element contains:
|  FR1831 || 1831 French Census
+
 
|-
+
* An _attribute element. This contains the key used to store census information in the Attributes of Event objects within the Gramps database.
|  FR1836 || 1836 French Census
+
 
|-
+
  <heading>
|  FR1841 || 1841 French Census
+
    <_attribute>City or Borough</_attribute>
|-
+
  </heading>
| FR1846 || 1846 French Census
+
 
|-
+
Although you can add your definitions to the pre-defined entries in census.xml, you can create a separate file called custom.xml for this purpose.
|  FR1851 || 1851 French Census
+
 
|-
+
=== Submitting your definitions ===
| FR1856 || 1856 French Census
+
 
|-
+
Once you have written some custom definitions, you may wish to share them with the Gramps community.
| FR1861 || 1861 French Census
+
 
|-
+
A [[Census Testing]] area is available for this purpose.
| FR1866 || 1866 French Census
+
|-
+
| FR1872 || 1872 French Census
+
|-
+
| FR1876 || 1876 French Census
+
|-
+
| FR1881 || 1881 French Census
+
|-
+
| FR1886 || 1886 French Census
+
|-
+
|  FR1891 || 1891 French Census
+
|-
+
|  FR1896 || 1896 French Census
+
|-
+
|  FR1901 || 1901 French Census
+
|-
+
|  FR1906 || 1906 French Census
+
|-
+
|  FR || Local Census (not national)
+
|-
+
|}
+
{| {{Prettytable}}
+
|-
+
! Code !! Description
+
|-
+
|  - || 1814 Belgian/French Census
+
|-
+
| - || 1829 Belgian/Nederland Census
+
|-
+
| BE1846 || 1846 Belgian Census
+
|-
+
| BE1856 || 1856 Belgian Census
+
|-
+
|  BE1866 || 1866 Belgian Census
+
|-
+
| BE1880 || 1880 Belgian Census
+
|-
+
| BE1890 || 1890 Belgian Census
+
|-
+
| BE1900 || 1900 Belgian Census
+
|-
+
|  BE1910 || 1910 Belgian Census
+
|-
+
|}
+
{| {{Prettytable}}
+
|-
+
! Code !! Description
+
|-
+
|  US1790 || 1790 US Census
+
|-
+
|  US1800 || 1800 US Census
+
|-
+
|  US1810 || 1810 US Census
+
|-
+
|  US1820 || 1820 US Census
+
|-
+
|  US1830 || 1830 US Census
+
|-
+
|  US1840 || 1840 US Census
+
|-
+
|  US1850 || 1850 US Census
+
|-
+
|  US1860 || 1860 US Census
+
|-
+
|  US1870 || 1870 US Census
+
|-
+
|  US1880 || 1880 US Census
+
|-
+
|  US1890 || 1890 US Census
+
|-
+
|  US1900 || 1900 US Census
+
|-
+
|  US1910 || 1910 US Census
+
|-
+
|  US1920 || 1920 US Census
+
|-
+
|  US1930 || 1930 US Census
+
|-
+
|}
+
  
 
==Census Gramplet==
 
==Census Gramplet==
Line 165: Line 87:
  
 
===Census Editor===
 
===Census Editor===
 +
 +
[[File:census edition.png|thumb|400px|right|Census edition]]
  
 
The census editor is designed so that most census data can be entered into a single form.
 
The census editor is designed so that most census data can be entered into a single form.
  
The first thing to enter is the census source.  This is selected from a drop-down list at the top of the editor.
+
* The first thing to enter is the census source.  This is selected from a drop-down list at the top of the editor.
  
Once the source has been selected the census date is populated automatically.
+
* Once the source has been selected the census date is populated automatically.
  
Next a source reference can be entered.  This should comprise of one or more references that uniquely identify the census entry.  In the case of a UK census you will need to enter the PRO reference, Piece, Folio and Page.
+
* Next a source reference can be entered.  This should comprise of one or more references that uniquely identify the census entry.  In the case of a UK census you will need to enter the PRO reference, Piece, Folio and Page.
  
A place can be selected in the usual Gramps manner.
+
* A place can be selected in the usual Gramps manner.
  
 
At the bottom of the editor there is a table which allows the user to enter data specific to individual people listed on the census return.  A new person can be created and then added to the census by clicking the "+" button.  A person already in Gramps can be added to the census by clicking the second button ("share").  A census source must be selected before people can be added to the list, and after the first person is added, the source can no longer be changed.
 
At the bottom of the editor there is a table which allows the user to enter data specific to individual people listed on the census return.  A new person can be created and then added to the census by clicking the "+" button.  A person already in Gramps can be added to the census by clicking the second button ("share").  A census source must be selected before people can be added to the list, and after the first person is added, the source can no longer be changed.
Line 186: Line 110:
 
The census data can then be saved by clicking the "OK" button or discarded using "Cancel".
 
The census data can then be saved by clicking the "OK" button or discarded using "Cancel".
  
==Census Report==
+
==Samples==
 +
 
 +
===Census Report===
  
 
The census report prints census events in a format similar to the original census entries.
 
The census report prints census events in a format similar to the original census entries.
Line 206: Line 132:
  
 
The last option prints all censuses in the database.
 
The last option prints all censuses in the database.
 +
 +
''Census Report for Martin, John''
 +
1881
 +
Date:                3 Apr 1881                   
 +
Source Reference:    17 Hope Terrace - RG 11 /2854 page 27                 
 +
Address:            Wednesbury
 +
                   
 +
Name              Relation  Condition  Age  Occupation    Where Born    Disability
 +
Martin, John      Head      Married    36  Laborer      Wednesbury    /
 +
N., Zillah        Wife                36                Golds Greence
 +
Martin, Arthur    Son                  11  Scholar      Wednesbury   
 +
Martin, Zillah    Daughter              7  Scholar      Wednesbury   
 +
Martin, Catherine Daughter              5  Scholar      Wednesbury
 +
 +
===NarrativeWeb Report===
 +
 +
[[File:narrative census.png|thumb|370px|right|Census data on individual form for NarrativeWeb Report]]
 +
 +
[[File:narrative events.png|thumb|370px|left|Shared Event]]
 +
 +
<br clear="all" />
  
 
==Data Storage==
 
==Data Storage==
 +
 +
[[File:census data.png|thumb|400px|right|Census data]]
  
 
Each census return is stored as a single event record with an event type of "Census".
 
Each census return is stored as a single event record with an event type of "Census".
Line 220: Line 169:
  
 
Data can also be edited using the usual Gramps editors.
 
Data can also be edited using the usual Gramps editors.
 +
 +
 +
 +
 +
==Example of using the Census Addon==
 +
 +
This is an example of how to get started with the Census Addon after it is installed as described above. The 1941 UK census is used as the example:
 +
# Start or open a family tree in Gramps.
 +
# Add a person (name and gender) if this is a new family tree.
 +
# Go to the Source view.
 +
# Add a source with a title like "Source for 1841 Census"
 +
# Open that source and go to the "Data" tab.
 +
# Click on the plus symbol to add a key and value.
 +
# Fill in in the key column with "Census" and hit enter.
 +
# Click on Value column and fill in "UK1841", hit enter.
 +
# Click on OK.
 +
# Reopen the Source to see if the key and value pair have been successfully stored in the "Data" tab (optional).
 +
# Go to the People view and switch on the sidebar (View->sidebar).
 +
# Add the "Census Gramplet" by rightclicking on the side bar and choosing "Add Gramplet->Census Gramplet".
 +
# Select the person that you created (or an existing person that appears in that census) in the main window.
 +
# In the Census Gramplet on the sidebar, click "New".
 +
# The New Census" gramplet form should open and you can click on the arrow down bútton to the right of "Source". You should see the "Source for 1841 Census". Select this.
 +
# Now you can enter all of the details from the census (e.g. Reference to the page and the address), and then add people in the normal Gramps way.
 +
# Fill in the details from the census page against each person.
 +
  
 
==Known Issues==
 
==Known Issues==
Line 229: Line 203:
 
==Future Enhancements==
 
==Future Enhancements==
  
I plan to implement the following enhancements:
+
Possible future enhancements:
* Add heading fields for Municipal Ward, Ecclesiastical Parish etc...
+
 
 
* Split the Source Reference Page/Volume field into its component parts.  (e.g. Ref., Piece, Folio, Page)
 
* Split the Source Reference Page/Volume field into its component parts.  (e.g. Ref., Piece, Folio, Page)
* Add a census image to gallery of the Event object.
 
 
* Add the current person when creating a new census.
 
* Add the current person when creating a new census.
 
* Improve data entry into the table cells.  Automatically edit the next cell when "Enter" is pressed.
 
* Improve data entry into the table cells.  Automatically edit the next cell when "Enter" is pressed.
 
The following have been requested but require further thought:
 
 
* Add check-boxes to automatically add the census source to selected Gramps records.
 
* Add check-boxes to automatically add the census source to selected Gramps records.
 
* Ensure that attributes are kept in the correct order in the Gramps editor.
 
* Ensure that attributes are kept in the correct order in the Gramps editor.
 
* Remove the need to add Data tags to sources.  Create a tool to define census sources and store them in the Gramps configuration file.
 
* Remove the need to add Data tags to sources.  Create a tool to define census sources and store them in the Gramps configuration file.
  
==External Links and ressources==
+
==External Links and resources==
  
 
* [[Census|Census page on wiki]]
 
* [[Census|Census page on wiki]]
 +
* [[File:CanadianCensus.gramps.gz|Census source definitions for available Canadian Censuses]]
 +
* [[Events_manager#Census_Addon|Sample of use]]
 +
* [http://www.chradams.co.uk/censusxml/howitworks.php Census XML project]
 +
* [http://www.nappdata.org/napp/index.shtml North Atlantic Population Project]

Revision as of 11:15, 19 March 2013


There are two census addons: a gramplet and a report.

The gramplet allows users to create and edit census data in a single form.

The report prints census events in a format similar to the original census entries.

Configuration

Before using the census addons you need to define which of your sources are census sources.

To do this you need to edit each source and add an entry in the Data tab. The entry must have a key of "Census" and a value which is a code that identifies the census. After typing the value code you must press "Enter" before clicking "OK", or the value will not be saved.

SourceForCensus.png

Supported definitions

A number of supported definitions are included with the download.

A full list of codes is available. See: Census Definitions

Writing your own defintions

If a census you require is not in the list of supported definitions then you can write your own.

Census defintions are stored in a XML files. These are located in the Census directory beneath your plugins directory. The file called census.xml, provided in the download, contains some common definitions. Additional files called custom.xml and test.xml will also be searched.

Definition files consist of an XML declaration followed by a censuses element.

<?xml version="1.0" encoding="UTF-8" ?>
<censuses>

The censuses element contains a number of census elements, each representing a census definition. The census start-tag contains 3 attributes:

  • id : A unique code to identify the census definition.
  • title : A description of the census.
  • date : The date of the census in a Gramps date format.
<census id='UK1841' title='1841 UK Census' date='6 Jun 1841'>

Each census element should contain a column element for each column in the census. Column elements describe information that may be recorded for each person on the census.

A column element contains:

  • An _attribute element. This contains the key used to store column information in the Attributes of Event Reference objects within the Gramps database. Once defined this text must not be changed.
  • An optional _longname element. This contains a fuller description of the column that is used in the tooltips in the editor and for the heading in the census report.
  • A size element. This contains the size of the column in the census report. It is a percentage of the page width. The sum of all size elemnts in a definition should total 100.
<column>
    <_attribute>At Home</_attribute>
    <_longname>Working at Home</_longname>
    <size>7</size>
</column>

Note: The underscore is important and indicates that the text should be translated by translators.

Each census element may optionally contain heading elements. Heading elements describe information that is recorded once for each census.

A heading element contains:

  • An _attribute element. This contains the key used to store census information in the Attributes of Event objects within the Gramps database.
<heading>
    <_attribute>City or Borough</_attribute>
</heading>

Although you can add your definitions to the pre-defined entries in census.xml, you can create a separate file called custom.xml for this purpose.

Submitting your definitions

Once you have written some custom definitions, you may wish to share them with the Gramps community.

A Census Testing area is available for this purpose.

Census Gramplet

The census gramplet consists of a census listing and a census editor.

Census Listing

When the gramplet is loaded it lists all the census events for the active person. The listing displays the census source, date and place.

A new census event can be created by clicking the "New" button at the bottom of the gramplet.

An existing census event can be edited either by highlighting a row and clicking the "Edit" button or by double-clicking on a row.

Census Editor

Census edition

The census editor is designed so that most census data can be entered into a single form.

  • The first thing to enter is the census source. This is selected from a drop-down list at the top of the editor.
  • Once the source has been selected the census date is populated automatically.
  • Next a source reference can be entered. This should comprise of one or more references that uniquely identify the census entry. In the case of a UK census you will need to enter the PRO reference, Piece, Folio and Page.
  • A place can be selected in the usual Gramps manner.

At the bottom of the editor there is a table which allows the user to enter data specific to individual people listed on the census return. A new person can be created and then added to the census by clicking the "+" button. A person already in Gramps can be added to the census by clicking the second button ("share"). A census source must be selected before people can be added to the list, and after the first person is added, the source can no longer be changed.

The cells in the table are editable. By clicking on a cell, the user can enter data from the census return into a corresponding column in the table.

A person can be removed from the list by clicking the "-" button.

The order of people in the list can be changed by highlighting a row and then using the up and down arrow buttons.

The census data can then be saved by clicking the "OK" button or discarded using "Cancel".

Samples

Census Report

The census report prints census events in a format similar to the original census entries.

Which censuses are printed is determined by settings in the Report Options.

A drop-down list allows the following options:

  • By Person
  • By Source
  • By Person and Source
  • All Census records

Use the first option to print all census records for a given person. This defaults to the current person but can be changed using a selector.

Use the second option to print all census records for a given source. Select the required source from the drop-down list.

The third option can be used to print a single census. Both the person and source selections are taken into account.

The last option prints all censuses in the database.

Census Report for Martin, John
1881 
Date:                3 Apr 1881                    
Source Reference:    17 Hope Terrace - RG 11 /2854 page 27                   
Address:             Wednesbury 
                    
Name              Relation  Condition  Age  Occupation    Where Born    Disability
Martin, John      Head      Married    36   Laborer       Wednesbury    / 
N., Zillah        Wife                 36                 Golds Greence
Martin, Arthur    Son                  11   Scholar       Wednesbury    
Martin, Zillah    Daughter              7   Scholar       Wednesbury    
Martin, Catherine Daughter              5   Scholar       Wednesbury

NarrativeWeb Report

Census data on individual form for NarrativeWeb Report
Shared Event


Data Storage

Census data

Each census return is stored as a single event record with an event type of "Census".

The chosen source is attached to the event and contents of the "Reference" field are stored and the "Volume/Page" field of the associated source reference object.

The "Date" and "Place" fields are stored in the event object.

Each person in the table is attached to the event. The contents of the table are stored as attributes in the associated event reference object. The attribute type is set to the column heading and the value is set to the contents of the cell. An additional attribute called "Order" contains an integer which defines the position that the person appears in the census.

The addons will read existing data in this format. If "Order" attributes do not exist, they will be created when the editor saves a record. Until then the order of the people in the census will not be defined.

Data can also be edited using the usual Gramps editors.



Example of using the Census Addon

This is an example of how to get started with the Census Addon after it is installed as described above. The 1941 UK census is used as the example:

  1. Start or open a family tree in Gramps.
  2. Add a person (name and gender) if this is a new family tree.
  3. Go to the Source view.
  4. Add a source with a title like "Source for 1841 Census"
  5. Open that source and go to the "Data" tab.
  6. Click on the plus symbol to add a key and value.
  7. Fill in in the key column with "Census" and hit enter.
  8. Click on Value column and fill in "UK1841", hit enter.
  9. Click on OK.
  10. Reopen the Source to see if the key and value pair have been successfully stored in the "Data" tab (optional).
  11. Go to the People view and switch on the sidebar (View->sidebar).
  12. Add the "Census Gramplet" by rightclicking on the side bar and choosing "Add Gramplet->Census Gramplet".
  13. Select the person that you created (or an existing person that appears in that census) in the main window.
  14. In the Census Gramplet on the sidebar, click "New".
  15. The New Census" gramplet form should open and you can click on the arrow down bútton to the right of "Source". You should see the "Source for 1841 Census". Select this.
  16. Now you can enter all of the details from the census (e.g. Reference to the page and the address), and then add people in the normal Gramps way.
  17. Fill in the details from the census page against each person.


Known Issues

When using the census editor the user should not edit the same event using the standard Gramps event editor.

When the save button in the editor is clicked, the person records of the people in the census are updated. If a person is being edited using the Gramps person editor and the record is saved then data saved using the census editor will be lost for this person.

Future Enhancements

Possible future enhancements:

  • Split the Source Reference Page/Volume field into its component parts. (e.g. Ref., Piece, Folio, Page)
  • Add the current person when creating a new census.
  • Improve data entry into the table cells. Automatically edit the next cell when "Enter" is pressed.
  • Add check-boxes to automatically add the census source to selected Gramps records.
  • Ensure that attributes are kept in the correct order in the Gramps editor.
  • Remove the need to add Data tags to sources. Create a tool to define census sources and store them in the Gramps configuration file.

External Links and resources