Research Profile
================

<toc/>



Introduction & overview
-----------------------

Research profile is one of the main parts of a personal record in ACIS.
It lists the research works that the person has authored or otherwise
took part in creation of.  Research works are usually documents:
articles or papers, but it can also be a book or a chapter in a book,
a software component, a series, et cetera.

At the same time, research profile is a part of the ACIS web interface
which is designed to let users manage their list of research works.

When a person includes a work into his or her <abbr 
title='research profile' >RP</abbr>, we oftern refer to the event as
"claiming"; we say, for instance, <i>the user claimed a document</i>.

ACIS maintains its own database of documents and other research items.
(We sometimes use a general word "resource" to refer to them.)  And
users do not have an ability to directly add their own stuff to the
document database.  The personal RPs can only include items that are
already present in the resource database.



Research Profile screens
------------------------

### Identified Items

The identified items screen lists all the currently-claimed works of a
person.  And it allows to remove items from the list, for example, to
fix a mistake of adding a wrong item.


### Automatic Suggestions

<a ref='rp-autosearch'>Automatic search</a> is the main procedure that
we execute to find works for a person's RP.  Automatic Suggestions
screen is where we show the results of the automatic search and let
user either accept them or not, individually.


### Refused Items

The refused items is a list of research items which should not be
suggested for inclusion into the person's RP.  It is a blacklist of
sorts.

The refused items screen lets user review the list and delete items for
it, if desired.  


### Manual Search

While <a ref='rp-autosearch'>automatic search</a> should find every
resource an ACIS service has for a person, sometimes the metadata is
not accurate.  This and other reasons mean that automatic search is not
always absolutely effective.  Therefore, we let users do their own
search by several different criteria: by the work title, by the
author/editor name, by record identifier.

On the Manual search screen users do those searches and handle their
results.


### Auto Update Preferences

ACIS provides <a href='apu.html'>APU</a> -- automatic profile update
service, which executes automatic research searches for a person even
when user is not directly asking that.  It may automatically add
closely matching items to the person's RP.  But if user doesn't want
that service, he can disable it on the Auto Update Preferences screen.


<h3 id='doclinks'>Document-to-Document Links</h3>

Document-to-document links is an advanced feature of RP.  It lets users
connect the works of their RP with each other, specifying the type of
relation between them.  For instance, many different works may be
different versions of the same research report.  Some work is a
continuation of an earlier one.  And so on.  

The range of possible relation types is defined by the system
administrator.

On the Document-to-document links screen users can review and delete
the links they have previously created and they can create new ones.

The links data are then exported in AMF with the user profile (if AMF
export is configured with <c>metadata-amf-output-dir</c>).  It may look like this

    <text ref="repec:wop:cirano:96s14">
      <follow-up xmlns="http://acis.openlib.org/2007/doclinks-relations">
        <text xmlns="http://amf.openlib.org" ref="repec:mit:worpap:382"/>
      </follow-up>
    </text>
    <text ref="repec:wop:epruwp:9701">
      <isreferencedby>
        <text ref="repec:wop:cirano:97s41"/>
      </isreferencedby>
    </text>


<h3 id='fturls'>Full-text URLs</h3>

Another advanced and optional feature of RP.  If you have full-text
links for your research works (articles, papers, etc.) but the data is
not 100% authoritative, you may ask the authors to review and flag
right and wrong links.  At the same time, you may ask them for their
permission to archive the full-text file (if it is correct).  Please
refer to the <a
href='http://acis.openlib.org/documents/textilshchiki.html'>Textilshchiki</a>
document, section <i>Full-text file recognition</i> for a better
description of the rationale for this feature.

The Full-text URLs screen shows the currently known URLs for each of
the RP items.  (There may be several URLs per item.)  And for each URL
it shows its current status.  If user made no decision about it yet,
then the assumed default status is shown.  Otherwise it shows the
latest user-made decision.  Thus user can review his or her previous
decisions and change them.

See <a ref='fturls-conf'>below</a> instructions on how to configure
the feature and on its input data format.

The collected data of users' decisions can then be exported out of ACIS
in a simple format:


#### <C>bin/export\_fturls\_choices</C> script

The script is for exporting data from the ft\_urls\_choices table (and
some related fields in other tables).  It outputs data on the standard
output in a simple tab-delimited one-record-per-line format.  The
following fields are included (in this order): 

- document id
- URL
- nature of the URL: <co>authoritative</co> (supplied in the primary metadata
  for the document) or <co>automatic</co> (automatically found via third-party
  tools)
- personal id (of the user who made the decision)
- the user's choice in the recognition menu, one of: <co>correct</co>,
  <co>abstractpage</co>, <co>wrong</co>, <co>anotherversion</co>
- the user's choice in the permission menu, one of: <co>mayarchive</co>,
  <co>checkupdates</co>, <co>notarchive</co> or an empty string
- the time when the decision was made (i.e. recordered by ACIS) in a
  simple YYYY-MM-DD HH:MM:SS format

The script may optinally accept one or two date parameters on the
command line.  With such parameters, script would only output decisions
taken in the given period.  If only one date is supplied, script
outputs all data from that day on.  The dates are expected in the
YYYY-MM-DD format.




### Main Research Profile screen

Displays a menu of all the screens with a brief introduction into each
and some general status information.  Provides a button to force
automatic search for the person with her current name variations.


<h2 id='rp-autosearch'>Automatic research search</h2>


### Exact searches

This is search by the person's name variations in the names of the
document authors (and editors).  As its name states, it finds exact
matches only.


### Additional searches

