Should we be using the user's preferred checklist (rather than the project default)?

[pmorrill]

In Dendroica, users can set a preference for their naming checklist. At the moment, the API ignores this preference and delivers all species lists using the project default checklist.

It is not a difficult change to instead deliver species using the preferred checklist, and no change in the app would be required w.r.t species querying and displaying.

However, we would want the mobile app to report the checklist to the user. Probably we should be doing that anyway.

What I propose to get this started, is to add the checklist name to the user profile object. The app would then report that to the user. If the user had no preference set, then the checklist would be the project default.

If the user has a preference, we would then use that in the API to deliver the species list (no changes required in the app itself).

But there is a catch-22. When a user signs in, we do not actually know what project they will be working with, so we are not able to resolve their checklist preference for that project.

The solution to this (which does mean a change in the app code) is to make a 2nd call to /profile AFTER the project has been chosen in the app. The function /api/profile?token=asdfasdf&projectId=1 will return a profile structure that includes project-specific preferences. Currently it delivers the preferences for exclusion of rare and / or non-breeding species. It could also include the checklist name so it could be displayed to the user.

[RobynVG]

I'm assuming naming checklist is the taxonomy?

I think to be able to comment on this I would need to understand better how taxonomy works but I have some comments so far based on assumptions.

What I think is going on is that the same species may have multiple IDs each corresponding to a seperate taxonomy.
The problem I am forseeing with this is the ability to switch taxonomies.

If a user imports their default checklist for a project at startup the correct IDs are loaded in so there doesn't seem to be a problem here. However, I think it would only make sense that if a user is able to select or import a default checklist on project load they should also be able to change this setting. I'm not too sure what the implications of this would be. Would I need to refresh the SpeciesRegions table and import additional species into Species? Would this have implications on any of the other tables?

I think the second call to profile? after a project has been loaded makes sense. That way we can display a message that asks the user if they would like to use the imported preferences, describe what they are, and inform them that they can be changed in the settings pannel in the future.

My other question is, that when I currently fetch user information I get naming and sorting preferences. Are these actually project specific? I'm wondering if I should break these up into namingP1, namingP2,... ,sortingP1, sortingP2,... for each project so that if more than one project is loaded the user can switch between without making an API call to replace the fields.

Which actually, brings me to one more question. Will there be an issue if a user has multiple projects loaded with differing naming preferences. My assumption
would be no, since the master region/species table would only contain species corresponding to the taxonomy for the specific project.

[pmorrill]

You are about right: a checklist is a taxonomic filter. Each checklist is established at a certain moment in time, and includes all the named species at that point. We therefore keep loads of 'taxa naming' records that are needed for previous checklists, and not necessarily the most current one. So when you download a set of species, the checklist that I use is what determines the names that I deliver (I hide all the cross-linkages from the app).

Species names change for 3 reasons:

1. sometimes a species is just renamed, full stop
2. sometimes 2 species are merged into one
3. sometimes a species is split into 2 (or more)

Each of these events happens at the moment that a new checklist is released by the AOU.

As I mentioned, our taxonomy in Dendroica is out of date. We only have the linkages for AOU_7-56, and several checklists ave been released since then. I intend to work on this problem this winter.

Anyroad: I would not let people switch checklists in the first version of the app, for the reasons you mention. But they do have the option of saving their preferred checklist in the web interface, and we could use that preference to deliver the species names to the app. Checklists are definitely PROJECT-SPECIFIC. The S. American projects use different checklists entirely, for example.

[pmorrill]

Some preferences are global and some apply only to specific projects.

Global prefs:

• naming convention (scientific vs checklist naming)
• sort order (alphabetic vs checklist ordering)
• language

Project-specific:

• exclude rare species in region
• exclude non-breeding species
• preferred checklist (taxonomy)

So, only the later 3 need to be stored on a project by project basis.

[pmorrill]

I have updated the api so that the /profile call delivers the user's project-specific checklist preference (which will often be the same as the project default). I deliver both the name and the checklistId - we will have to decide how you want to stick-handle that in the app, if we implement this granularity.

Also, I have started documenting the api here https://github.com/pmorrill/DendroicaAPI/blob/master/API_v1.md. The authentication and profile entrypoints are pretty well complete, though I have a ways to go with documenting the data request entrypoints.