01.Rmd

# Вовед {#intro}

Во овој текст правиме краток преглед и даваме основни препораки за безбедна пракса при ракување, анализирање, и објавување на податоци. Под „безбедна пракса“ подразбираме чекори коишто доколку ги следиме ќе имаме некаква сигурност дека нашата анализа ќе може да биде повторена во друг контекст (друг компјутер, друга организација, после една година, итн) давајќи ги истите резултати. За оваа цел, потребни е да размислуваме за тоа како наједноставно и најбезбедно да ги споделиме нашите податоци, процедури, и програмски код _заедно_ со самите резултати. Инаку, нема никаква надеж дека нашите резултати ќе можат да се повторат.

Се чини дека оваа поента е доволно очигледна и некој би рекол дека воопшто нема потреба да се зборува за ова. Сите се согласуваме со тоа дека кога некоја наша колешка ќе направи некаква анализа, ние, доколку имаме доволно информации за нејзината анализа, можеме да ја повториме и да ги добиеме _истите_ резултати. Но во пракса оваа удобна идеја ретко кога се остварува [@minocher2020]. Наместо повторливост, кога се обидуваме да повториме некоја анализа вообичаено е да се соочиме со забуна и фрустрација. Ова често завршува со откажување или правење на анализата од почеток, односно, бесполезно и контрапродуктивно губење на време, ресурси и пари. За брз вовед во овие проблеми и значајноста на повторливоста во истражувањето, ви го препорачуваме [ова видео](https://www.youtube.com/watch?v=zwRdO9_GGhY&t=14s) од [Ричард МкЕлреат](https://xcelab.net/rm/). 

Горната дефиниција на „безбедна пракса“ (без преправање дека ова е некаква прецизна дефиниција) повикува барем две дополнителни поенти за тоа што подразбира да анализираме податоци и да објавуваме резултати на начин што овозможува точно повторување. Имено, објавувањето на резултат мора да биде поддржано со објавување на 1) точните податоци коишто биле употребени да се направи анализата, и 2) деталната процедура којашто била извршена за да се добие резултатот. Подоцна ќе видиме зошто се неопходни овие компоненти (иако веруваме дека е горе-доле очигледно) и на кој начин е најдобро да се презентираат/објават.

Тука е можеби полезно да направиме разлика помеѓу повторливоста која ја опишуваме до сега и еден друг тип на повторливост што има нешто поголема фундаменталност и тежина. Во природните науки, кога зборуваме дека нешто е научна вистина или научно знаење, тоа скоро секогаш се однесува на резултати коишто се повторливи и коишто можат да се докажат од различни агли. Дали почнувајќи со различни податоци, или со поставување на нови експерименти, или со употреба на поинакви анализи, критично е да дојдеме до истиот резултат за тој да биде прифатен како една компонента од тоа како светот функционира (научна вистина). На пример, дека Земјата е сферична може да се докаже со податоци од циркумнавигација, со мерење на аголот на сончевите зраци на различни географски локации, со движењето на Фуковото нишало, со самото постоење на ГПС навигација, со фотографии од возила во орбитата, и така натаму. Значи истиот резултат можеме да го изведеме од многу различни податоци и методи. За разлика од ваквата репликација, фокусот на овој текст е поскромен, и се однесува на далеку полесниот концепт на повторување на истиот рецепт, со истите состојки, за да ја направиме истата пита. 

## Аналогија {#analogy}