<h3 id='research-fuzzy'>Fuzzy name search</h3>

Features to find mistyped author (editor) names in the document 
metadata.  

This requires running <c>bin/fuzzy\_search\_table</c> utility every once
in a while and some <a ref='conf-fuzzy'>configuration</a>.

Find a detailed explanation of how this is supposed to work in the <a
href='http://acis.openlib.org/documents/textilshchiki.html'>Textilshchiki</a>
document, section <i>Fuzzy searching</i>.

#### <C>bin/fuzzy\_search_table</C> script

The script initializes the database tables which are needed for the
fuzzy name search to work.  Should be run regularly.  Depending on size
of your documents database, it may take a while to do its job.  

Takes no arguments and prints out its progress (the executed database
statements) to standard output.


<h2 id='rp-conf'>Configuration of the Research Profile and its screens</h2>

See all <a ref='conf-research'>research profile parameters</a>.


### Automatic search 

- <c>research-additional-searches</c>



<h3 id='research-doclinks'>Document-to-document links configuration</h3>

The whole feature has to be enabled with a
<c>document-document-links-profile</c> parameter.

The relation types have to be specified in an XML file
<f>doclinks.conf.xml</f> in the ACIS installation directory.  The file
has a simple structure; a self-explanatory example file is supplied in
<f>doclinks.conf.xml.eg</f>.


<h3 id='fturls-conf'>Full-text URLs configuration</h3>

The whole feature won't be there unless you have enabled it with a
<c>full-text-urls-recognition</c> parameter.

The input data format is AMF-based.  The authoritative URLs:

    <text id=".."> 
     <file>
      <url>url</url>
     </file>
    </text>

Automatically found URLs:

    <text id=".."> 
     <hasversion>
      <text>
       <file>
        <url>url</url>
       </file>
      </text>
     </hasversion>
    </text>

If you have full-text URLs data separate from the document data,
configure it as a special metadata collection in main.conf.  Use
<co>FullTextUrlsAMF</co> as its type.  E.g. this collection is named
'URLs':

    metadata-collections="Papers URLs ..."
    metadata-Papers-home=/path/to/Papers
    metadata-Papers-type=AMF
    metadata-URLs-home=/path/to/URLs/data
    metadata-URLs-type=FullTextUrlsAMF
    ...

Before this data becomes available to users, it has to be processed
with the update daemon.  You have to explicitly request an update (see
<c>bin/updareq</c>).


### Fuzzy search

- <c>fuzzy-name-search</c>
- <c>fuzzy-name-search-min-common-prefix</c>
- <c>fuzzy-name-search-min-variation-length</c>
- <c>fuzzy-name-search-max-name-occurr-in-doc-names</c>
- <c>fuzzy-name-search-max-name-occurr-in-name-variations</c>
- <c>fuzzy-name-search-via-web</c>


<h2 id='rp-tech'>Selected technical details</h2>

### Technical: database tables

#### <co>resources</co>

    +----------+--------------+------+-----+---------+-------+
    | Field    | Type         | Null | Key | Default | Extra |
    +----------+--------------+------+-----+---------+-------+
    | id       | varchar(255) |      | PRI |         |       |
    | sid      | varchar(15)  |      | MUL |         |       |
    | type     | varchar(20)  |      |     |         |       |
    | title    | varchar(255) |      | MUL |         |       |
    | classif  | varchar(50)  | YES  |     | NULL    |       |
    | location | text         | YES  |     | NULL    |       |
    | authors  | text         | YES  |     | NULL    |       |
    | urlabout | text         | YES  |     | NULL    |       |
    +----------+--------------+------+-----+---------+-------+


#### <co>rp_suggestions</co>

    +--------+----------+------+-----+---------------------+-------+
    | Field  | Type     | Null | Key | Default             | Extra |
    +--------+----------+------+-----+---------------------+-------+
    | psid   | char(15) |      | PRI |                     |       |
    | dsid   | char(15) |      | PRI |                     |       |
    | role   | char(15) |      |     |                     |       |
    | reason | char(30) |      |     |                     |       |
    | time   | datetime |      |     | 0000-00-00 00:00:00 |       |
    +--------+----------+------+-----+---------------------+-------+
 

#### <co>ft_urls</co>

- dsid char(15) not null
- url blob not null 
- checksum char(16) binary not null
- nature ENUM(\'authoritative\',\'automatic\') not null
- source varchar(255) not null

<co>PRIMARY KEY( dsid, checksum ), index url\_i(url(30)), index
source\_i(source(50))</co>


#### <co>ft_urls\_choices</co>

- dsid char(15) not null
- checksum char(16) binary not null
- psid char(15) not null
- choice char(2) not null -- first char: d|y|r|n (corresponding menu items:
   2|4|3|1); second char: y|c|n (1|2|3) 
- time datetime not null

<co>primary key prim(dsid, checksum, psid), index t\_i(time), index psid\_i(psid)</co>





### Technical: code structure

Core modules:

- ACIS::Resources
- ACIS::Resources::Search
- ACIS::Resources::AutoSearch
- ACIS::Resources::Suggestions
- ACIS::Resources::SearchFuzzy
- ACIS::Web::Contributions

<a href='apu.html'>APU</a> modules:

- ACIS::APU
- ACIS::APU::Queue
- ACIS::APU::RP

Document to document links:

- ACIS::DocLinks
- ACIS::Web::DocLinks

Full-text URLs:

- ACIS::FullTextURLs
- ACIS::FullTextURLs::Input






<id>$Id: researchprofile.text,v 2.11 2007/07/06 21:57:00 ivan Exp $</id>


