Editing Module:PopulationFromWikidata/doc (section)

== What the module does ==
=== Population sources ===
The module is designed to be invoked from the [[Template:Infobox_Australian_place|Infobox Australian place]] template and gathers data from the Wikidata item linked to each article. The module may be modified and used in other places/cases in the future. 

Currently, this module is invoked in such a way that it will only give the Infobox a population figure if one isn't manually given for the [[Template:Infobox_Australian_place|Infobox Australian place]] ''pop'' argument. This means that initially the module will not impact many articles. Over time, once we're certain it is working well, we can remove the manually added population figures in favour of the Wikidata figures brought in by the module. 

See line 110 of the [[Template:Infobox_Australian_place|Infobox Australian place]] template for the module invoke.

=== How to see the module in action ===
Currently the module will only give a population figure to the Infobox if one has not been manually added via the Infobox Australian place template ''pop'' field. This means if you want to see the module in action for a particular place article, you should follow these steps:

# Pick a Wikipedia place article and check that the linked Wikidata item has a [[w:Module:PopulationFromWikidata#Census_data|valid population claim]] (most now do, but some values will be old because not all 2021 Census data has been released yet).
# If the Wikidata item looks good, then edit the Infobox Australian place template part of the article. Remove the ''pop'' value and replace with a comment like: ''“&lt;!--Leave blank to draw the latest automatically from Wikidata--&gt;”.'' Remove the ''pop_year'' and ''pop_footnotes'' fields. Check if the old ''pop_footnotes'' reference had been used elsewhere in the article.
# Check the output in the article Infobox. If the output is not as expected then edit the Wikidata item or if it’s really broken, get in touch [[w:Module_talk:PopulationFromWikidata|here.]]
Here's an [[Maylands, Western Australia|example]] of an article with Infobox using the module, and the [https://en.wikipedia.org/w/index.php?title=Maylands,_Western_Australia&curid=1336427&diff=1099730354&oldid=1066133969 diff] of the edit made.

The list of articles using population values from Wikidata (via this module) is [[w:Category:Australian_place_articles_using_Wikidata_population_values|here]].