Проширување на горната аналогија е добар начин да се запознаеме со главните компоненти на повторливата обработка на податоци. Кога правиме пита, имаме состојки (брашно, квасец, спанаќ, сирење), рецепт од неколку чекори (нарасни го квасецот, замеси тесто, засукај кори), и неопходни алатки (лонче, тарун, тепсија, фурна). Кога сакаме да ја направиме истата пита што ја прави бабата на нашиот пријател, треба да ги имаме сите состојки, информации за сите чекори за подготовка како и сите алатки. Ако имаме брашно, вода и сол ама сме заборавиле квасец, нема да може да замесиме тесто. Ако немаме сукало, ќе треба да тегнеме кори, што секако ќе значи поинаква пита. Значи, за да ја повториме питата потребно е да ги имаме сите неопходни елементи и инфмормации коишто ќе овозможат точно повторување на секој чекор. Затоа не е чудно што рецепти за готвење често доаѓаат со слики или видео. Тоа се медиуми побогати со информации и затоа поадекватни за пренесување комплексни процеси како правење пита. Без разлика од тоа колку детално некој опишал како се сука кора со радиус од 25 cm, со видео од процесот ние добиваме далеку подобро разбирање за процедурата. 

Во сферата на анализа за податоци, аналозите на горните компоненти се:

   - податоците ~ состојки  
   - изворниот код ~ рецепт и   
   - софтверски пакети од коишто зависи нашиот код ~ алатки  
   
На пример, ако правиме анализа на невработеност низ Северна Македонија и имаме една табела со невработеност по општини но сме ги групирале податоците по градови користејќи друга табела, тогаш за точна репликација на нашата анализа треба да ги споделиме двете табели (и брашното и квасецот). Слично, за некој да ги направи истите графици за невработеност по град, треба да го споделиме и нашиот код за правење на анализата (рецептот), како и информации за софтверот во којшто сме го извршиле тој програмски код (тарунот). Некогаш тарунот не е неопходен за да се направи истата пита, можеби само температурата на фурната е битна, и во ваквите случаи можеме да го споделиме рецептот без рестрикција за алатката што треба да се користи. Но во други случаи, дури и да се достапни точните податоци и документираниот изворен код, анализата не може да се повтори без некоја специјална алатка. Во овие случаи ние би требало да ги спакуваме и споделиме дури и нашите алатки. 

За среќа, аналогијата помеѓу правење пита и повторување на некоја анализа завршува со споделување на податоците, кодот, и информации за алатките. Имајќи пристап до овие компоненти, дури и никогаш да не сте правеле некаква специфична анализа во некој специфичен софтвер, вие сепак ќе можете да ги извршите истите документирани чекори и да дојдете до истиот резултат. Повторувањето на анализата не бара пракса, умешност, искуство и не зависи од тоа колку е влажно брашното. Ако креирањето повторливи документи или анализи ви звучеше како комплициран концепт, се надеваме дека со оваа аналогија станува јасно дека е далеку полесно од обидот да се направи пита како како бабата на пријателот или пица како од ресторан. 

## За кого е наменет овој прирачник {#audience}

Краткиот одговор е: На секој што работи во сферата на истражување, статистика, наука за податоци, за секој што е студент во овие струки, и за секој што е претпоставен на луѓе кои работат во овие и слични струки. Со други зборови, доколку работите со податоци, и некогаш сте се нашле во ситуација кога некој колега, претпоставен, ментор, соработник, донор, рецензент, едитор, новинар, политичар, итн, ве прашал за тоа како може да се повторат или потврдат вашите резултати, тогаш веројатно има нешто во овој прирачник што би ви било од корист. Да разгледаме некои примери.

Пример 1: Работите во невладина организација чијшто фунцкионирање зависи од надворешни грантови, како од македонски така и од странски извори. Се почесто, донорите поставуаат услови за активностите кои тие ги подджуваат, дека сите податоци кои вашата организација ги собира (преку анкети, истражувања, и контакти) како и сите анализи на тие податоци треба да се транспарентни и повторливи. Што во пракса значи дека со завршниот извештај за проектот во кој ги презентирате резултатите, вие ќе треба исто така да покажете јавна депозиција на податоците и изворниот код користен да се добиат презентираните резултати. Со други зборови, пред вас е задача за повторлива анализа

Пример 2: Работите во индустриска лабораторија каде што вашата работа е да правите статистичка обработка на експериментални резултати или анализи за контрола на квалитет. Вашата организација повторно фунцкионира преку надворешни грантови или клиенти кои очекуваат дека резултатите од вашата лабораторија ќе може да бида независно потврдени. Во пракса ова повторно значи објавување на повторлив проект, со податоци и програмски код, кој што ќе фунцкионира во контекст многу различен од вашата лабораторија.

