Public:Bwmeta service/Tutorial

From YaddaWiki

Revision as of 07:36, 13 March 2013

This page describes how to create completly new bwmeta docuemnt using Y model. Docuemnt described in this example describes some article.

After setting all libraries, getting all imports, let's first create the new Empty YElement.

		YElement article = new YElement(); 

Elements are used for all bliographic objects - books, chapters, articles, journals etc...

This is equal to creating new empty bwmeta element in xml:

 <element xmlns="http://yadda.icm.edu.pl/bwmeta-2.x.x.xsd">
 
 </element>

While we don't specify verion of bwmeta we marked xsd with x.x - it could be now 2.0.0 or 2.1.0.

When we got article let's assign id to it:

           article.setId("bwmeta1.element.element-form-pubmed-0000"/*PBMID*/+"22222");

Ids should be unique. They should be recognized by regexp: [A-Za-z0-9_./:@\-]+ Current practices applying to id are described here. After this our xml would look like:

<element xmlns="http://yadda.icm.edu.pl/bwmeta-2.x.x.xsd" id="bwmeta1.element.element-form-pubmed-000022222">
 
 </element>

After setting id lets set title of article. For describing titles we use YName.

            YName nam=new YName();
            nam.setText("Tytuł artykułu");
            nam.setLanguage(YLanguage.English);
            nam.setType(YConstants.NM_CANONICAL);
//          nam.setType(YConstants.NM_SUBTITLE);
            article.addName(nam);
              

Name with type canonical for article is a main title. Additionally for article we could set sub and super title etc...

It would add to our element field name:

 <element xmlns="http://yadda.icm.edu.pl/bwmeta-2.x.x.xsd" id="bwmeta1.element.element-form-pubmed-000022222">
   <name lang="eng" type="canonical">
       Tytuł artykułu
   </name>
 </element>

For defining keywords and setting unknown categorizations YTagList should be used.

           YTagList slowaKluczoweMim=new YTagList();
           slowaKluczoweMim.setType("slowa_kluczowe_mim");
           slowaKluczoweMim.setType(YConstants.TG_KEYWORD);
   // type slowa_kluczowe mim wouldn't be used while it is overwritten with keyword
           slowaKluczoweMim.setLanguage(YLanguage.Polish);
           slowaKluczoweMim.addValue("ala");
           slowaKluczoweMim.setValues(null);
          

In XMl it would add element tags(from this point we would only show added element that should be child of element element):

  <tags lang="pol" type="keyword">
     <tag>ala</tag>
  </tags>
 

For define categories we use category-ref.

           article.addCategoryRef(new YCategoryRef(YConstants.EXT_CLASSIFICATION_MSC_2010, "67.23.+"));
           

There is a big question sometimes what to use - tag list or category ref. IN general category-refs should be used for categorization terms known in SYNAT system. While we identify them by codes, it is usually maeningless to put the code, that is not recognized in system. For all other types of categorization - and all tapes of keywords tag list should be used.

Now we describe contributor of the article:

           YContributor aut1=new YContributor(YConstants.CR_AUTHOR, false);
           aut1.addAffiliationRef("aff1");

Affiliation should be reference to some existing affiliation element inside this article.

           aut1.setRole(YConstants.CR_AUTHOR);

Other roles of contributor are: translator, editor, ilustrator etc...

           aut1.addName(new YName(YLanguage.Undetermined, "A.G. Drag",YConstants.NM_CANONICAL));

This should be the name in form that it apears on front page.

           aut1.addName(new YName(YLanguage.Undetermined, "A. G.", YConstants.NM_FORENAMES));
           aut1.addName(new YName(YLanguage.Undetermined, "Drag", YConstants.NM_SURNAME));

If author could be recognized by system - for eample if we can recognize other publications by same person, we could

           aut1.setIdentity("bwmeta1.person.person-000001"); 
           

Now lets define affiliation that contributor was referenced to.

          YAffiliation aff=new YAffiliation("aff1", "Uniwersytet Rzeszowski");
          article.addAffiliation(aff);
          

While we defined identity of person - here is example of this person element. It is not a part of article, but they could be serialized together.

           YPerson per=new YPerson();
           per.setId("bwmeta1.person.person-000001");
           per.addName(new YName(YLanguage.Undetermined, "Aleksandra Genofewa", YConstants.NM_FORENAMES));
           per.addName(new YName(YLanguage.Undetermined, "Drag-Kowalska", YConstants.NM_SURNAME));
         

Following code shows how to add abstract and summary to article.

           article.addDescription(new YDescription(YLanguage.English, "yadda yadda  ", YConstants.DS_ABSTRACT));
           article.addDescription(new YDescription(YLanguage.English, "yadda yadda  ", YConstants.DS_SUMMARY));
           