=== Assumptions ===
The module works with the following assumptions:
* That all Australian place Wikipedia articles are linked to relevant Wikidata items (true because Canley and 99of9 have done this work).
* Relying on the type field of the Infobox Australian place template being a required field and assuming it always has a value specified. 
* We're only considering population values associated with the Australian Bureau of Statistics' defined [https://www.abs.gov.au/statistics/standards/australian-statistical-geography-standard-asgs-edition-3/jul2021-jun2026#asgs-diagram Australian Statistical Geographic Standard] areas.
* Assuming that the linked Wikidata item will likely have population statements for multiple Australian Bureau of Statistics geographic areas that encompass the item place.
* We’re ignoring any ranking of population statements.

=== Population selection ===
The high level steps of the module work flow are outlined in the diagram below. There are three major steps in the process of selecting the best population figure from a Wikidata item.

==== Step 1. Check which population claims have enough information to be considered====
As a minimum they are required to have:
# A ''point in time'' qualifier date (this helps to choose the most recent population figures).
# An ''applies to part'' qualifier value (this states which ABS geography type the population is for and helps choose the most appropriate geographic area for the place article).
# A ''determination method'' qualifier item (this specifies if it is a census population figure or a non-census population estimate and helps define the reference components).
# Some reference information (it is a requirement to have something with which to build a reference but more than the minimum is recommended - see the Population data in Wikidata section).
     
After filtering for these requirements a subset of population claims is carried forward.

==== Step 2. Check which population claims match the Infobox Australian place ''type'' value ====
The next part of the module separates the valid population claims into those which have ''applies to part'' values (defined ABS geography types) that match the Infobox ''type'' and those that don't. 
For the Infobox types that can map to multiple ABS geography types (eg. ''type'' = town), the most common mapping is considered a match initially and the other mappings are considered later in the module if the first preference isn't available. For example, ''type'' = town is matched to Urban Centres and Localities (UCL) as a first preference, but also returns population values for Suburbs and Localities (SAL) and Indigenous Locations (ILOC) instead, if they exist.

The mappings are based on outputs of summary SPARQL queries pulling out Infobox place ''type'' versus ABS geography types specified in linked Wikidata item (for all Australian place articles). The module uses the following mappings. 

{|class="wikitable"
! Infobox ''type'' !! ABS geographic area
|-
| City || Urban Centres and Localities (UCL)
|-
| Suburb || Suburbs and Localities (SAL)
|-
| Town || Urban Centres and Localities (UCL) (or SAL or Indigenous Locations (ILOC))
|-
| LGA  || Local Government Areas (LGA)
|-
| Region || Local Government Areas (LGA) (for now)
|}


==== Step 3. Check which population claims have the most recent figures ====
The next step is to check within the two sets of claims (''applies to part'' geography matched or not) and find the most recent population figure per each ''applies to part'' value. For example, in the list of claims with ''applies to part'' geography not matching the Infobox, there are likely multiple ''applies to part'' values (UCL, SA1 etc) and multiple point in time values (2006, 2011, 2016 etc). This step finds the most recent population figures for each geography type (eg 2016  UCL; 2021 SA1).

There are then three different types of outputs depending on the outcomes of the Step 2 and Step 3 filtering.

===== Step 3A. Outputs for claims with geography match to Infobox ''type'' =====
This is Output Scenario 1 and gives the Infobox one formatted population figure, with the relevant ''applies to part'', ''point in time'' year and full [[Template:Cite_web|Cite web]] reference(s).
Eg. 5,089 (Suburb and Locality 2021)<sup>[1]</sup>

===== Step 3B Towns. Second preference output for Infobox ''type'' = town =====
This is Output Scenario 2 and gives the Infobox up to two formatted population figures, each with the relevant ''applies to part'', ''point in time'' year and full [[Template:Cite_web|Cite web]] reference(s). This happens when there is no valid UCL population claim and is the second preference output for ''type'' = town places.
E.g. 
* 100 (Urban Centre and Locality 2021)<sup>[1]</sup>
OR 
* 90 (Indigenous Location 2021)<sup>[1]</sup>
* 100 (Suburb and Locality 2021)<sup>[2]</sup>

===== Step 3B. Outputs for claims with no geography match to Infobox ''type'' =====
This is Output Scenario 3 and gives the Infobox (possibly) multiple formatted population figures (one for each applies to part value), each with the relevant ''applies to part'', ''point in time'' year and full [[Template:Cite_web|Cite web]] reference(s).
Eg. If Infobox ''type'' = city that's mapped to UCL (ands leads to Output Scenario 1), but if there're no UCL population values you might get this output:

* 100 (GCCSA 2021)<sup>[1]</sup>
* 100 (SUA 2016)<sup>[2]</sup>
* 120 (SA1 2016)<sup>[3]</sup>

=== References ===
The references are formatted using the [[Template:Cite_web|Cite web]]  template. 

The census population figure references take this form:
Australian Bureau of Statistics (28 June 2022). "Cosmo Newberry (Indigenous Locations)". ''Australian Census 2021 QuickStats''. Retrieved 28 June 2022. 

The non-census derived population figure references take this form:
Australian Bureau of Statistics (29 March 2022). "Population estimates by SA2 and above, 2001 to 2021 (Greater Capital City Statistical Areas)". ''Australian Regional Population''. Retrieved 28 June 2022.

The references are named, using this method (for now): name = refwork.."_"..pointintime.."_"..appliespart.."_"..reftitle. This is long-winded because we are aiming for a unique reference name for each population value.


=== Module work flow diagram (draft) ===

<div style="background-color:white; text-align:center; padding:1em;">[[File:PopulationFromWikidata Diagram.png]]</div>


=== Example outputs ===

There are some example outputs in the Infobox Australian place Sandbox Test Cases page [[Template:Infobox_Australian_place/testcases#Population_Tests|here]].