К оглавлению курса

Структура проекта

Как и во многих исследовательских проектах, первым шагом в анализе закона Ципфа является загрузка данных и установка необходимого программного обеспечения (далее - ПО). Прежде чем это сделать, стоит подумать, как мы собираемся организовать проект. Скоро у нас появится ряд книг из Project Gutenberg в виде набора текстовых файлов, созданных нами графиков, показывающих частотное распределение слов в каждой книге, а также программного кода, который мы напишем для создания этих графиков. Такой набор файлов может привести к путанице.

При создании проекта для проверки закона Ципфа мы будем следовать широко используемому шаблону для организации небольших проектов по анализу данных. Проект будет жить в каталоге с именем zipf, который одновременно будет репозиторием Git, хранящимся на GitHub (об этом позже). Ниже приведена сокращенная версия дерева каталогов проекта в том виде, в каком она появляется ближе к концу курса:

zipf/
├── .gitignore
├── CITATION.md
├── CONDUCT.md
├── CONTRIBUTING.md
├── LICENSE.md
├── README.md
├── Makefile
├── bin
│   ├── book_summary.sh
│   ├── collate.py
│   ├── countwords.py
│   └── ...
├── data
│   ├── README.md
│   ├── dracula.txt
│   ├── frankenstein.txt
│   └── ...
├── docs
│   └── ...
├── results
│   ├── collated.csv
│   ├── dracula.csv
│   ├── dracula.png
│   └── ...
└── ...

Стандартная информация

Наш проект будет содержать несколько стандартных файлов, которые должны присутствовать в каждом проекте исследовательского ПО:

• README включает в себя основную информацию о проекте.
• LICENSE является лицензией проекта.
• CONTRIBUTING объясняет, как внести свой вклад в проект.
• CONDUCT включает правила поведения, описываются процедуры решения проблем между членами сообщества проекта.
• CITATION объясняет, как цитировать программное обеспечение.

Некоторые проекты также включают файл CONTRIBUTORS или AUTHORS, в котором перечислены все, кто внес свой вклад в проект, в то время как другие проекты включают эту информацию в README.

Организация содержания проекта

Каталоги проекта организованы в соответствии с их целью:

• Запускаемые исполняемые файлы хранятся в bin (это старая Unix-аббревиатура для "бинарный", что означает "не текстовый"). Каталог будет включать как сценарии оболочки, например, book_summary.sh, так и программы на Python, например countwords.py.
• Необработанные данные поступают в data и никогда не изменяются после сохранения.
• В некоторых проектах каталог data удобно разбить на несколько подкаталогов:

  
  ├── data               # Каталог с данными
  │   ├── interim        # Рабочий каталог для временных файлов
  │   ├── processed      # Очищенные данные, готовые к анализу
  │   └── raw            # Оригинальные (сырые) данные (никогда не должны изменяться)
  

• Результаты помещаются в results (иногда называют reports). Сюда входят очищенные данные, рисунки и др., созданное с использованием содержимого каталогов bin и data.
• Наконец, документация помещается в docs. В нашем проекте docs будет содержать автоматически сгенерированную документацию для Python пакета.

Эта структура хорошо работает для многих вычислительных исследовательских проектов. Мы добавим еще несколько каталогов и файлов, когда будем говорить о тестировании и упаковке.

Загрузка данных

Файлы данных, используемые в курсе, заархивированы в онлайн-хранилище под названием Figshare, и к ним можно получить доступ по адресу.

Можно загрузить zip-файл, содержащий файлы данных, нажав "Download all" по этому URL-адресу, а затем разархивировав содержимое в новый каталог zipf/data, который соответствует структуре проекта, описанной выше:

zipf/
└── data
    ├── README.md
    ├── dracula.txt
    ├── frankenstein.txt
    ├── jane_eyre.txt
    ├── moby_dick.txt
    ├── sense_and_sensibility.txt
    ├── sherlock_holmes.txt
    └── time_machine.txt

Установка программного обеспечения

Для проведения анализа необходимо установить следующее ПО.

1. Оболочку Bash
2. Систему контроля версий Git
3. Дистрибутив Anaconda
4. Anaconda уже включает IDE Spyder (текстовый редактор) для запуска Python-скриптов, поэтому будем использовать его
5. GNU Make

Подробные инструкции по установке ПО для операционных систем Windows, Mac и Linux (с видеоуроками) доступны по адресу.

Можно следовать этим инструкциям, чтобы установить оболочку Bash, Git и Anaconda. Рекомендуем дистрибутив Anaconda в качестве способа установки Python, так как он уже включает в себя пакеты, которые мы будем использовать в этом курсе.

Вы можете проверить, установлен ли Make на вашем компьютере, введя команду make -v в оболочке Bash.

Альтернативный способ: в новых версиях ОС Windows можно установить Linux с помощью WSL и на него установить Bash и Git.

Упражнение

Прежде чем переходить к следующей главе, убедитесь, что вы загрузили необходимые файлы данных и установили необходимое ПО.

Дополнительно

• Утилита Cookiecutter для создания шаблона проекта
• Cookiecutter для проектов Data Science в Jupyter Lab
• Шаблон cookiecutter на русском языке для анализа данных в Jupyter Lab

Обсудить публикацию в [Telegram-канале]

"Research Software Engineering with Python. Building software that makes research possible"
by Damien Irving, Kate Hertweck, Luke Johnston, Joel Ostblom, Charlotte Wickham, Greg Wilson
https://merely-useful.tech/py-rse/
CC-BY 4.0 и MIT License.