Below is shown method for adding citations.

           YRelation rel=new YRelation();
           rel.setType(YConstants.RL_REFERENCE_TO);
           rel.setTarget(new YId(YConstants.EXT_SCHEME_YADDA, "bwmeta1.element.element-docelowy-rel1"));
           rel.addAttribute(YConstants.AT_REFERENCE_TEXT, "text referencji 1");
           article.addRelation(rel);

YID set in target hasn;t to be YADDA id , it could be also doi , coden , etc...

Now definition of some strange element called structure. It is very important element. It defines hierarchy to which specified element belongs to. It also defines element level and element parents. Because element could be anything this place defines its nature. Our element is article and therfor ebelongs to hierarchy journal.

           YStructure struct=new YStructure(YConstants.EXT_HIERARCHY_JOURNAL);
           
           YAncestor anc=new YAncestor(YConstants.EXT_LEVEL_JOURNAL_JOURNAL);

In most cases other journal should be also in system so we could call its object by id ( its soft reference and is not checked). However in example we've commented it out.

       //    anc.setIdentity("bwmeta1.element.journal-issn-00000032324");
  
           anc.addName(new YName(YLanguage.English,"Journal of bibliography learning",YConstants.NM_CANONICAL));
           struct.addAncestor(anc);
           
           YAncestor anc2=new YAncestor(YConstants.EXT_LEVEL_JOURNAL_YEAR);
           //    anc2.setIdentity("bwmeta1.element.year-00000032324-2000");
  
           anc2.addName(new YName("2000"));
           struct.addAncestor(anc2);
           

Current element informs about what is the level of the element, In it we specify position of elment in its purent, ie. pages on which article appears in a journal.

           YCurrent current=new YCurrent(YConstants.EXT_LEVEL_JOURNAL_ARTICLE);
           current.setPosition("p.1-20");
           struct.setCurrent(current);
           
           article.addStructure(struct);
           

Here we use attribute for storing information about source of article. This source is some hint that could be used later for identification of journal in which appers article, then - we wouldn;t fill in parent level in structure.

           // jak zapisać  alternatywnie dla potrzbe przyszłego przetwarzania
           YAttribute st=new YAttribute("SOURCE", "JOU. B. LEARN.");            
           article.addAttribute(st);
 

Here is shown how to setup date. - there are various types of dates connected to article - publication, accepted ...

           YDate dat=new YDate(YConstants.DT_PUBLISHED, 2000, 1, 12, "druga połowa XX wieku");
           article.addDate(dat);

After serialization we obtain xml:

<?xml version="1.0" encoding="UTF-8"?>
<bwmeta xmlns="http://yadda.icm.edu.pl/bwmeta-2.1.0.xsd">
  <element id="bwmeta1.element.element-form-pubmed-000022222">
    <affiliation id="aff1">
     <text>Uniwersytet Rzeszowski</text>
    </affiliation>
    <attribute key="SOURCE">
     <value>JOU. B. LEARN.</value>
    </attribute>
    <category-ref classification="bwmeta1.category-class.MSC" code="67.23.+" />
    <contributor institution="false" role="author">
     <affiliation-ref ref="aff1" />
     <identity ref="bwmeta1.person.person-000001" />
     <name lang="und" type="canonical">A.G. Drag</name>
     <name lang="und" type="forenames">A. G.</name>
     <name lang="und" type="surname">Drag</name>
    </contributor>
    <date type="published" day="12" month="1" year="2000">druga połowa XX wieku</date>
    <description lang="eng" type="abstract">yadda yadda</description>
    <description lang="eng" type="summary">yadda yadda</description>
    <name lang="eng" type="canonical">Tytuł artykułu</name>
    <relation type="reference-to" id-scheme="bwmeta1.id-class.YADDA" id-value="bwmeta1.element.element-docelowy-rel1">
     <attribute key="reference-text">
       <value>text referencji 1</value>
     </attribute>
    </relation>
    <structure hierarchy="bwmeta1.hierarchy-class.hierarchy_Journal">
     <ancestor level="bwmeta1.level.hierarchy_Journal_Journal">
       <name lang="eng" type="canonical">Journal of bibliography learning</name>
     </ancestor>
     <ancestor level="bwmeta1.level.hierarchy_Journal_Year">
       <name lang="und">2000</name>
     </ancestor>
     <current level="bwmeta1.level.hierarchy_Journal_Article" position="p.1-20" />
    </structure>
  </element>
  <person id="bwmeta1.person.person-000001">
   <name lang="und" type="forenames">Aleksandra Genofewa</name>
   <name lang="und" type="surname">Drag-Kowalska</name>
  </person>
 </bwmeta>