User:JMatazzoni (WMF)/drafts/Event Metrics help
Event Metrics (formerly known as Grant Metrics[1]) enables organizers of events like editathons and content drives to get metrics about those events in order to understand and demonstrate the scale and impact of their contributions. Wikimedia grantees can use the program to provide grant documentation (such as metrics listed at Grants:Metrics).
To begin using Event Metrics, organizers first create a Program, which is an overall category for a series of events. Individual Events live inside Programs. For example, a Program might be be “Smallville Library Events, 2019." Events inside this program could be "Town History Month" or "Earth Day, 2019," etc. Users can compute metrics for each event and also look at metrics overall for a given program. Below is a detailed walkthrough for how to use the app.
Metric definitions[edit]
Learn what metrics are provided by the various Event Metrics reports and about the properties and limitations of each data type.
Getting started[edit]
Landing page[edit]
When you go to Event Metrics for the first time, you are presented with a landing screen that looks like this. It prompts you to login with OAuth. The background image is pulled from Commons, so every time you refresh, you see a new one!
Logging in[edit]
When you click on "Login with OAuth", you're presented with a dialog box which asks for your permission to provide Event Metrics with your username. The app doesn't pull any other data from your account.
My programs (Home page)[edit]
When you login with OAuth, you land on "My Programs" page. This page lists all of the programs that you're an organizer for. Anyone can create a program and anybody can be added as a program organizer. Keep in mind that only program organizers can create and edit events for a given program.
Note the two icons in front of every program? The gear icon is for modifying a program and the red delete icon is for deleting a program.
Keep in mind though that programs with events inside them cannot be deleted. You can create a new program by clicking the 'Create a new program' button on the right.
The metrics you see next to the program and combined metrics for all of the events in a program. We'll touch upon how to generate them below.
Creating a new program[edit]
By clicking the 'Create a new program' button in the previous screenshot, you come to this screen. Here you can create a new program by adding a program title and adding organizers for the program. Note that the creator of the program is automatically added as an organizer and cannot remove themselves. Note that the app will not let you save the participants list if a user you added as organizer is not registered.
New program on homepage[edit]
Once you add your program, you can come back to the home page (by clicking "My programs" link on top). Your new program will be there! But it doesn't have any events yet, so let's create one. You can go inside the program by clicking the program title. In this case "Women in Red".
Program page[edit]
This is the program view page. It lists the organizers on the left. You can click on them to see their Meta user page. It's empty right now because we don't have any events for it. We can create an event by clicking the "Create a new event" button.
Creating a new event[edit]
When you click the "Create a new event" button in the previous screen, you land on the Event Setting page. In order to create a new event, you need to fill in the form pictures at left with:
- A unique title for the event
- Wikis on which the event will run: Contributions will be tracked on the specified wikis only. But impact metrics will not be limited to these wikis. E.g., if you specify Commons, you’ll get metrics about the files you upload to Commons. But you’ll get pageview metrics for those files from every wiki where those files get placed.
- Per-wiki limit of 50,000 pages tracked: For each wiki in your event, Event Metrics will track a maximum of 50,000 pages (on Wikipedias and similar projects). On Commons, it will track up to 50,000 files, and on Wikidata that same number of items. If you expect your event to be bigger than that, try breaking it up. E.g, instead of trying to track all the categories or users in one event, spread them over multiple events.
- Date and time for the event duration (along with your preferred timezone).
When you Save your settings, the system creates the event and delivers you into the main Event Summary page. But your job is not yet complete: you must also provide filtering.
Filtering[edit]
Filtering is required[edit]
You can save an event without filters, but you won’t get metrics for the event until you add either Participants or Categories filtering—you can also combine both types. Here's a summary of the basic filtering requirements and of how the two filter types interact. The system will remind you of these rules during setup (see illustration).
- You must provide filtering for every wiki for which you want metrics.
- Participants filtering applies to all wikis and satisfies all minimum filtering requirements by itself.
- Category filters are specific to individual wikis because each wiki has different categories.
- If you use Categories without Participants, you must provide a category for every wiki for which you want metrics. If you provide categories for some wikis only, you’ll get metrics only for those wikis.
- If you combine Categories and Participants, contributions tracked will be those that satisfy both filters (i.e., Category AND Participants).
The two filtering type have different properties and restrictions, which are explained in the next sections.
Filter by Participants[edit]
To filter an event by Participants, you enter and save a list of wiki usernames. Once you do, reports for that event will track contributions only from those users.
- Covers all minimum filtering requirements: If you use a Participants list, you will get results for all wikis you specified in Event Settings and for all contribution types. If Wikidata is part of your event, you must supply Participants (Wikidata doesn't use Categories, so Category filtering is not available there).
- To add Participants type or paste wiki usernames, one per line, in the large text box (see illustration). Save the list. Usernames can include both underscores and spaces.
- Username validation: The list will update, as pictured. The green ticks indicate valid—meaning registered—usernames. The red symbol indicates that the username does not exist.
- You must remove or fix invalid usernames and click 'Save Participants' in order for your changes to be saved. Invalid names will prevent you from Saving any of the names. If you're having trouble saving a username, check for incorrect spelling, capitalization and extra formatting like bullets, spaces, commas etc.
- Automatic formatting of wiki lists: You can copy paste participants directly from on-wiki lists and they should be formatted correctly. For example, you can select all the participants you see on this page and paste them in the input box on Event Metrics and they appear formatted correctly, one per line.
Filter by Categories[edit]
Category filtering restricts metrics to pages and files that are in the a specified category or group of categories.
- Categories are wiki specific: You must name a wiki for each category you provide. The category will apply only to that wiki.
- Main namespace only: For filtering purposes, categories must by must be applied to main/article namespace pages. E.g., talk page categories won’t work. Commons is an exception (see below).
- Applies to files on Commons: On Commons only, Category filtering works for uploaded files, including images, videos, audio files, etc.
- Subcategories are not tracked automatically. If you want to include subcategories, you must specify them directly.
- Hidden categories are allowed by the system. (Make sure to check with the policies and practices governing the use of hidden categories on your local wiki).
- Categories without Participants: If you use Categories filtering without Participant filtering, you must supply a category for every wiki about which you want metrics. If you don’t, you won’t get metrics for that wiki. (As described above, Participants filtering automatically covers every wiki and contribution type.)
- No Wikidata metrics: Categories don’t work on Wikidata, so if you don’t supply a Participants list, you will see no metrics about Wikidata items
- No local file uploads: Category filtering won’t work for files uploaded directly to Wikipedias. If you want to track such file uploads, you must include a Participants list.
- To add categories: Begin typing the abbreviation for the name of a wiki (see list of wiki abbreviations).
Getting reports[edit]
Update data[edit]
When you click on "Calculate totals" above the table on top, it starts computing the five metrics. This can be instantaneous or it can take a while, depending on the size of the participants, their activity, the length of the event and the number of wikis involved.
Once it finished computing the metrics, it refreshes the page and modifies the table you see with updated metrics.
Note: The number of participants, new editors and editor retention metrics are consistent across all wikis so you don't see an entry for those for each wiki. You only see the number in the Totals row. More on those metrics is defined on top. Also note that viewing data is disabled while the metrics are being computed.
Viewing all data[edit]
When you click the "View all data" button (next to "Calculate totals"), you land on this screen. Here, you can see every edit made by participants on your list, on the wikis your event ran on, over the duration of the event.
For example your event ran on enwiki and hewiki for 1 Feb 2018 00:00 UTC to 10 Feb 2018 00:00 UTC. Your participants were User:A and User:B. Then the "View all data" page will show you edits by User:A and User:B on enwiki and hewiki during 1 Feb 2018 00:00 UTC to 10 Feb 2018 00:00 UTC.
From here you can download all the data as a CSV file or export it as a wikitable. If you click on "Download as CSV", it automatically downloads the CSV file for you. If you click on "Download as wiki table", it opens another page which contains the wikitext tables for the top stats and for the edits made during the event (which we see on this page).
Troubleshooting[edit]
Something doesn't work as expected? You could try...
- Using a different browser
- Restricting the participant list or the number of wikis or the duration of your event
If you find a bug, congratulations! You found one despite our extensive testing! Please take the time to file a bug report on Phabricator. Or tell us about it on the discussion page. We'll try to get back to you as soon as possible.
- ↑ Some screenshots in this documentation may still show the old name "Grant Metrics". The workflow and functionality is the same, however.