text: # Welcome to examples.py with examples to get started with this package
  # The goal of this package is to provide you user-friendly commands to download and prepare bibliometrics data
  # most lines are comments, with every example on average just 3 lines of code
  # Let's get started
  
  # example 0: your first dataset
  # it is known bibliometrics data exists and is out there, but it needs to get on the computer
  # preferably without any manual actions like visiting websites and pressing download buttons
  # for this purpose, one can use API's (Application Programmable Interfaces) and
  # download data directly without leaving Python (hurray)
  # below a first dataset using Scopus
  #
  # first one must define a search query to tell Scopus which data is wanted (the entire corpus is simply too large)
  # this query asks Scopus to return records of publications with 'Gunes' in the author names and 'tensor' in the title.
  my_query = "AUTH(Gunes) AND TITLE(TENSOR)"
  #
  # Next this query must be sent to Scopus, through the API
  # There are two ways to do this: either by using general API commands or by using a 'wrapper'.
  # The 'wrapper' is a package of functions which simplifies the general API commands
  # One wrapper for scopus search is the following
  #
  # first we need to install some python packages to borrow functionality from
  # for example, we need an installation of pandas for processing dataframes
  # and numpy for mathematics
  # if this repository was copied to a computer with git clone, then
  # these installations must be done before continuing
  # for this, open either command prompt window or anaconda prompt window
  # then go to the location of your python installation or activate virtual 
  # environments if any,
  # and use pip install XX, where XX is the package name and version
  # the packages required by this toolbox are in requirements.txt
  # and pip installing them one by one will finish this task
  # Alternatively, once available, a pipy package can be downloaded which
  # will do all these installations automatically. This will be released in the future.
  #
  from pybliometrics.scopus import ScopusSearch
  # knowledge of python packages is assumed
  # if that command failed, install the package pybliometrics
  # during your first run an api-key will be asked, get one from scopus
  # hint: in production code always put all imports at the top
  #
  #
  # now send out the query
  # easy querying of Scopus
  s = ScopusSearch(my_query)
  # the variable s stores the results
  #
  # next we turn it into a pandas dataframe for easy handling
  # we use s.results to make the wrapper return the results in suitable format
  # and pandas for data handling
  import pandas as pd
  df = pd.DataFrame(s.results)
  #
  # now the data can be printed
  print(df.head())
  #
  # this wraps up how to get scopus dsta through python automatically
  
  
  # example 1: enriching your data with Altmetric
  # scopus is not everything
  # for example, it has no twitter mentions counts or not of sufficient quality
  # but a different API sercice named Altmetric does
  # so Altmetric can be used to 'enrich' Scopus records
  # then both information sources are combined
  #
  # Using our package, this is as simple as a single command
  from core_functions import add_altmetric_columns  # will be renamed later
  df = add_altmetric_columns(df)
  #
  # and that is all, now the dataframe df has altmetric information for every
  # record
  # the only requirement is that df has a column 'doi' and no overlapping columns
  # with the altmetric columns
  #
  # to summarize: only 1 function and 1 argument is needed to get Altmetric data
  
  # example 2: enriching your data with Unpaywall
  # Unpaywall is an API service for open access status of publications
  # tells if papers are free to read and what its url is amongst other things
  #
  # and again just a single function, import and call, done
  from core_functions import add_unpaywall_columns
  df = add_unpaywall_columns(df)
  #
  # these 2 lines enrich any dataframe with a doi column with unpaywall
  # furthermore, the function is optimized and will run 40x faster than usual
  # basically, the simple-python-bibliometrics package harvests unpaywall
  # roughly 40x faster than a basic code would do
  
  
  # more examples are underway
  # like scopus abstracts, author info processing, merging scopus with local
  # university/library repositories, and much more
  # also, an ETL with luigi will be prepared to run most common functions with a single call() : )
  
  
  