Пример 3: Накратко, бидејќи патернот е јасен. Вие сте научен истражувач на некој универзитет или институт. Вашата работа зависи од објавување трудови и аплицирање за грантови. Се поголем број на научни журнали имаат стриктни барања за транспарентни и повторливи анализи без кои нема ни да го рецензираат трудот. Вас ви треба повторлив проект.

Веројатно е полесно да се зборува за кого овој прирачник _не е_ корисен? Доколку се чувствувате како експерт по сите алатки спомнати во Поглавје \@ref(tools), тогаш веројатно нема да научите многу од овој текст. Сепак, овој прирачник наменет за почетници или искусни истражувачи но без пракса за повторливи анализи. Но тоа не значи дека не можете да помогнете со пријателска рецензија или со подобрување на некое поглавје каде што чувствувате дека има простор за значајно подобрување.

## Организација {#organ}

Темата на овој текст е доволно опширна што тука нема ни да се обидеме да дадеме севкупен третмант на сите значајни аспекти. Туку, целта е да дадеме преглед на главните принципи за повторливи анализи и практични примери за главните препораки.

По воведот, прво ќе се запознаеме со софтверските алатки кои ќе ги користиме понатаму (Поглавје \@ref(tools): Алатки), и ќе посочиме некои од најчестите случаи кога една анализа, дури и да имаме најдобри намери, може да биде “неповторлива“ (Поглавје \@ref(nogood): Aнализи што не може да се повторат). Понатаму ќе ги разгледаме главните начини на кои постоечки код за некоја анализа која е тешка да се повтори може да се конвертира во повторлива анализа (Поглавје \@ref(conversion): Конверзија во повторлив код). Следи вовед во таканаречено „писмено програмирање“, односно пишување на документи коишто ги покажуваат нашите размислувањa, претпоставки, хипотези, заедно со кодот што го користиме за нивно тестирање и резултатите од тие тестови (Поглавје \@ref(rmd): Повторливи документи / извештаи). Во Поглавје \@ref(proekti) ќе видиме како да организираме еден поголем проект, со неколку различни извори на податоци, скрипти, извештаи и резултати, во еден пакет со документација и стандардна структура што е лесна да се следи и користи. За крај, ќе зборуваме за контола на изворниот код со `git` што ни дава слобода и безбедност за променување и подобрување (Поглавје \@ref(git): Контрола на изворниот код). Текстот го затвораме со заклучок и литература со препорака во најмала рака да ги погледнете ресурсите дадени во библиографијата бидејќи содржат далеку подетални и ефективни третмани на темата на повторливо ракување, анализирање и објавување на податоци.

## Подобрувања и коментари

Изворниот код за овој прирачник е [достапен](https://github.com/discindo/booklet/) на `GitHub`. Сите предлози за подобрувања, коментари или пријавување на печатни грешки може да се направат на страницата на репозиториумот преку [пријавување на проблем](https://github.com/discindo/booklet/issues), [отворање на дискусија](https://github.com/discindo/booklet/discussions) или [создавање на pull request](https://github.com/discindo/booklet/pulls).

## За овој прирачник 

Овој прирачник е изработен како дел од проектот „Отворени податоци за отворена иднина“, поддржан од програмата Цивика Мобилитас, а спроведен од Слободен софтвер Македонија.

![](www/banner-photo.png)

Содржината на овој прирачник е единствена одговорност на Слободен софтвер Македонија и на ниту еден начин не може да се смета дека ги одразува гледиштата на Цивика мобилитас, Швајцарската агенција за развој и соработка (SDC) или организациите што ја спроведуваат.

## Лиценца

Прирачникот е објавен под лиценцата [GNU GENERAL PUBLIC LICENSE, Version 3](https://www.gnu.org/licenses/gpl-3.0.en.html). Целиот текст на лиценцата е достапен во изворниот код на овој прирачник.